1// Copyright 2013 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef FLUTTER_FML_TRACE_EVENT_H_
6#define FLUTTER_FML_TRACE_EVENT_H_
7
8#include <functional>
9
10#include "flutter/fml/build_config.h"
11
12#if defined(OS_FUCHSIA)
13
14// Forward to the system tracing mechanism on Fuchsia.
15
16#include <lib/trace/event.h>
17
18// TODO(DNO-448): This is disabled because the Fuchsia counter id json parsing
19// only handles ints whereas this can produce ints or strings.
20#define FML_TRACE_COUNTER(a, b, c, arg1, ...) \
21 ::fml::tracing::TraceCounterNopHACK((a), (b), (c), (arg1), __VA_ARGS__);
22
23#define FML_TRACE_EVENT(a, b, args...) TRACE_DURATION(a, b)
24// On Fuchsia, the flow_id arguments to this macro are ignored.
25#define FML_TRACE_EVENT_WITH_FLOW_IDS(category_group, name, flow_id_count, \
26 flow_ids, ...) \
27 FML_TRACE_EVENT(category_group, name)
28
29#define TRACE_EVENT0(a, b) TRACE_DURATION(a, b)
30// On Fuchsia, the flow_id arguments to this macro are ignored.
31#define TRACE_EVENT0_WITH_FLOW_IDS(category_group, name, flow_id_count, \
32 flow_ids) \
33 TRACE_EVENT0(category_group, name)
34#define TRACE_EVENT1(a, b, c, d) TRACE_DURATION(a, b, c, d)
35// On Fuchsia, the flow_id arguments to this macro are ignored.
36#define TRACE_EVENT1_WITH_FLOW_IDS(category_group, name, flow_id_count, \
37 flow_ids, arg1_name, arg1_val) \
38 TRACE_EVENT1(category_group, name, arg1_name, arg1_val)
39#define TRACE_EVENT2(a, b, c, d, e, f) TRACE_DURATION(a, b, c, d, e, f)
40#define TRACE_EVENT_ASYNC_BEGIN0(a, b, c) TRACE_ASYNC_BEGIN(a, b, c)
41// On Fuchsia, the flow_id arguments to this macro are ignored.
42#define TRACE_EVENT_ASYNC_BEGIN0_WITH_FLOW_IDS(category_group, name, id, \
43 flow_id_count, flow_ids) \
44 TRACE_EVENT_ASYNC_BEGIN0(category_group, name, id)
45#define TRACE_EVENT_ASYNC_END0(a, b, c) TRACE_ASYNC_END(a, b, c)
46#define TRACE_EVENT_ASYNC_BEGIN1(a, b, c, d, e) TRACE_ASYNC_BEGIN(a, b, c, d, e)
47#define TRACE_EVENT_ASYNC_END1(a, b, c, d, e) TRACE_ASYNC_END(a, b, c, d, e)
48#define TRACE_EVENT_INSTANT0(a, b) TRACE_INSTANT(a, b, TRACE_SCOPE_THREAD)
49#define TRACE_EVENT_INSTANT1(a, b, k1, v1) \
50 TRACE_INSTANT(a, b, TRACE_SCOPE_THREAD, k1, v1)
51#define TRACE_EVENT_INSTANT2(a, b, k1, v1, k2, v2) \
52 TRACE_INSTANT(a, b, TRACE_SCOPE_THREAD, k1, v1, k2, v2)
53
54#endif // defined(OS_FUCHSIA)
55
56#include <cstddef>
57#include <cstdint>
58#include <string>
59#include <type_traits>
60#include <vector>
61
62#include "flutter/fml/macros.h"
63#include "flutter/fml/time/time_point.h"
64#include "third_party/dart/runtime/include/dart_tools_api.h"
65
66#if (FLUTTER_RELEASE && !defined(OS_FUCHSIA) && !defined(FML_OS_ANDROID))
67#define FLUTTER_TIMELINE_ENABLED 0
68#else
69#define FLUTTER_TIMELINE_ENABLED 1
70#endif
71
72#if !defined(OS_FUCHSIA)
73#ifndef TRACE_EVENT_HIDE_MACROS
74
75#define __FML__TOKEN_CAT__(x, y) x##y
76#define __FML__TOKEN_CAT__2(x, y) __FML__TOKEN_CAT__(x, y)
77#define __FML__AUTO_TRACE_END(name) \
78 ::fml::tracing::ScopedInstantEnd __FML__TOKEN_CAT__2(__trace_end_, \
79 __LINE__)(name);
80
81// This macro has the FML_ prefix so that it does not collide with the macros
82// from lib/trace/event.h on Fuchsia.
83//
84// TODO(chinmaygarde): All macros here should have the FML prefix.
85#define FML_TRACE_COUNTER(category_group, name, counter_id, arg1, ...) \
86 ::fml::tracing::TraceCounter((category_group), (name), (counter_id), (arg1), \
87 __VA_ARGS__);
88
89// Avoid using the same `name` and `argX_name` for nested traces, which can
90// lead to double free errors. E.g. the following code should be avoided:
91//
92// ```cpp
93// {
94// TRACE_EVENT1("flutter", "Foo::Bar", "count", "initial_count_value");
95// ...
96// TRACE_EVENT_INSTANT1("flutter", "Foo::Bar",
97// "count", "updated_count_value");
98// }
99// ```
100//
101// Instead, either use different `name` or `arg1` parameter names.
102#define FML_TRACE_EVENT_WITH_FLOW_IDS(category_group, name, flow_id_count, \
103 flow_ids, ...) \
104 ::fml::tracing::TraceEvent((category_group), (name), (flow_id_count), \
105 (flow_ids), __VA_ARGS__); \
106 __FML__AUTO_TRACE_END(name)
107
108// Avoid using the same `name` and `argX_name` for nested traces, which can
109// lead to double free errors. E.g. the following code should be avoided:
110//
111// ```cpp
112// {
113// TRACE_EVENT1("flutter", "Foo::Bar", "count", "initial_count_value");
114// ...
115// TRACE_EVENT_INSTANT1("flutter", "Foo::Bar",
116// "count", "updated_count_value");
117// }
118// ```
119//
120// Instead, either use different `name` or `arg1` parameter names.
121#define FML_TRACE_EVENT(category_group, name, ...) \
122 FML_TRACE_EVENT_WITH_FLOW_IDS((category_group), (name), \
123 /*flow_id_count=*/(0), /*flow_ids=*/(nullptr), \
124 __VA_ARGS__)
125
126#define TRACE_EVENT0_WITH_FLOW_IDS(category_group, name, flow_id_count, \
127 flow_ids) \
128 ::fml::tracing::TraceEvent0(category_group, name, flow_id_count, flow_ids); \
129 __FML__AUTO_TRACE_END(name)
130
131#define TRACE_EVENT0(category_group, name) \
132 TRACE_EVENT0_WITH_FLOW_IDS(category_group, name, /*flow_id_count=*/0, \
133 /*flow_ids=*/nullptr)
134
135#define TRACE_EVENT1_WITH_FLOW_IDS(category_group, name, flow_id_count, \
136 flow_ids, arg1_name, arg1_val) \
137 ::fml::tracing::TraceEvent1(category_group, name, flow_id_count, flow_ids, \
138 arg1_name, arg1_val); \
139 __FML__AUTO_TRACE_END(name)
140
141#define TRACE_EVENT1(category_group, name, arg1_name, arg1_val) \
142 TRACE_EVENT1_WITH_FLOW_IDS(category_group, name, /*flow_id_count=*/0, \
143 /*flow_ids=*/nullptr, arg1_name, arg1_val)
144
145#define TRACE_EVENT2(category_group, name, arg1_name, arg1_val, arg2_name, \
146 arg2_val) \
147 ::fml::tracing::TraceEvent2(category_group, name, /*flow_id_count=*/0, \
148 /*flow_ids=*/nullptr, arg1_name, arg1_val, \
149 arg2_name, arg2_val); \
150 __FML__AUTO_TRACE_END(name)
151
152#define TRACE_EVENT_ASYNC_BEGIN0_WITH_FLOW_IDS(category_group, name, id, \
153 flow_id_count, flow_ids) \
154 ::fml::tracing::TraceEventAsyncBegin0(category_group, name, id, \
155 flow_id_count, flow_ids);
156
157#define TRACE_EVENT_ASYNC_BEGIN0(category_group, name, id) \
158 TRACE_EVENT_ASYNC_BEGIN0_WITH_FLOW_IDS( \
159 category_group, name, id, /*flow_id_count=*/0, /*flow_ids=*/nullptr)
160
161#define TRACE_EVENT_ASYNC_END0(category_group, name, id) \
162 ::fml::tracing::TraceEventAsyncEnd0(category_group, name, id);
163
164#define TRACE_EVENT_ASYNC_BEGIN1(category_group, name, id, arg1_name, \
165 arg1_val) \
166 ::fml::tracing::TraceEventAsyncBegin1( \
167 category_group, name, id, /*flow_id_count=*/0, /*flow_ids=*/nullptr, \
168 arg1_name, arg1_val);
169
170#define TRACE_EVENT_ASYNC_END1(category_group, name, id, arg1_name, arg1_val) \
171 ::fml::tracing::TraceEventAsyncEnd1( \
172 category_group, name, id, /*flow_id_count=*/0, /*flow_ids=*/nullptr, \
173 arg1_name, arg1_val);
174
175#define TRACE_EVENT_INSTANT0(category_group, name) \
176 ::fml::tracing::TraceEventInstant0( \
177 category_group, name, /*flow_id_count=*/0, /*flow_ids=*/nullptr);
178
179#define TRACE_EVENT_INSTANT1(category_group, name, arg1_name, arg1_val) \
180 ::fml::tracing::TraceEventInstant1( \
181 category_group, name, /*flow_id_count=*/0, /*flow_ids=*/nullptr, \
182 arg1_name, arg1_val);
183
184#define TRACE_EVENT_INSTANT2(category_group, name, arg1_name, arg1_val, \
185 arg2_name, arg2_val) \
186 ::fml::tracing::TraceEventInstant2( \
187 category_group, name, /*flow_id_count=*/0, /*flow_ids=*/nullptr, \
188 arg1_name, arg1_val, arg2_name, arg2_val);
189
190#define TRACE_FLOW_BEGIN(category, name, id) \
191 ::fml::tracing::TraceEventFlowBegin0(category, name, id);
192
193#define TRACE_FLOW_STEP(category, name, id) \
194 ::fml::tracing::TraceEventFlowStep0(category, name, id);
195
196#define TRACE_FLOW_END(category, name, id) \
197 ::fml::tracing::TraceEventFlowEnd0(category, name, id);
198
199#endif // TRACE_EVENT_HIDE_MACROS
200#endif // !defined(OS_FUCHSIA)
201
202#define TRACE_EVENT2_INT(category_group, name, arg1_name, arg1_val, arg2_name, \
203 arg2_val) \
204 const auto __arg1_val_str = std::to_string(arg1_val); \
205 const auto __arg2_val_str = std::to_string(arg2_val); \
206 TRACE_EVENT2(category_group, name, arg1_name, __arg1_val_str.c_str(), \
207 arg2_name, __arg2_val_str.c_str());
208
209namespace fml {
210namespace tracing {
211
212using TraceArg = const char*;
213using TraceIDArg = int64_t;
214
215void TraceSetAllowlist(const std::vector<std::string>& allowlist);
216
217typedef void (*TimelineEventHandler)(const char*,
218 int64_t,
219 int64_t,
220 intptr_t,
221 const int64_t*,
222 Dart_Timeline_Event_Type,
223 intptr_t,
224 const char**,
225 const char**);
226
227using TimelineMicrosSource = int64_t (*)();
228
229void TraceSetTimelineEventHandler(TimelineEventHandler handler);
230
231bool TraceHasTimelineEventHandler();
232
233void TraceSetTimelineMicrosSource(TimelineMicrosSource source);
234
235int64_t TraceGetTimelineMicros();
236
237void TraceTimelineEvent(TraceArg category_group,
238 TraceArg name,
239 int64_t timestamp_micros,
240 TraceIDArg id,
241 size_t flow_id_count,
242 const uint64_t* flow_ids,
243 Dart_Timeline_Event_Type type,
244 const std::vector<const char*>& names,
245 const std::vector<std::string>& values);
246
247void TraceTimelineEvent(TraceArg category_group,
248 TraceArg name,
249 TraceIDArg id,
250 size_t flow_id_count,
251 const uint64_t* flow_ids,
252 Dart_Timeline_Event_Type type,
253 const std::vector<const char*>& names,
254 const std::vector<std::string>& values);
255
256inline std::string TraceToString(const char* string) {
257 return std::string{string};
258}
259
260inline std::string TraceToString(std::string string) {
261 return string;
262}
263
264inline std::string TraceToString(TimePoint point) {
265 return std::to_string(val: point.ToEpochDelta().ToNanoseconds());
266}
267
268template <typename T, typename = std::enable_if_t<std::is_arithmetic<T>::value>>
269std::string TraceToString(T string) {
270 return std::to_string(string);
271}
272
273inline void SplitArgumentsCollect(std::vector<const char*>& keys,
274 std::vector<std::string>& values) {}
275
276template <typename Key, typename Value, typename... Args>
277void SplitArgumentsCollect(std::vector<const char*>& keys,
278 std::vector<std::string>& values,
279 Key key,
280 Value value,
281 Args... args) {
282 keys.emplace_back(key);
283 values.emplace_back(TraceToString(value));
284 SplitArgumentsCollect(keys, values, args...);
285}
286
287inline std::pair<std::vector<const char*>, std::vector<std::string>>
288SplitArguments() {
289 return {};
290}
291
292template <typename Key, typename Value, typename... Args>
293std::pair<std::vector<const char*>, std::vector<std::string>>
294SplitArguments(Key key, Value value, Args... args) {
295 std::vector<const char*> keys;
296 std::vector<std::string> values;
297 SplitArgumentsCollect(keys, values, key, value, args...);
298 return std::make_pair(t1: std::move(keys), t2: std::move(values));
299}
300
301size_t TraceNonce();
302
303template <typename... Args>
304void TraceCounter(TraceArg category,
305 TraceArg name,
306 TraceIDArg identifier,
307 Args... args) {
308#if FLUTTER_TIMELINE_ENABLED
309 auto split = SplitArguments(args...);
310 TraceTimelineEvent(category, name, identifier, /*flow_id_count=*/0,
311 /*flow_ids=*/nullptr, Dart_Timeline_Event_Counter,
312 split.first, split.second);
313#endif // FLUTTER_TIMELINE_ENABLED
314}
315
316// HACK: Used to NOP FML_TRACE_COUNTER macro without triggering unused var
317// warnings at usage sites.
318template <typename... Args>
319void TraceCounterNopHACK(TraceArg category,
320 TraceArg name,
321 TraceIDArg identifier,
322 Args... args) {}
323
324template <typename... Args>
325void TraceEvent(TraceArg category,
326 TraceArg name,
327 size_t flow_id_count,
328 const uint64_t* flow_ids,
329 Args... args) {
330#if FLUTTER_TIMELINE_ENABLED
331 auto split = SplitArguments(args...);
332 TraceTimelineEvent(category, name, 0, flow_id_count, flow_ids,
333 Dart_Timeline_Event_Begin, split.first, split.second);
334#endif // FLUTTER_TIMELINE_ENABLED
335}
336
337void TraceEvent0(TraceArg category_group,
338 TraceArg name,
339 size_t flow_id_count,
340 const uint64_t* flow_ids);
341
342void TraceEvent1(TraceArg category_group,
343 TraceArg name,
344 size_t flow_id_count,
345 const uint64_t* flow_ids,
346 TraceArg arg1_name,
347 TraceArg arg1_val);
348
349void TraceEvent2(TraceArg category_group,
350 TraceArg name,
351 size_t flow_id_count,
352 const uint64_t* flow_ids,
353 TraceArg arg1_name,
354 TraceArg arg1_val,
355 TraceArg arg2_name,
356 TraceArg arg2_val);
357
358void TraceEventEnd(TraceArg name);
359
360template <typename... Args>
361void TraceEventAsyncComplete(TraceArg category_group,
362 TraceArg name,
363 TimePoint begin,
364 TimePoint end,
365 Args... args) {
366#if FLUTTER_TIMELINE_ENABLED
367 auto identifier = TraceNonce();
368 const auto split = SplitArguments(args...);
369
370 if (begin > end) {
371 std::swap(x&: begin, y&: end);
372 }
373
374 const int64_t begin_micros = begin.ToEpochDelta().ToMicroseconds();
375 const int64_t end_micros = end.ToEpochDelta().ToMicroseconds();
376
377 TraceTimelineEvent(category_group, // group
378 name, // name
379 begin_micros, // timestamp_micros
380 identifier, // identifier
381 0, // flow_id_count
382 nullptr, // flow_ids
383 Dart_Timeline_Event_Async_Begin, // type
384 split.first, // names
385 split.second // values
386 );
387
388 TraceTimelineEvent(category_group, // group
389 name, // name
390 end_micros, // timestamp_micros
391 identifier, // identifier
392 0, // flow_id_count
393 nullptr, // flow_ids
394 Dart_Timeline_Event_Async_End, // type
395 split.first, // names
396 split.second // values
397 );
398#endif // FLUTTER_TIMELINE_ENABLED
399}
400
401void TraceEventAsyncBegin0(TraceArg category_group,
402 TraceArg name,
403 TraceIDArg id,
404 size_t flow_id_count,
405 const uint64_t* flow_ids);
406
407void TraceEventAsyncEnd0(TraceArg category_group, TraceArg name, TraceIDArg id);
408
409void TraceEventAsyncBegin1(TraceArg category_group,
410 TraceArg name,
411 TraceIDArg id,
412 size_t flow_id_count,
413 const uint64_t* flow_ids,
414 TraceArg arg1_name,
415 TraceArg arg1_val);
416
417void TraceEventAsyncEnd1(TraceArg category_group,
418 TraceArg name,
419 TraceIDArg id,
420 TraceArg arg1_name,
421 TraceArg arg1_val);
422
423void TraceEventInstant0(TraceArg category_group,
424 TraceArg name,
425 size_t flow_id_count,
426 const uint64_t* flow_ids);
427
428void TraceEventInstant1(TraceArg category_group,
429 TraceArg name,
430 size_t flow_id_count,
431 const uint64_t* flow_ids,
432 TraceArg arg1_name,
433 TraceArg arg1_val);
434
435void TraceEventInstant2(TraceArg category_group,
436 TraceArg name,
437 size_t flow_id_count,
438 const uint64_t* flow_ids,
439 TraceArg arg1_name,
440 TraceArg arg1_val,
441 TraceArg arg2_name,
442 TraceArg arg2_val);
443
444void TraceEventFlowBegin0(TraceArg category_group,
445 TraceArg name,
446 TraceIDArg id);
447
448void TraceEventFlowStep0(TraceArg category_group, TraceArg name, TraceIDArg id);
449
450void TraceEventFlowEnd0(TraceArg category_group, TraceArg name, TraceIDArg id);
451
452class ScopedInstantEnd {
453 public:
454 explicit ScopedInstantEnd(const char* str) : label_(str) {}
455
456 ~ScopedInstantEnd() { TraceEventEnd(name: label_); }
457
458 private:
459 const char* label_;
460
461 FML_DISALLOW_COPY_AND_ASSIGN(ScopedInstantEnd);
462};
463
464// A move-only utility object that creates a new flow with a unique ID and
465// automatically ends it when it goes out of scope. When tracing using multiple
466// overlapping flows, it often gets hard to make sure to end the flow
467// (especially with early returns), or, end/step on the wrong flow. This
468// leads to corrupted or missing traces in the UI.
469class TraceFlow {
470 public:
471 explicit TraceFlow(const char* label) : label_(label), nonce_(TraceNonce()) {
472 TraceEvent0(category_group: "flutter", name: label_, /*flow_id_count=*/flow_id_count: 1,
473 /*flow_ids=*/flow_ids: &nonce_);
474 TraceEventFlowBegin0(category_group: "flutter", name: label_, id: nonce_);
475 TraceEventEnd(name: label_);
476 }
477
478 ~TraceFlow() { End(label: label_); }
479
480 TraceFlow(TraceFlow&& other) : label_(other.label_), nonce_(other.nonce_) {
481 other.nonce_ = 0;
482 }
483
484 void Step(const char* label = nullptr) const {
485 TraceEvent0(category_group: "flutter", name: label ? label : label_, /*flow_id_count=*/flow_id_count: 1,
486 /*flow_ids=*/flow_ids: &nonce_);
487 TraceEventFlowStep0(category_group: "flutter", name: label ? label : label_, id: nonce_);
488 TraceEventEnd(name: label ? label : label_);
489 }
490
491 void End(const char* label = nullptr) {
492 if (nonce_ != 0) {
493 TraceEvent0(category_group: "flutter", name: label ? label : label_, /*flow_id_count=*/flow_id_count: 1,
494 /*flow_ids=*/flow_ids: &nonce_);
495 TraceEventFlowEnd0(category_group: "flutter", name: label ? label : label_, id: nonce_);
496 TraceEventEnd(name: label ? label : label_);
497 nonce_ = 0;
498 }
499 }
500
501 private:
502 const char* label_;
503 uint64_t nonce_;
504
505 FML_DISALLOW_COPY_AND_ASSIGN(TraceFlow);
506};
507
508} // namespace tracing
509} // namespace fml
510
511#endif // FLUTTER_FML_TRACE_EVENT_H_
512

source code of flutter_engine/flutter/fml/trace_event.h