Flutter Engine
trace_event.h
Go to the documentation of this file.
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 
25 #define TRACE_EVENT0(a, b) TRACE_DURATION(a, b)
26 #define TRACE_EVENT1(a, b, c, d) TRACE_DURATION(a, b, c, d)
27 #define TRACE_EVENT2(a, b, c, d, e, f) TRACE_DURATION(a, b, c, d, e, f)
28 #define TRACE_EVENT_ASYNC_BEGIN0(a, b, c) TRACE_ASYNC_BEGIN(a, b, c)
29 #define TRACE_EVENT_ASYNC_END0(a, b, c) TRACE_ASYNC_END(a, b, c)
30 #define TRACE_EVENT_ASYNC_BEGIN1(a, b, c, d, e) TRACE_ASYNC_BEGIN(a, b, c, d, e)
31 #define TRACE_EVENT_ASYNC_END1(a, b, c, d, e) TRACE_ASYNC_END(a, b, c, d, e)
32 #define TRACE_EVENT_INSTANT0(a, b) TRACE_INSTANT(a, b, TRACE_SCOPE_THREAD)
33 #define TRACE_EVENT_INSTANT1(a, b, k1, v1) \
34  TRACE_INSTANT(a, b, TRACE_SCOPE_THREAD, k1, v1)
35 #define TRACE_EVENT_INSTANT2(a, b, k1, v1, k2, v2) \
36  TRACE_INSTANT(a, b, TRACE_SCOPE_THREAD, k1, v1, k2, v2)
37 
38 #endif // defined(OS_FUCHSIA)
39 
40 #include <cstddef>
41 #include <cstdint>
42 #include <string>
43 #include <type_traits>
44 #include <vector>
45 
46 #include "flutter/fml/macros.h"
47 #include "flutter/fml/time/time_point.h"
48 #include "third_party/dart/runtime/include/dart_tools_api.h"
49 
50 #if (FLUTTER_RELEASE && !defined(OS_FUCHSIA) && !defined(OS_ANDROID))
51 #define FLUTTER_TIMELINE_ENABLED 0
52 #else
53 #define FLUTTER_TIMELINE_ENABLED 1
54 #endif
55 
56 #if !defined(OS_FUCHSIA)
57 #ifndef TRACE_EVENT_HIDE_MACROS
58 
59 #define __FML__TOKEN_CAT__(x, y) x##y
60 #define __FML__TOKEN_CAT__2(x, y) __FML__TOKEN_CAT__(x, y)
61 #define __FML__AUTO_TRACE_END(name) \
62  ::fml::tracing::ScopedInstantEnd __FML__TOKEN_CAT__2(__trace_end_, \
63  __LINE__)(name);
64 
65 // This macro has the FML_ prefix so that it does not collide with the macros
66 // from lib/trace/event.h on Fuchsia.
67 //
68 // TODO(chinmaygarde): All macros here should have the FML prefix.
69 #define FML_TRACE_COUNTER(category_group, name, counter_id, arg1, ...) \
70  ::fml::tracing::TraceCounter((category_group), (name), (counter_id), (arg1), \
71  __VA_ARGS__);
72 
73 // Avoid using the same `name` and `argX_name` for nested traces, which can
74 // lead to double free errors. E.g. the following code should be avoided:
75 //
76 // ```cpp
77 // {
78 // TRACE_EVENT1("flutter", "Foo::Bar", "count", "initial_count_value");
79 // ...
80 // TRACE_EVENT_INSTANT1("flutter", "Foo::Bar",
81 // "count", "updated_count_value");
82 // }
83 // ```
84 //
85 // Instead, either use different `name` or `arg1` parameter names.
86 #define FML_TRACE_EVENT(category_group, name, ...) \
87  ::fml::tracing::TraceEvent((category_group), (name), __VA_ARGS__); \
88  __FML__AUTO_TRACE_END(name)
89 
90 #define TRACE_EVENT0(category_group, name) \
91  ::fml::tracing::TraceEvent0(category_group, name); \
92  __FML__AUTO_TRACE_END(name)
93 
94 #define TRACE_EVENT1(category_group, name, arg1_name, arg1_val) \
95  ::fml::tracing::TraceEvent1(category_group, name, arg1_name, arg1_val); \
96  __FML__AUTO_TRACE_END(name)
97 
98 #define TRACE_EVENT2(category_group, name, arg1_name, arg1_val, arg2_name, \
99  arg2_val) \
100  ::fml::tracing::TraceEvent2(category_group, name, arg1_name, arg1_val, \
101  arg2_name, arg2_val); \
102  __FML__AUTO_TRACE_END(name)
103 
104 #define TRACE_EVENT_ASYNC_BEGIN0(category_group, name, id) \
105  ::fml::tracing::TraceEventAsyncBegin0(category_group, name, id);
106 
107 #define TRACE_EVENT_ASYNC_END0(category_group, name, id) \
108  ::fml::tracing::TraceEventAsyncEnd0(category_group, name, id);
109 
110 #define TRACE_EVENT_ASYNC_BEGIN1(category_group, name, id, arg1_name, \
111  arg1_val) \
112  ::fml::tracing::TraceEventAsyncBegin1(category_group, name, id, arg1_name, \
113  arg1_val);
114 
115 #define TRACE_EVENT_ASYNC_END1(category_group, name, id, arg1_name, arg1_val) \
116  ::fml::tracing::TraceEventAsyncEnd1(category_group, name, id, arg1_name, \
117  arg1_val);
118 
119 #define TRACE_EVENT_INSTANT0(category_group, name) \
120  ::fml::tracing::TraceEventInstant0(category_group, name);
121 
122 #define TRACE_EVENT_INSTANT1(category_group, name, arg1_name, arg1_val) \
123  ::fml::tracing::TraceEventInstant1(category_group, name, arg1_name, arg1_val);
124 
125 #define TRACE_EVENT_INSTANT2(category_group, name, arg1_name, arg1_val, \
126  arg2_name, arg2_val) \
127  ::fml::tracing::TraceEventInstant2(category_group, name, arg1_name, \
128  arg1_val, arg2_name, arg2_val);
129 
130 #define TRACE_FLOW_BEGIN(category, name, id) \
131  ::fml::tracing::TraceEventFlowBegin0(category, name, id);
132 
133 #define TRACE_FLOW_STEP(category, name, id) \
134  ::fml::tracing::TraceEventFlowStep0(category, name, id);
135 
136 #define TRACE_FLOW_END(category, name, id) \
137  ::fml::tracing::TraceEventFlowEnd0(category, name, id);
138 
139 #endif // TRACE_EVENT_HIDE_MACROS
140 #endif // !defined(OS_FUCHSIA)
141 
142 namespace fml {
143 namespace tracing {
144 
145 using TraceArg = const char*;
146 using TraceIDArg = int64_t;
147 
148 void TraceSetAllowlist(const std::vector<std::string>& allowlist);
149 
150 using TimelineEventHandler = std::function<void(const char*,
151  int64_t,
152  int64_t,
153  Dart_Timeline_Event_Type,
154  intptr_t,
155  const char**,
156  const char**)>;
157 
159 
160 void TraceTimelineEvent(TraceArg category_group,
161  TraceArg name,
162  int64_t timestamp_micros,
163  TraceIDArg id,
164  Dart_Timeline_Event_Type type,
165  const std::vector<const char*>& names,
166  const std::vector<std::string>& values);
167 
168 void TraceTimelineEvent(TraceArg category_group,
169  TraceArg name,
170  TraceIDArg id,
171  Dart_Timeline_Event_Type type,
172  const std::vector<const char*>& names,
173  const std::vector<std::string>& values);
174 
175 inline std::string TraceToString(const char* string) {
176  return std::string{string};
177 }
178 
179 inline std::string TraceToString(std::string string) {
180  return string;
181 }
182 
183 inline std::string TraceToString(TimePoint point) {
184  return std::to_string(point.ToEpochDelta().ToNanoseconds());
185 }
186 
188 std::string TraceToString(T string) {
189  return std::to_string(string);
190 }
191 
192 inline void SplitArgumentsCollect(std::vector<const char*>& keys,
193  std::vector<std::string>& values) {}
194 
195 template <typename Key, typename Value, typename... Args>
196 void SplitArgumentsCollect(std::vector<const char*>& keys,
197  std::vector<std::string>& values,
198  Key key,
199  Value value,
200  Args... args) {
201  keys.emplace_back(key);
202  values.emplace_back(TraceToString(value));
203  SplitArgumentsCollect(keys, values, args...);
204 }
205 
206 inline std::pair<std::vector<const char*>, std::vector<std::string>>
208  return {};
209 }
210 
211 template <typename Key, typename Value, typename... Args>
212 std::pair<std::vector<const char*>, std::vector<std::string>>
213 SplitArguments(Key key, Value value, Args... args) {
214  std::vector<const char*> keys;
215  std::vector<std::string> values;
216  SplitArgumentsCollect(keys, values, key, value, args...);
217  return std::make_pair(std::move(keys), std::move(values));
218 }
219 
220 size_t TraceNonce();
221 
222 template <typename... Args>
223 void TraceCounter(TraceArg category,
224  TraceArg name,
225  TraceIDArg identifier,
226  Args... args) {
227 #if FLUTTER_TIMELINE_ENABLED
228  auto split = SplitArguments(args...);
229  TraceTimelineEvent(category, name, identifier, Dart_Timeline_Event_Counter,
230  split.first, split.second);
231 #endif // FLUTTER_TIMELINE_ENABLED
232 }
233 
234 // HACK: Used to NOP FML_TRACE_COUNTER macro without triggering unused var
235 // warnings at usage sites.
236 template <typename... Args>
238  TraceArg name,
239  TraceIDArg identifier,
240  Args... args) {}
241 
242 template <typename... Args>
243 void TraceEvent(TraceArg category, TraceArg name, Args... args) {
244 #if FLUTTER_TIMELINE_ENABLED
245  auto split = SplitArguments(args...);
246  TraceTimelineEvent(category, name, 0, Dart_Timeline_Event_Begin, split.first,
247  split.second);
248 #endif // FLUTTER_TIMELINE_ENABLED
249 }
250 
251 void TraceEvent0(TraceArg category_group, TraceArg name);
252 
253 void TraceEvent1(TraceArg category_group,
254  TraceArg name,
255  TraceArg arg1_name,
256  TraceArg arg1_val);
257 
258 void TraceEvent2(TraceArg category_group,
259  TraceArg name,
260  TraceArg arg1_name,
261  TraceArg arg1_val,
262  TraceArg arg2_name,
263  TraceArg arg2_val);
264 
265 void TraceEventEnd(TraceArg name);
266 
267 template <typename... Args>
268 void TraceEventAsyncComplete(TraceArg category_group,
269  TraceArg name,
270  TimePoint begin,
271  TimePoint end,
272  Args... args) {
273 #if FLUTTER_TIMELINE_ENABLED
274  auto identifier = TraceNonce();
275  const auto split = SplitArguments(args...);
276 
277  if (begin > end) {
278  std::swap(begin, end);
279  }
280 
281  const int64_t begin_micros = begin.ToEpochDelta().ToMicroseconds();
282  const int64_t end_micros = end.ToEpochDelta().ToMicroseconds();
283 
284  TraceTimelineEvent(category_group, // group
285  name, // name
286  begin_micros, // timestamp_micros
287  identifier, // identifier
288  Dart_Timeline_Event_Async_Begin, // type
289  split.first, // names
290  split.second // values
291  );
292 
293  TraceTimelineEvent(category_group, // group
294  name, // name
295  end_micros, // timestamp_micros
296  identifier, // identifier
297  Dart_Timeline_Event_Async_End, // type
298  split.first, // names
299  split.second // values
300  );
301 #endif // FLUTTER_TIMELINE_ENABLED
302 }
303 
304 void TraceEventAsyncBegin0(TraceArg category_group,
305  TraceArg name,
306  TraceIDArg id);
307 
308 void TraceEventAsyncEnd0(TraceArg category_group, TraceArg name, TraceIDArg id);
309 
310 void TraceEventAsyncBegin1(TraceArg category_group,
311  TraceArg name,
312  TraceIDArg id,
313  TraceArg arg1_name,
314  TraceArg arg1_val);
315 
316 void TraceEventAsyncEnd1(TraceArg category_group,
317  TraceArg name,
318  TraceIDArg id,
319  TraceArg arg1_name,
320  TraceArg arg1_val);
321 
322 void TraceEventInstant0(TraceArg category_group, TraceArg name);
323 
324 void TraceEventInstant1(TraceArg category_group,
325  TraceArg name,
326  TraceArg arg1_name,
327  TraceArg arg1_val);
328 
329 void TraceEventInstant2(TraceArg category_group,
330  TraceArg name,
331  TraceArg arg1_name,
332  TraceArg arg1_val,
333  TraceArg arg2_name,
334  TraceArg arg2_val);
335 
336 void TraceEventFlowBegin0(TraceArg category_group,
337  TraceArg name,
338  TraceIDArg id);
339 
340 void TraceEventFlowStep0(TraceArg category_group, TraceArg name, TraceIDArg id);
341 
342 void TraceEventFlowEnd0(TraceArg category_group, TraceArg name, TraceIDArg id);
343 
345  public:
346  ScopedInstantEnd(const char* str) : label_(str) {}
347 
349 
350  private:
351  const char* label_;
352 
353  FML_DISALLOW_COPY_AND_ASSIGN(ScopedInstantEnd);
354 };
355 
356 // A move-only utility object that creates a new flow with a unique ID and
357 // automatically ends it when it goes out of scope. When tracing using multiple
358 // overlapping flows, it often gets hard to make sure to end the flow
359 // (especially with early returns), or, end/step on the wrong flow. This
360 // leads to corrupted or missing traces in the UI.
361 class TraceFlow {
362  public:
363  TraceFlow(const char* label) : label_(label), nonce_(TraceNonce()) {
364  TraceEventFlowBegin0("flutter", label_, nonce_);
365  }
366 
367  ~TraceFlow() { End(label_); }
368 
369  TraceFlow(TraceFlow&& other) : label_(other.label_), nonce_(other.nonce_) {
370  other.nonce_ = 0;
371  }
372 
373  void Step(const char* label = nullptr) const {
374  TraceEventFlowStep0("flutter", label ? label : label_, nonce_);
375  }
376 
377  void End(const char* label = nullptr) {
378  if (nonce_ != 0) {
379  TraceEventFlowEnd0("flutter", label ? label : label_, nonce_);
380  nonce_ = 0;
381  }
382  }
383 
384  private:
385  const char* label_;
386  size_t nonce_;
387 
389 };
390 
391 } // namespace tracing
392 } // namespace fml
393 
394 #endif // FLUTTER_FML_TRACE_EVENT_H_
G_BEGIN_DECLS FlValue * args
void TraceEventInstant1(TraceArg category_group, TraceArg name, TraceArg arg1_name, TraceArg arg1_val)
Definition: trace_event.cc:360
KeyCallType type
void TraceEventAsyncEnd0(TraceArg category_group, TraceArg name, TraceIDArg id)
Definition: trace_event.cc:342
void TraceCounter(TraceArg category, TraceArg name, TraceIDArg identifier, Args... args)
Definition: trace_event.h:223
std::function< void(const char *, int64_t, int64_t, Dart_Timeline_Event_Type, intptr_t, const char **, const char **)> TimelineEventHandler
Definition: trace_event.h:156
void TraceEventEnd(TraceArg name)
Definition: trace_event.cc:331
TraceFlow(TraceFlow &&other)
Definition: trace_event.h:369
TraceFlow(const char *label)
Definition: trace_event.h:363
Dart_NativeFunction function
Definition: fuchsia.cc:51
void TraceEventFlowBegin0(TraceArg category_group, TraceArg name, TraceIDArg id)
Definition: trace_event.cc:372
TimeDelta ToEpochDelta() const
Definition: time_point.h:47
void TraceTimelineEvent(TraceArg category_group, TraceArg name, int64_t timestamp_micros, TraceIDArg identifier, Dart_Timeline_Event_Type type, const std::vector< const char *> &c_names, const std::vector< std::string > &values)
Definition: trace_event.cc:302
void swap(scoped_nsprotocol< C > &p1, scoped_nsprotocol< C > &p2)
Definition: ascii_trie.cc:9
void TraceEvent1(TraceArg category_group, TraceArg name, TraceArg arg1_name, TraceArg arg1_val)
Definition: trace_event.cc:319
const char * TraceArg
Definition: trace_event.h:145
void TraceEventFlowEnd0(TraceArg category_group, TraceArg name, TraceIDArg id)
Definition: trace_event.cc:380
void TraceEventInstant0(TraceArg category_group, TraceArg name)
Definition: trace_event.cc:358
uint8_t value
std::pair< std::vector< const char * >, std::vector< std::string > > SplitArguments()
Definition: trace_event.h:207
constexpr int64_t ToMicroseconds() const
Definition: time_delta.h:62
void TraceEventAsyncEnd1(TraceArg category_group, TraceArg name, TraceIDArg id, TraceArg arg1_name, TraceArg arg1_val)
Definition: trace_event.cc:352
void End(const char *label=nullptr)
Definition: trace_event.h:377
void Step(const char *label=nullptr) const
Definition: trace_event.h:373
void TraceEventFlowStep0(TraceArg category_group, TraceArg name, TraceIDArg id)
Definition: trace_event.cc:376
void TraceSetTimelineEventHandler(TimelineEventHandler handler)
Definition: trace_event.cc:296
void TraceCounterNopHACK(TraceArg category, TraceArg name, TraceIDArg identifier, Args... args)
Definition: trace_event.h:237
ScopedInstantEnd(const char *str)
Definition: trace_event.h:346
constexpr int64_t ToNanoseconds() const
Definition: time_delta.h:61
int64_t TraceIDArg
Definition: trace_event.h:146
void TraceSetAllowlist(const std::vector< std::string > &allowlist)
Definition: trace_event.cc:294
void TraceEvent2(TraceArg category_group, TraceArg name, TraceArg arg1_name, TraceArg arg1_val, TraceArg arg2_name, TraceArg arg2_val)
Definition: trace_event.cc:324
void TraceEventAsyncBegin0(TraceArg category_group, TraceArg name, TraceIDArg id)
Definition: trace_event.cc:338
void TraceEvent(TraceArg category, TraceArg name, Args... args)
Definition: trace_event.h:243
std::string TraceToString(const char *string)
Definition: trace_event.h:175
const char * name
Definition: fuchsia.cc:50
void SplitArgumentsCollect(std::vector< const char *> &keys, std::vector< std::string > &values)
Definition: trace_event.h:192
void TraceEventInstant2(TraceArg category_group, TraceArg name, TraceArg arg1_name, TraceArg arg1_val, TraceArg arg2_name, TraceArg arg2_val)
Definition: trace_event.cc:365
void TraceEventAsyncComplete(TraceArg category_group, TraceArg name, TimePoint begin, TimePoint end)
Definition: trace_event.cc:333
size_t TraceNonce()
Definition: trace_event.cc:298
#define FML_DISALLOW_COPY_AND_ASSIGN(TypeName)
Definition: macros.h:27
void TraceEvent0(TraceArg category_group, TraceArg name)
Definition: trace_event.cc:317
void TraceEventAsyncBegin1(TraceArg category_group, TraceArg name, TraceIDArg id, TraceArg arg1_name, TraceArg arg1_val)
Definition: trace_event.cc:346