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