1 /*
2 * Copyright (C) 2019 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef INCLUDE_PERFETTO_TRACING_TRACK_EVENT_H_
18 #define INCLUDE_PERFETTO_TRACING_TRACK_EVENT_H_
19
20 #include "perfetto/tracing/internal/track_event_data_source.h"
21 #include "perfetto/tracing/internal/track_event_internal.h"
22 #include "perfetto/tracing/internal/track_event_macros.h"
23 #include "perfetto/tracing/string_helpers.h"
24 #include "perfetto/tracing/track.h"
25 #include "perfetto/tracing/track_event_category_registry.h"
26 #include "protos/perfetto/trace/track_event/track_event.pbzero.h"
27
28 #include <type_traits>
29
30 // This file contains a set of macros designed for instrumenting applications
31 // with track event trace points. While the underlying TrackEvent API can also
32 // be used directly, doing so efficiently requires some care (e.g., to avoid
33 // evaluating arguments while tracing is disabled). These types of optimizations
34 // are abstracted away by the macros below.
35 //
36 // ================
37 // Quickstart guide
38 // ================
39 //
40 // To add track events to your application, first define your categories in,
41 // e.g., my_tracing.h:
42 //
43 // PERFETTO_DEFINE_CATEGORIES(
44 // perfetto::Category("base"),
45 // perfetto::Category("v8"),
46 // perfetto::Category("cc"));
47 //
48 // Then in a single .cc file, e.g., my_tracing.cc:
49 //
50 // #include "my_tracing.h"
51 // PERFETTO_TRACK_EVENT_STATIC_STORAGE();
52 //
53 // Finally, register track events at startup, after which you can record
54 // events with the TRACE_EVENT macros:
55 //
56 // #include "my_tracing.h"
57 //
58 // int main() {
59 // perfetto::TrackEvent::Register();
60 //
61 // // A basic track event with just a name.
62 // TRACE_EVENT("category", "MyEvent");
63 //
64 // // A track event with (up to two) debug annotations.
65 // TRACE_EVENT("category", "MyEvent", "parameter", 42);
66 //
67 // // A track event with a strongly typed parameter.
68 // TRACE_EVENT("category", "MyEvent", [](perfetto::EventContext ctx) {
69 // ctx.event()->set_foo(42);
70 // ctx.event()->set_bar(.5f);
71 // });
72 // }
73 //
74 // Note that track events must be nested consistently, i.e., the following is
75 // not allowed:
76 //
77 // TRACE_EVENT_BEGIN("a", "bar", ...);
78 // TRACE_EVENT_BEGIN("b", "foo", ...);
79 // TRACE_EVENT_END("a"); // "foo" must be closed before "bar".
80 // TRACE_EVENT_END("b");
81 //
82 // ====================
83 // Implementation notes
84 // ====================
85 //
86 // The track event library consists of the following layers and components. The
87 // classes the internal namespace shouldn't be considered part of the public
88 // API.
89 // .--------------------------------.
90 // .----| TRACE_EVENT |----.
91 // write | | - App instrumentation point | | write
92 // event | '--------------------------------' | arguments
93 // V V
94 // .----------------------------------. .-----------------------------.
95 // | TrackEvent | | EventContext |
96 // | - Registry of event categories | | - One track event instance |
97 // '----------------------------------' '-----------------------------'
98 // | |
99 // | | look up
100 // | is | interning ids
101 // V V
102 // .----------------------------------. .-----------------------------.
103 // | internal::TrackEventDataSource | | TrackEventInternedDataIndex |
104 // | - Perfetto data source | | - Corresponds to a field in |
105 // | - Has TrackEventIncrementalState | | in interned_data.proto |
106 // '----------------------------------' '-----------------------------'
107 // | | ^
108 // | | owns (1:many) |
109 // | write event '-------------------------'
110 // V
111 // .----------------------------------.
112 // | internal::TrackEventInternal |
113 // | - Outlined code to serialize |
114 // | one track event |
115 // '----------------------------------'
116 //
117
118 // DEPRECATED: Please use PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE to implement
119 // multiple track event category sets in one program.
120 //
121 // Each compilation unit can be in exactly one track event namespace,
122 // allowing the overall program to use multiple track event data sources and
123 // category lists if necessary. Use this macro to select the namespace for the
124 // current compilation unit.
125 //
126 // If the program uses multiple track event namespaces, category & track event
127 // registration (see quickstart above) needs to happen for both namespaces
128 // separately.
129
130 #ifndef PERFETTO_TRACK_EVENT_NAMESPACE
131 #define PERFETTO_TRACK_EVENT_NAMESPACE perfetto_track_event
132 #endif
133
134 // Deprecated; see perfetto::Category().
135 #define PERFETTO_CATEGORY(name) \
136 ::perfetto::Category { \
137 #name \
138 }
139
140 // Internal helpers for determining if a given category is defined at build or
141 // runtime.
142 namespace PERFETTO_TRACK_EVENT_NAMESPACE {
143 namespace internal {
144
145 // By default no statically defined categories are dynamic, but this can be
146 // overridden with PERFETTO_DEFINE_TEST_CATEGORY_PREFIXES.
147 template <typename... T>
IsDynamicCategory(const char *)148 constexpr bool IsDynamicCategory(const char*) {
149 return false;
150 }
151
152 // Explicitly dynamic categories are always dynamic.
IsDynamicCategory(const::perfetto::DynamicCategory &)153 constexpr bool IsDynamicCategory(const ::perfetto::DynamicCategory&) {
154 return true;
155 }
156
157 } // namespace internal
158 } // namespace PERFETTO_TRACK_EVENT_NAMESPACE
159
160 // Normally all categories are defined statically at build-time (see
161 // PERFETTO_DEFINE_CATEGORIES). However, some categories are only used for
162 // testing, and we shouldn't publish them to the tracing service or include them
163 // in a production binary. Use this macro to define a list of prefixes for these
164 // types of categories. Note that trace points using these categories will be
165 // slightly less efficient compared to regular trace points.
166 #define PERFETTO_DEFINE_TEST_CATEGORY_PREFIXES(...) \
167 namespace PERFETTO_TRACK_EVENT_NAMESPACE { \
168 namespace internal { \
169 template <> \
170 constexpr bool IsDynamicCategory(const char* name) { \
171 return ::perfetto::internal::IsStringInPrefixList(name, __VA_ARGS__); \
172 } \
173 } /* namespace internal */ \
174 } /* namespace PERFETTO_TRACK_EVENT_NAMESPACE */ \
175 PERFETTO_INTERNAL_SWALLOW_SEMICOLON()
176
177 // Register the set of available categories by passing a list of categories to
178 // this macro: perfetto::Category("cat1"), perfetto::Category("cat2"), ...
179 // `ns` is the name of the namespace in which the categories should be declared.
180 // `attrs` are linkage attributes for the underlying data source. See
181 // PERFETTO_DECLARE_DATA_SOURCE_STATIC_MEMBERS_WITH_ATTRS.
182 //
183 // Implementation note: the extra namespace (PERFETTO_TRACK_EVENT_NAMESPACE) is
184 // kept here only for backward compatibility.
185 #define PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE_WITH_ATTRS(ns, attrs, ...) \
186 namespace ns { \
187 namespace PERFETTO_TRACK_EVENT_NAMESPACE { \
188 /* The list of category names */ \
189 PERFETTO_INTERNAL_DECLARE_CATEGORIES(attrs, __VA_ARGS__) \
190 /* The track event data source for this set of categories */ \
191 PERFETTO_INTERNAL_DECLARE_TRACK_EVENT_DATA_SOURCE(attrs); \
192 } /* namespace PERFETTO_TRACK_EVENT_NAMESPACE */ \
193 using PERFETTO_TRACK_EVENT_NAMESPACE::TrackEvent; \
194 } /* namespace ns */ \
195 PERFETTO_DECLARE_DATA_SOURCE_STATIC_MEMBERS_WITH_ATTRS( \
196 attrs, ns::PERFETTO_TRACK_EVENT_NAMESPACE::TrackEvent, \
197 ::perfetto::internal::TrackEventDataSourceTraits)
198
199 // Register the set of available categories by passing a list of categories to
200 // this macro: perfetto::Category("cat1"), perfetto::Category("cat2"), ...
201 // `ns` is the name of the namespace in which the categories should be declared.
202 #define PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE(ns, ...) \
203 PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE_WITH_ATTRS( \
204 ns, PERFETTO_COMPONENT_EXPORT, __VA_ARGS__)
205
206 // Make categories in a given namespace the default ones used by track events
207 // for the current translation unit. Can only be used *once* in a given global
208 // or namespace scope.
209 #define PERFETTO_USE_CATEGORIES_FROM_NAMESPACE(ns) \
210 namespace PERFETTO_TRACK_EVENT_NAMESPACE { \
211 using ::ns::PERFETTO_TRACK_EVENT_NAMESPACE::TrackEvent; \
212 namespace internal { \
213 using ::ns::PERFETTO_TRACK_EVENT_NAMESPACE::internal::kCategoryRegistry; \
214 using ::ns::PERFETTO_TRACK_EVENT_NAMESPACE::internal:: \
215 kConstExprCategoryRegistry; \
216 } /* namespace internal */ \
217 } /* namespace PERFETTO_TRACK_EVENT_NAMESPACE */ \
218 PERFETTO_INTERNAL_SWALLOW_SEMICOLON()
219
220 // Make categories in a given namespace the default ones used by track events
221 // for the current block scope. Can only be used in a function or block scope.
222 #define PERFETTO_USE_CATEGORIES_FROM_NAMESPACE_SCOPED(ns) \
223 namespace PERFETTO_TRACK_EVENT_NAMESPACE = ns::PERFETTO_TRACK_EVENT_NAMESPACE
224
225 // Register categories in the default (global) namespace. Warning: only one set
226 // of global categories can be defined in a single program. Create namespaced
227 // categories with PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE to work around this
228 // limitation.
229 #define PERFETTO_DEFINE_CATEGORIES(...) \
230 PERFETTO_DEFINE_CATEGORIES_IN_NAMESPACE(perfetto, __VA_ARGS__); \
231 PERFETTO_USE_CATEGORIES_FROM_NAMESPACE(perfetto)
232
233 // Allocate storage for each category by using this macro once per track event
234 // namespace. `ns` is the name of the namespace in which the categories should
235 // be declared and `attrs` specify linkage attributes for the data source.
236 #define PERFETTO_TRACK_EVENT_STATIC_STORAGE_IN_NAMESPACE_WITH_ATTRS(ns, attrs) \
237 namespace ns { \
238 namespace PERFETTO_TRACK_EVENT_NAMESPACE { \
239 PERFETTO_INTERNAL_CATEGORY_STORAGE(attrs) \
240 PERFETTO_INTERNAL_DEFINE_TRACK_EVENT_DATA_SOURCE() \
241 } /* namespace PERFETTO_TRACK_EVENT_NAMESPACE */ \
242 } /* namespace ns */ \
243 PERFETTO_DEFINE_DATA_SOURCE_STATIC_MEMBERS_WITH_ATTRS( \
244 attrs, ns::PERFETTO_TRACK_EVENT_NAMESPACE::TrackEvent, \
245 ::perfetto::internal::TrackEventDataSourceTraits)
246
247 // Allocate storage for each category by using this macro once per track event
248 // namespace.
249 #define PERFETTO_TRACK_EVENT_STATIC_STORAGE_IN_NAMESPACE(ns) \
250 PERFETTO_TRACK_EVENT_STATIC_STORAGE_IN_NAMESPACE_WITH_ATTRS( \
251 ns, PERFETTO_COMPONENT_EXPORT)
252
253 // Allocate storage for each category by using this macro once per track event
254 // namespace.
255 #define PERFETTO_TRACK_EVENT_STATIC_STORAGE() \
256 PERFETTO_TRACK_EVENT_STATIC_STORAGE_IN_NAMESPACE(perfetto)
257
258 // Ignore GCC warning about a missing argument for a variadic macro parameter.
259 #if defined(__GNUC__) || defined(__clang__)
260 #pragma GCC system_header
261 #endif
262
263 // Begin a slice under |category| with the title |name|. Both strings must be
264 // static constants. The track event is only recorded if |category| is enabled
265 // for a tracing session.
266 //
267 // The slice is thread-scoped (i.e., written to the default track of the current
268 // thread) unless overridden with a custom track object (see Track).
269 //
270 // |name| must be a string with static lifetime (i.e., the same
271 // address must not be used for a different event name in the future). If you
272 // want to use a dynamically allocated name, do this:
273 //
274 // TRACE_EVENT("category", nullptr, [&](perfetto::EventContext ctx) {
275 // ctx.event()->set_name(dynamic_name);
276 // });
277 //
278 // The following optional arguments can be passed to `TRACE_EVENT` to add extra
279 // information to events:
280 //
281 // TRACE_EVENT("cat", "name"[, track][, timestamp]
282 // [, "debug_name1", debug_value1]
283 // [, "debug_name2", debug_value2]
284 // ...
285 // [, "debug_nameN", debug_valueN]
286 // [, lambda]);
287 //
288 // Some examples of valid combinations:
289 //
290 // 1. A lambda for writing custom TrackEvent fields:
291 //
292 // TRACE_EVENT("category", "Name", [&](perfetto::EventContext ctx) {
293 // ctx.event()->set_custom_value(...);
294 // });
295 //
296 // 2. A timestamp and a lambda:
297 //
298 // TRACE_EVENT("category", "Name", time_in_nanoseconds,
299 // [&](perfetto::EventContext ctx) {
300 // ctx.event()->set_custom_value(...);
301 // });
302 //
303 // |time_in_nanoseconds| should be an uint64_t by default. To support custom
304 // timestamp types,
305 // |perfetto::TraceTimestampTraits<T>::ConvertTimestampToTraceTimeNs|
306 // should be defined. See |ConvertTimestampToTraceTimeNs| for more details.
307 //
308 // 3. Arbitrary number of debug annotations:
309 //
310 // TRACE_EVENT("category", "Name", "arg", value);
311 // TRACE_EVENT("category", "Name", "arg", value, "arg2", value2);
312 // TRACE_EVENT("category", "Name", "arg", value, "arg2", value2,
313 // "arg3", value3);
314 //
315 // See |TracedValue| for recording custom types as debug annotations.
316 //
317 // 4. Arbitrary number of debug annotations and a lambda:
318 //
319 // TRACE_EVENT("category", "Name", "arg", value,
320 // [&](perfetto::EventContext ctx) {
321 // ctx.event()->set_custom_value(...);
322 // });
323 //
324 // 5. An overridden track:
325 //
326 // TRACE_EVENT("category", "Name", perfetto::Track(1234));
327 //
328 // See |Track| for other types of tracks which may be used.
329 //
330 // 6. A track and a lambda:
331 //
332 // TRACE_EVENT("category", "Name", perfetto::Track(1234),
333 // [&](perfetto::EventContext ctx) {
334 // ctx.event()->set_custom_value(...);
335 // });
336 //
337 // 7. A track and a timestamp:
338 //
339 // TRACE_EVENT("category", "Name", perfetto::Track(1234),
340 // time_in_nanoseconds);
341 //
342 // 8. A track, a timestamp and a lambda:
343 //
344 // TRACE_EVENT("category", "Name", perfetto::Track(1234),
345 // time_in_nanoseconds, [&](perfetto::EventContext ctx) {
346 // ctx.event()->set_custom_value(...);
347 // });
348 //
349 // 9. A track and an arbitrary number of debug annotions:
350 //
351 // TRACE_EVENT("category", "Name", perfetto::Track(1234),
352 // "arg", value);
353 // TRACE_EVENT("category", "Name", perfetto::Track(1234),
354 // "arg", value, "arg2", value2);
355 //
356 #define TRACE_EVENT_BEGIN(category, name, ...) \
357 PERFETTO_INTERNAL_TRACK_EVENT_WITH_METHOD( \
358 TraceForCategory, category, name, \
359 ::perfetto::protos::pbzero::TrackEvent::TYPE_SLICE_BEGIN, ##__VA_ARGS__)
360
361 // End a slice under |category|.
362 #define TRACE_EVENT_END(category, ...) \
363 PERFETTO_INTERNAL_TRACK_EVENT_WITH_METHOD( \
364 TraceForCategory, category, /*name=*/nullptr, \
365 ::perfetto::protos::pbzero::TrackEvent::TYPE_SLICE_END, ##__VA_ARGS__)
366
367 // Begin a slice which gets automatically closed when going out of scope.
368 #define TRACE_EVENT(category, name, ...) \
369 PERFETTO_INTERNAL_SCOPED_TRACK_EVENT(category, name, ##__VA_ARGS__)
370
371 // Emit a slice which has zero duration.
372 #define TRACE_EVENT_INSTANT(category, name, ...) \
373 PERFETTO_INTERNAL_TRACK_EVENT_WITH_METHOD( \
374 TraceForCategory, category, name, \
375 ::perfetto::protos::pbzero::TrackEvent::TYPE_INSTANT, ##__VA_ARGS__)
376
377 // Efficiently determine if the given static or dynamic trace category or
378 // category group is enabled for tracing.
379 #define TRACE_EVENT_CATEGORY_ENABLED(category) \
380 PERFETTO_INTERNAL_CATEGORY_ENABLED(category)
381
382 // Time-varying numeric data can be recorded with the TRACE_COUNTER macro:
383 //
384 // TRACE_COUNTER("cat", counter_track[, timestamp], value);
385 //
386 // For example, to record a single value for a counter called "MyCounter":
387 //
388 // TRACE_COUNTER("category", "MyCounter", 1234.5);
389 //
390 // This data is displayed as a counter track in the Perfetto UI.
391 //
392 // Both integer and floating point counter values are supported. Counters can
393 // also be annotated with additional information such as units, for example, for
394 // tracking the rendering framerate in terms of frames per second or "fps":
395 //
396 // TRACE_COUNTER("category", perfetto::CounterTrack("Framerate", "fps"), 120);
397 //
398 // As another example, a memory counter that records bytes but accepts samples
399 // as kilobytes (to reduce trace binary size) can be defined like this:
400 //
401 // perfetto::CounterTrack memory_track = perfetto::CounterTrack("Memory")
402 // .set_unit("bytes")
403 // .set_multiplier(1024);
404 // TRACE_COUNTER("category", memory_track, 4 /* = 4096 bytes */);
405 //
406 // See /protos/perfetto/trace/track_event/counter_descriptor.proto
407 // for the full set of attributes for a counter track.
408 //
409 // To record a counter value at a specific point in time (instead of the current
410 // time), you can pass in a custom timestamp:
411 //
412 // // First record the current time and counter value.
413 // uint64_t timestamp = perfetto::TrackEvent::GetTraceTimeNs();
414 // int64_t value = 1234;
415 //
416 // // Later, emit a sample at that point in time.
417 // TRACE_COUNTER("category", "MyCounter", timestamp, value);
418 //
419 #define TRACE_COUNTER(category, track, ...) \
420 PERFETTO_INTERNAL_TRACK_EVENT_WITH_METHOD( \
421 TraceForCategory, category, /*name=*/nullptr, \
422 ::perfetto::protos::pbzero::TrackEvent::TYPE_COUNTER, \
423 ::perfetto::CounterTrack(track), ##__VA_ARGS__)
424
425 // TODO(skyostil): Add flow events.
426
427 #endif // INCLUDE_PERFETTO_TRACING_TRACK_EVENT_H_
428