SupervisedUser SafeSites: Switch to the new SafeSearch API
[chromium-blink-merge.git] / base / trace_event / trace_event_common.h
blobaa5a4935362686ede2f1c1935fb9448fbb7663a9
1 // Copyright 2015 The Chromium 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.
5 // This header file defines the set of trace_event macros without specifying
6 // how the events actually get collected and stored. If you need to expose trace
7 // events to some other universe, you can copy-and-paste this file as well as
8 // trace_event.h, modifying the macros contained there as necessary for the
9 // target platform. The end result is that multiple libraries can funnel events
10 // through to a shared trace event collector.
12 // IMPORTANT: To avoid conflicts, if you need to modify this file for a library,
13 // land your change in base/ first, and then copy-and-paste it.
15 // Trace events are for tracking application performance and resource usage.
16 // Macros are provided to track:
17 // Begin and end of function calls
18 // Counters
20 // Events are issued against categories. Whereas LOG's
21 // categories are statically defined, TRACE categories are created
22 // implicitly with a string. For example:
23 // TRACE_EVENT_INSTANT0("MY_SUBSYSTEM", "SomeImportantEvent",
24 // TRACE_EVENT_SCOPE_THREAD)
26 // It is often the case that one trace may belong in multiple categories at the
27 // same time. The first argument to the trace can be a comma-separated list of
28 // categories, forming a category group, like:
30 // TRACE_EVENT_INSTANT0("input,views", "OnMouseOver", TRACE_EVENT_SCOPE_THREAD)
32 // We can enable/disable tracing of OnMouseOver by enabling/disabling either
33 // category.
35 // Events can be INSTANT, or can be pairs of BEGIN and END in the same scope:
36 // TRACE_EVENT_BEGIN0("MY_SUBSYSTEM", "SomethingCostly")
37 // doSomethingCostly()
38 // TRACE_EVENT_END0("MY_SUBSYSTEM", "SomethingCostly")
39 // Note: our tools can't always determine the correct BEGIN/END pairs unless
40 // these are used in the same scope. Use ASYNC_BEGIN/ASYNC_END macros if you
41 // need them to be in separate scopes.
43 // A common use case is to trace entire function scopes. This
44 // issues a trace BEGIN and END automatically:
45 // void doSomethingCostly() {
46 // TRACE_EVENT0("MY_SUBSYSTEM", "doSomethingCostly");
47 // ...
48 // }
50 // Additional parameters can be associated with an event:
51 // void doSomethingCostly2(int howMuch) {
52 // TRACE_EVENT1("MY_SUBSYSTEM", "doSomethingCostly",
53 // "howMuch", howMuch);
54 // ...
55 // }
57 // The trace system will automatically add to this information the
58 // current process id, thread id, and a timestamp in microseconds.
60 // To trace an asynchronous procedure such as an IPC send/receive, use
61 // ASYNC_BEGIN and ASYNC_END:
62 // [single threaded sender code]
63 // static int send_count = 0;
64 // ++send_count;
65 // TRACE_EVENT_ASYNC_BEGIN0("ipc", "message", send_count);
66 // Send(new MyMessage(send_count));
67 // [receive code]
68 // void OnMyMessage(send_count) {
69 // TRACE_EVENT_ASYNC_END0("ipc", "message", send_count);
70 // }
71 // The third parameter is a unique ID to match ASYNC_BEGIN/ASYNC_END pairs.
72 // ASYNC_BEGIN and ASYNC_END can occur on any thread of any traced process.
73 // Pointers can be used for the ID parameter, and they will be mangled
74 // internally so that the same pointer on two different processes will not
75 // match. For example:
76 // class MyTracedClass {
77 // public:
78 // MyTracedClass() {
79 // TRACE_EVENT_ASYNC_BEGIN0("category", "MyTracedClass", this);
80 // }
81 // ~MyTracedClass() {
82 // TRACE_EVENT_ASYNC_END0("category", "MyTracedClass", this);
83 // }
84 // }
86 // Trace event also supports counters, which is a way to track a quantity
87 // as it varies over time. Counters are created with the following macro:
88 // TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter", g_myCounterValue);
90 // Counters are process-specific. The macro itself can be issued from any
91 // thread, however.
93 // Sometimes, you want to track two counters at once. You can do this with two
94 // counter macros:
95 // TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter0", g_myCounterValue[0]);
96 // TRACE_COUNTER1("MY_SUBSYSTEM", "myCounter1", g_myCounterValue[1]);
97 // Or you can do it with a combined macro:
98 // TRACE_COUNTER2("MY_SUBSYSTEM", "myCounter",
99 // "bytesPinned", g_myCounterValue[0],
100 // "bytesAllocated", g_myCounterValue[1]);
101 // This indicates to the tracing UI that these counters should be displayed
102 // in a single graph, as a summed area chart.
104 // Since counters are in a global namespace, you may want to disambiguate with a
105 // unique ID, by using the TRACE_COUNTER_ID* variations.
107 // By default, trace collection is compiled in, but turned off at runtime.
108 // Collecting trace data is the responsibility of the embedding
109 // application. In Chrome's case, navigating to about:tracing will turn on
110 // tracing and display data collected across all active processes.
113 // Memory scoping note:
114 // Tracing copies the pointers, not the string content, of the strings passed
115 // in for category_group, name, and arg_names. Thus, the following code will
116 // cause problems:
117 // char* str = strdup("importantName");
118 // TRACE_EVENT_INSTANT0("SUBSYSTEM", str); // BAD!
119 // free(str); // Trace system now has dangling pointer
121 // To avoid this issue with the |name| and |arg_name| parameters, use the
122 // TRACE_EVENT_COPY_XXX overloads of the macros at additional runtime overhead.
123 // Notes: The category must always be in a long-lived char* (i.e. static const).
124 // The |arg_values|, when used, are always deep copied with the _COPY
125 // macros.
127 // When are string argument values copied:
128 // const char* arg_values are only referenced by default:
129 // TRACE_EVENT1("category", "name",
130 // "arg1", "literal string is only referenced");
131 // Use TRACE_STR_COPY to force copying of a const char*:
132 // TRACE_EVENT1("category", "name",
133 // "arg1", TRACE_STR_COPY("string will be copied"));
134 // std::string arg_values are always copied:
135 // TRACE_EVENT1("category", "name",
136 // "arg1", std::string("string will be copied"));
139 // Convertable notes:
140 // Converting a large data type to a string can be costly. To help with this,
141 // the trace framework provides an interface ConvertableToTraceFormat. If you
142 // inherit from it and implement the AppendAsTraceFormat method the trace
143 // framework will call back to your object to convert a trace output time. This
144 // means, if the category for the event is disabled, the conversion will not
145 // happen.
147 // class MyData : public base::trace_event::ConvertableToTraceFormat {
148 // public:
149 // MyData() {}
150 // void AppendAsTraceFormat(std::string* out) const override {
151 // out->append("{\"foo\":1}");
152 // }
153 // private:
154 // ~MyData() override {}
155 // DISALLOW_COPY_AND_ASSIGN(MyData);
156 // };
158 // TRACE_EVENT1("foo", "bar", "data",
159 // scoped_refptr<ConvertableToTraceFormat>(new MyData()));
161 // The trace framework will take ownership if the passed pointer and it will
162 // be free'd when the trace buffer is flushed.
164 // Note, we only do the conversion when the buffer is flushed, so the provided
165 // data object should not be modified after it's passed to the trace framework.
168 // Thread Safety:
169 // A thread safe singleton and mutex are used for thread safety. Category
170 // enabled flags are used to limit the performance impact when the system
171 // is not enabled.
173 // TRACE_EVENT macros first cache a pointer to a category. The categories are
174 // statically allocated and safe at all times, even after exit. Fetching a
175 // category is protected by the TraceLog::lock_. Multiple threads initializing
176 // the static variable is safe, as they will be serialized by the lock and
177 // multiple calls will return the same pointer to the category.
179 // Then the category_group_enabled flag is checked. This is a unsigned char, and
180 // not intended to be multithread safe. It optimizes access to AddTraceEvent
181 // which is threadsafe internally via TraceLog::lock_. The enabled flag may
182 // cause some threads to incorrectly call or skip calling AddTraceEvent near
183 // the time of the system being enabled or disabled. This is acceptable as
184 // we tolerate some data loss while the system is being enabled/disabled and
185 // because AddTraceEvent is threadsafe internally and checks the enabled state
186 // again under lock.
188 // Without the use of these static category pointers and enabled flags all
189 // trace points would carry a significant performance cost of acquiring a lock
190 // and resolving the category.
192 #if defined(TRACE_EVENT0)
193 #error "Another copy of this file has already been included."
194 #endif
196 // This will mark the trace event as disabled by default. The user will need
197 // to explicitly enable the event.
198 #define TRACE_DISABLED_BY_DEFAULT(name) "disabled-by-default-" name
200 // Records a pair of begin and end events called "name" for the current
201 // scope, with 0, 1 or 2 associated arguments. If the category is not
202 // enabled, then this does nothing.
203 // - category and name strings must have application lifetime (statics or
204 // literals). They may not include " chars.
205 #define TRACE_EVENT0(category_group, name) \
206 INTERNAL_TRACE_MEMORY(category_group, name) \
207 INTERNAL_TRACE_EVENT_ADD_SCOPED(category_group, name)
208 #define TRACE_EVENT_WITH_FLOW0(category_group, name, bind_id, flow_flags) \
209 INTERNAL_TRACE_MEMORY(category_group, name) \
210 INTERNAL_TRACE_EVENT_ADD_SCOPED_WITH_FLOW(category_group, name, bind_id, \
211 flow_flags)
212 #define TRACE_EVENT1(category_group, name, arg1_name, arg1_val) \
213 INTERNAL_TRACE_MEMORY(category_group, name) \
214 INTERNAL_TRACE_EVENT_ADD_SCOPED(category_group, name, arg1_name, arg1_val)
215 #define TRACE_EVENT_WITH_FLOW1(category_group, name, bind_id, flow_flags, \
216 arg1_name, arg1_val) \
217 INTERNAL_TRACE_MEMORY(category_group, name) \
218 INTERNAL_TRACE_EVENT_ADD_SCOPED_WITH_FLOW(category_group, name, bind_id, \
219 flow_flags, arg1_name, arg1_val)
220 #define TRACE_EVENT2(category_group, name, arg1_name, arg1_val, arg2_name, \
221 arg2_val) \
222 INTERNAL_TRACE_MEMORY(category_group, name) \
223 INTERNAL_TRACE_EVENT_ADD_SCOPED(category_group, name, arg1_name, arg1_val, \
224 arg2_name, arg2_val)
225 #define TRACE_EVENT_WITH_FLOW2(category_group, name, bind_id, flow_flags, \
226 arg1_name, arg1_val, arg2_name, arg2_val) \
227 INTERNAL_TRACE_MEMORY(category_group, name) \
228 INTERNAL_TRACE_EVENT_ADD_SCOPED_WITH_FLOW(category_group, name, bind_id, \
229 flow_flags, arg1_name, arg1_val, \
230 arg2_name, arg2_val)
232 // Records events like TRACE_EVENT2 but uses |memory_tag| for memory tracing.
233 // Use this where |name| is too generic to accurately aggregate allocations.
234 #define TRACE_EVENT_WITH_MEMORY_TAG2(category, name, memory_tag, arg1_name, \
235 arg1_val, arg2_name, arg2_val) \
236 INTERNAL_TRACE_MEMORY(category, memory_tag) \
237 INTERNAL_TRACE_EVENT_ADD_SCOPED(category, name, arg1_name, arg1_val, \
238 arg2_name, arg2_val)
240 // UNSHIPPED_TRACE_EVENT* are like TRACE_EVENT* except that they are not
241 // included in official builds.
243 #if OFFICIAL_BUILD
244 #undef TRACING_IS_OFFICIAL_BUILD
245 #define TRACING_IS_OFFICIAL_BUILD 1
246 #elif !defined(TRACING_IS_OFFICIAL_BUILD)
247 #define TRACING_IS_OFFICIAL_BUILD 0
248 #endif
250 #if TRACING_IS_OFFICIAL_BUILD
251 #define UNSHIPPED_TRACE_EVENT0(category_group, name) (void)0
252 #define UNSHIPPED_TRACE_EVENT1(category_group, name, arg1_name, arg1_val) \
253 (void)0
254 #define UNSHIPPED_TRACE_EVENT2(category_group, name, arg1_name, arg1_val, \
255 arg2_name, arg2_val) \
256 (void)0
257 #define UNSHIPPED_TRACE_EVENT_INSTANT0(category_group, name, scope) (void)0
258 #define UNSHIPPED_TRACE_EVENT_INSTANT1(category_group, name, scope, arg1_name, \
259 arg1_val) \
260 (void)0
261 #define UNSHIPPED_TRACE_EVENT_INSTANT2(category_group, name, scope, arg1_name, \
262 arg1_val, arg2_name, arg2_val) \
263 (void)0
264 #else
265 #define UNSHIPPED_TRACE_EVENT0(category_group, name) \
266 TRACE_EVENT0(category_group, name)
267 #define UNSHIPPED_TRACE_EVENT1(category_group, name, arg1_name, arg1_val) \
268 TRACE_EVENT1(category_group, name, arg1_name, arg1_val)
269 #define UNSHIPPED_TRACE_EVENT2(category_group, name, arg1_name, arg1_val, \
270 arg2_name, arg2_val) \
271 TRACE_EVENT2(category_group, name, arg1_name, arg1_val, arg2_name, arg2_val)
272 #define UNSHIPPED_TRACE_EVENT_INSTANT0(category_group, name, scope) \
273 TRACE_EVENT_INSTANT0(category_group, name, scope)
274 #define UNSHIPPED_TRACE_EVENT_INSTANT1(category_group, name, scope, arg1_name, \
275 arg1_val) \
276 TRACE_EVENT_INSTANT1(category_group, name, scope, arg1_name, arg1_val)
277 #define UNSHIPPED_TRACE_EVENT_INSTANT2(category_group, name, scope, arg1_name, \
278 arg1_val, arg2_name, arg2_val) \
279 TRACE_EVENT_INSTANT2(category_group, name, scope, arg1_name, arg1_val, \
280 arg2_name, arg2_val)
281 #endif
283 // Records a single event called "name" immediately, with 0, 1 or 2
284 // associated arguments. If the category is not enabled, then this
285 // does nothing.
286 // - category and name strings must have application lifetime (statics or
287 // literals). They may not include " chars.
288 #define TRACE_EVENT_INSTANT0(category_group, name, scope) \
289 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \
290 TRACE_EVENT_FLAG_NONE | scope)
291 #define TRACE_EVENT_INSTANT1(category_group, name, scope, arg1_name, arg1_val) \
292 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \
293 TRACE_EVENT_FLAG_NONE | scope, arg1_name, arg1_val)
294 #define TRACE_EVENT_INSTANT2(category_group, name, scope, arg1_name, arg1_val, \
295 arg2_name, arg2_val) \
296 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \
297 TRACE_EVENT_FLAG_NONE | scope, arg1_name, arg1_val, \
298 arg2_name, arg2_val)
299 #define TRACE_EVENT_COPY_INSTANT0(category_group, name, scope) \
300 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \
301 TRACE_EVENT_FLAG_COPY | scope)
302 #define TRACE_EVENT_COPY_INSTANT1(category_group, name, scope, arg1_name, \
303 arg1_val) \
304 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \
305 TRACE_EVENT_FLAG_COPY | scope, arg1_name, arg1_val)
306 #define TRACE_EVENT_COPY_INSTANT2(category_group, name, scope, arg1_name, \
307 arg1_val, arg2_name, arg2_val) \
308 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \
309 TRACE_EVENT_FLAG_COPY | scope, arg1_name, arg1_val, \
310 arg2_name, arg2_val)
312 // Syntactic sugars for the sampling tracing in the main thread.
313 #define TRACE_EVENT_SCOPED_SAMPLING_STATE(category, name) \
314 TRACE_EVENT_SCOPED_SAMPLING_STATE_FOR_BUCKET(0, category, name)
315 #define TRACE_EVENT_GET_SAMPLING_STATE() \
316 TRACE_EVENT_GET_SAMPLING_STATE_FOR_BUCKET(0)
317 #define TRACE_EVENT_SET_SAMPLING_STATE(category, name) \
318 TRACE_EVENT_SET_SAMPLING_STATE_FOR_BUCKET(0, category, name)
319 #define TRACE_EVENT_SET_NONCONST_SAMPLING_STATE(categoryAndName) \
320 TRACE_EVENT_SET_NONCONST_SAMPLING_STATE_FOR_BUCKET(0, categoryAndName)
322 // Records a single BEGIN event called "name" immediately, with 0, 1 or 2
323 // associated arguments. If the category is not enabled, then this
324 // does nothing.
325 // - category and name strings must have application lifetime (statics or
326 // literals). They may not include " chars.
327 #define TRACE_EVENT_BEGIN0(category_group, name) \
328 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \
329 TRACE_EVENT_FLAG_NONE)
330 #define TRACE_EVENT_BEGIN1(category_group, name, arg1_name, arg1_val) \
331 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \
332 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
333 #define TRACE_EVENT_BEGIN2(category_group, name, arg1_name, arg1_val, \
334 arg2_name, arg2_val) \
335 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \
336 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
337 arg2_name, arg2_val)
338 #define TRACE_EVENT_COPY_BEGIN0(category_group, name) \
339 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \
340 TRACE_EVENT_FLAG_COPY)
341 #define TRACE_EVENT_COPY_BEGIN1(category_group, name, arg1_name, arg1_val) \
342 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \
343 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
344 #define TRACE_EVENT_COPY_BEGIN2(category_group, name, arg1_name, arg1_val, \
345 arg2_name, arg2_val) \
346 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \
347 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \
348 arg2_name, arg2_val)
350 // Similar to TRACE_EVENT_BEGINx but with a custom |at| timestamp provided.
351 // - |id| is used to match the _BEGIN event with the _END event.
352 // Events are considered to match if their category_group, name and id values
353 // all match. |id| must either be a pointer or an integer value up to 64 bits.
354 // If it's a pointer, the bits will be xored with a hash of the process ID so
355 // that the same pointer on two different processes will not collide.
356 #define TRACE_EVENT_BEGIN_WITH_ID_TID_AND_TIMESTAMP0(category_group, name, id, \
357 thread_id, timestamp) \
358 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
359 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \
360 timestamp, TRACE_EVENT_FLAG_NONE)
361 #define TRACE_EVENT_COPY_BEGIN_WITH_ID_TID_AND_TIMESTAMP0( \
362 category_group, name, id, thread_id, timestamp) \
363 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
364 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \
365 timestamp, TRACE_EVENT_FLAG_COPY)
366 #define TRACE_EVENT_COPY_BEGIN_WITH_ID_TID_AND_TIMESTAMP1( \
367 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val) \
368 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
369 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \
370 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
371 #define TRACE_EVENT_COPY_BEGIN_WITH_ID_TID_AND_TIMESTAMP2( \
372 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val, \
373 arg2_name, arg2_val) \
374 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
375 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \
376 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, \
377 arg2_val)
379 // Records a single END event for "name" immediately. If the category
380 // is not enabled, then this does nothing.
381 // - category and name strings must have application lifetime (statics or
382 // literals). They may not include " chars.
383 #define TRACE_EVENT_END0(category_group, name) \
384 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \
385 TRACE_EVENT_FLAG_NONE)
386 #define TRACE_EVENT_END1(category_group, name, arg1_name, arg1_val) \
387 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \
388 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
389 #define TRACE_EVENT_END2(category_group, name, arg1_name, arg1_val, arg2_name, \
390 arg2_val) \
391 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \
392 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \
393 arg2_name, arg2_val)
394 #define TRACE_EVENT_COPY_END0(category_group, name) \
395 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \
396 TRACE_EVENT_FLAG_COPY)
397 #define TRACE_EVENT_COPY_END1(category_group, name, arg1_name, arg1_val) \
398 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \
399 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
400 #define TRACE_EVENT_COPY_END2(category_group, name, arg1_name, arg1_val, \
401 arg2_name, arg2_val) \
402 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \
403 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \
404 arg2_name, arg2_val)
406 #define TRACE_EVENT_MARK(category_group, name) \
407 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_MARK, category_group, name, \
408 TRACE_EVENT_FLAG_NONE)
410 #define TRACE_EVENT_MARK_WITH_TIMESTAMP(category_group, name, timestamp) \
411 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP(TRACE_EVENT_PHASE_MARK, \
412 category_group, name, timestamp, \
413 TRACE_EVENT_FLAG_NONE)
415 #define TRACE_EVENT_COPY_MARK(category_group, name) \
416 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_MARK, category_group, name, \
417 TRACE_EVENT_FLAG_COPY)
419 #define TRACE_EVENT_COPY_MARK_WITH_TIMESTAMP(category_group, name, timestamp) \
420 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP(TRACE_EVENT_PHASE_MARK, \
421 category_group, name, timestamp, \
422 TRACE_EVENT_FLAG_COPY)
424 // Similar to TRACE_EVENT_ENDx but with a custom |at| timestamp provided.
425 // - |id| is used to match the _BEGIN event with the _END event.
426 // Events are considered to match if their category_group, name and id values
427 // all match. |id| must either be a pointer or an integer value up to 64 bits.
428 // If it's a pointer, the bits will be xored with a hash of the process ID so
429 // that the same pointer on two different processes will not collide.
430 #define TRACE_EVENT_END_WITH_ID_TID_AND_TIMESTAMP0(category_group, name, id, \
431 thread_id, timestamp) \
432 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
433 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \
434 timestamp, TRACE_EVENT_FLAG_NONE)
435 #define TRACE_EVENT_COPY_END_WITH_ID_TID_AND_TIMESTAMP0( \
436 category_group, name, id, thread_id, timestamp) \
437 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
438 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \
439 timestamp, TRACE_EVENT_FLAG_COPY)
440 #define TRACE_EVENT_COPY_END_WITH_ID_TID_AND_TIMESTAMP1( \
441 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val) \
442 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
443 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \
444 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
445 #define TRACE_EVENT_COPY_END_WITH_ID_TID_AND_TIMESTAMP2( \
446 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val, \
447 arg2_name, arg2_val) \
448 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
449 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \
450 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, \
451 arg2_val)
453 // Records the value of a counter called "name" immediately. Value
454 // must be representable as a 32 bit integer.
455 // - category and name strings must have application lifetime (statics or
456 // literals). They may not include " chars.
457 #define TRACE_COUNTER1(category_group, name, value) \
458 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \
459 TRACE_EVENT_FLAG_NONE, "value", \
460 static_cast<int>(value))
461 #define TRACE_COPY_COUNTER1(category_group, name, value) \
462 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \
463 TRACE_EVENT_FLAG_COPY, "value", \
464 static_cast<int>(value))
466 // Records the values of a multi-parted counter called "name" immediately.
467 // The UI will treat value1 and value2 as parts of a whole, displaying their
468 // values as a stacked-bar chart.
469 // - category and name strings must have application lifetime (statics or
470 // literals). They may not include " chars.
471 #define TRACE_COUNTER2(category_group, name, value1_name, value1_val, \
472 value2_name, value2_val) \
473 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \
474 TRACE_EVENT_FLAG_NONE, value1_name, \
475 static_cast<int>(value1_val), value2_name, \
476 static_cast<int>(value2_val))
477 #define TRACE_COPY_COUNTER2(category_group, name, value1_name, value1_val, \
478 value2_name, value2_val) \
479 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \
480 TRACE_EVENT_FLAG_COPY, value1_name, \
481 static_cast<int>(value1_val), value2_name, \
482 static_cast<int>(value2_val))
484 // Records the value of a counter called "name" immediately. Value
485 // must be representable as a 32 bit integer.
486 // - category and name strings must have application lifetime (statics or
487 // literals). They may not include " chars.
488 // - |id| is used to disambiguate counters with the same name. It must either
489 // be a pointer or an integer value up to 64 bits. If it's a pointer, the bits
490 // will be xored with a hash of the process ID so that the same pointer on
491 // two different processes will not collide.
492 #define TRACE_COUNTER_ID1(category_group, name, id, value) \
493 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \
494 name, id, TRACE_EVENT_FLAG_NONE, "value", \
495 static_cast<int>(value))
496 #define TRACE_COPY_COUNTER_ID1(category_group, name, id, value) \
497 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \
498 name, id, TRACE_EVENT_FLAG_COPY, "value", \
499 static_cast<int>(value))
501 // Records the values of a multi-parted counter called "name" immediately.
502 // The UI will treat value1 and value2 as parts of a whole, displaying their
503 // values as a stacked-bar chart.
504 // - category and name strings must have application lifetime (statics or
505 // literals). They may not include " chars.
506 // - |id| is used to disambiguate counters with the same name. It must either
507 // be a pointer or an integer value up to 64 bits. If it's a pointer, the bits
508 // will be xored with a hash of the process ID so that the same pointer on
509 // two different processes will not collide.
510 #define TRACE_COUNTER_ID2(category_group, name, id, value1_name, value1_val, \
511 value2_name, value2_val) \
512 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \
513 name, id, TRACE_EVENT_FLAG_NONE, \
514 value1_name, static_cast<int>(value1_val), \
515 value2_name, static_cast<int>(value2_val))
516 #define TRACE_COPY_COUNTER_ID2(category_group, name, id, value1_name, \
517 value1_val, value2_name, value2_val) \
518 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \
519 name, id, TRACE_EVENT_FLAG_COPY, \
520 value1_name, static_cast<int>(value1_val), \
521 value2_name, static_cast<int>(value2_val))
523 // TRACE_EVENT_SAMPLE_* events are injected by the sampling profiler.
524 #define TRACE_EVENT_SAMPLE_WITH_TID_AND_TIMESTAMP0(category_group, name, \
525 thread_id, timestamp) \
526 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
527 TRACE_EVENT_PHASE_SAMPLE, category_group, name, 0, thread_id, timestamp, \
528 TRACE_EVENT_FLAG_NONE)
530 #define TRACE_EVENT_SAMPLE_WITH_TID_AND_TIMESTAMP1( \
531 category_group, name, thread_id, timestamp, arg1_name, arg1_val) \
532 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
533 TRACE_EVENT_PHASE_SAMPLE, category_group, name, 0, thread_id, timestamp, \
534 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
536 #define TRACE_EVENT_SAMPLE_WITH_TID_AND_TIMESTAMP2(category_group, name, \
537 thread_id, timestamp, \
538 arg1_name, arg1_val, \
539 arg2_name, arg2_val) \
540 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
541 TRACE_EVENT_PHASE_SAMPLE, category_group, name, 0, thread_id, timestamp, \
542 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
544 // ASYNC_STEP_* APIs should be only used by legacy code. New code should
545 // consider using NESTABLE_ASYNC_* APIs to describe substeps within an async
546 // event.
547 // Records a single ASYNC_BEGIN event called "name" immediately, with 0, 1 or 2
548 // associated arguments. If the category is not enabled, then this
549 // does nothing.
550 // - category and name strings must have application lifetime (statics or
551 // literals). They may not include " chars.
552 // - |id| is used to match the ASYNC_BEGIN event with the ASYNC_END event. ASYNC
553 // events are considered to match if their category_group, name and id values
554 // all match. |id| must either be a pointer or an integer value up to 64 bits.
555 // If it's a pointer, the bits will be xored with a hash of the process ID so
556 // that the same pointer on two different processes will not collide.
558 // An asynchronous operation can consist of multiple phases. The first phase is
559 // defined by the ASYNC_BEGIN calls. Additional phases can be defined using the
560 // ASYNC_STEP_INTO or ASYNC_STEP_PAST macros. The ASYNC_STEP_INTO macro will
561 // annotate the block following the call. The ASYNC_STEP_PAST macro will
562 // annotate the block prior to the call. Note that any particular event must use
563 // only STEP_INTO or STEP_PAST macros; they can not mix and match. When the
564 // operation completes, call ASYNC_END.
566 // An ASYNC trace typically occurs on a single thread (if not, they will only be
567 // drawn on the thread defined in the ASYNC_BEGIN event), but all events in that
568 // operation must use the same |name| and |id|. Each step can have its own
569 // args.
570 #define TRACE_EVENT_ASYNC_BEGIN0(category_group, name, id) \
571 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \
572 category_group, name, id, \
573 TRACE_EVENT_FLAG_NONE)
574 #define TRACE_EVENT_ASYNC_BEGIN1(category_group, name, id, arg1_name, \
575 arg1_val) \
576 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \
577 category_group, name, id, \
578 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
579 #define TRACE_EVENT_ASYNC_BEGIN2(category_group, name, id, arg1_name, \
580 arg1_val, arg2_name, arg2_val) \
581 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
582 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \
583 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
584 #define TRACE_EVENT_COPY_ASYNC_BEGIN0(category_group, name, id) \
585 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \
586 category_group, name, id, \
587 TRACE_EVENT_FLAG_COPY)
588 #define TRACE_EVENT_COPY_ASYNC_BEGIN1(category_group, name, id, arg1_name, \
589 arg1_val) \
590 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \
591 category_group, name, id, \
592 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
593 #define TRACE_EVENT_COPY_ASYNC_BEGIN2(category_group, name, id, arg1_name, \
594 arg1_val, arg2_name, arg2_val) \
595 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
596 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \
597 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, arg2_val)
599 // Similar to TRACE_EVENT_ASYNC_BEGINx but with a custom |at| timestamp
600 // provided.
601 #define TRACE_EVENT_ASYNC_BEGIN_WITH_TIMESTAMP0(category_group, name, id, \
602 timestamp) \
603 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
604 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \
605 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE)
606 #define TRACE_EVENT_COPY_ASYNC_BEGIN_WITH_TIMESTAMP0(category_group, name, id, \
607 timestamp) \
608 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
609 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \
610 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_COPY)
612 // Records a single ASYNC_STEP_INTO event for |step| immediately. If the
613 // category is not enabled, then this does nothing. The |name| and |id| must
614 // match the ASYNC_BEGIN event above. The |step| param identifies this step
615 // within the async event. This should be called at the beginning of the next
616 // phase of an asynchronous operation. The ASYNC_BEGIN event must not have any
617 // ASYNC_STEP_PAST events.
618 #define TRACE_EVENT_ASYNC_STEP_INTO0(category_group, name, id, step) \
619 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_STEP_INTO, \
620 category_group, name, id, \
621 TRACE_EVENT_FLAG_NONE, "step", step)
622 #define TRACE_EVENT_ASYNC_STEP_INTO1(category_group, name, id, step, \
623 arg1_name, arg1_val) \
624 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
625 TRACE_EVENT_PHASE_ASYNC_STEP_INTO, category_group, name, id, \
626 TRACE_EVENT_FLAG_NONE, "step", step, arg1_name, arg1_val)
628 // Similar to TRACE_EVENT_ASYNC_STEP_INTOx but with a custom |at| timestamp
629 // provided.
630 #define TRACE_EVENT_ASYNC_STEP_INTO_WITH_TIMESTAMP0(category_group, name, id, \
631 step, timestamp) \
632 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
633 TRACE_EVENT_PHASE_ASYNC_STEP_INTO, category_group, name, id, \
634 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \
635 "step", step)
637 // Records a single ASYNC_STEP_PAST event for |step| immediately. If the
638 // category is not enabled, then this does nothing. The |name| and |id| must
639 // match the ASYNC_BEGIN event above. The |step| param identifies this step
640 // within the async event. This should be called at the beginning of the next
641 // phase of an asynchronous operation. The ASYNC_BEGIN event must not have any
642 // ASYNC_STEP_INTO events.
643 #define TRACE_EVENT_ASYNC_STEP_PAST0(category_group, name, id, step) \
644 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_STEP_PAST, \
645 category_group, name, id, \
646 TRACE_EVENT_FLAG_NONE, "step", step)
647 #define TRACE_EVENT_ASYNC_STEP_PAST1(category_group, name, id, step, \
648 arg1_name, arg1_val) \
649 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
650 TRACE_EVENT_PHASE_ASYNC_STEP_PAST, category_group, name, id, \
651 TRACE_EVENT_FLAG_NONE, "step", step, arg1_name, arg1_val)
653 // Records a single ASYNC_END event for "name" immediately. If the category
654 // is not enabled, then this does nothing.
655 #define TRACE_EVENT_ASYNC_END0(category_group, name, id) \
656 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \
657 category_group, name, id, \
658 TRACE_EVENT_FLAG_NONE)
659 #define TRACE_EVENT_ASYNC_END1(category_group, name, id, arg1_name, arg1_val) \
660 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \
661 category_group, name, id, \
662 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
663 #define TRACE_EVENT_ASYNC_END2(category_group, name, id, arg1_name, arg1_val, \
664 arg2_name, arg2_val) \
665 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
666 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \
667 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
668 #define TRACE_EVENT_COPY_ASYNC_END0(category_group, name, id) \
669 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \
670 category_group, name, id, \
671 TRACE_EVENT_FLAG_COPY)
672 #define TRACE_EVENT_COPY_ASYNC_END1(category_group, name, id, arg1_name, \
673 arg1_val) \
674 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \
675 category_group, name, id, \
676 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
677 #define TRACE_EVENT_COPY_ASYNC_END2(category_group, name, id, arg1_name, \
678 arg1_val, arg2_name, arg2_val) \
679 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
680 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \
681 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, arg2_val)
683 // Similar to TRACE_EVENT_ASYNC_ENDx but with a custom |at| timestamp provided.
684 #define TRACE_EVENT_ASYNC_END_WITH_TIMESTAMP0(category_group, name, id, \
685 timestamp) \
686 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
687 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \
688 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE)
690 // NESTABLE_ASYNC_* APIs are used to describe an async operation, which can
691 // be nested within a NESTABLE_ASYNC event and/or have inner NESTABLE_ASYNC
692 // events.
693 // - category and name strings must have application lifetime (statics or
694 // literals). They may not include " chars.
695 // - A pair of NESTABLE_ASYNC_BEGIN event and NESTABLE_ASYNC_END event is
696 // considered as a match if their category_group, name and id all match.
697 // - |id| must either be a pointer or an integer value up to 64 bits.
698 // If it's a pointer, the bits will be xored with a hash of the process ID so
699 // that the same pointer on two different processes will not collide.
700 // - |id| is used to match a child NESTABLE_ASYNC event with its parent
701 // NESTABLE_ASYNC event. Therefore, events in the same nested event tree must
702 // be logged using the same id and category_group.
704 // Unmatched NESTABLE_ASYNC_END event will be parsed as an event that starts
705 // at the first NESTABLE_ASYNC event of that id, and unmatched
706 // NESTABLE_ASYNC_BEGIN event will be parsed as an event that ends at the last
707 // NESTABLE_ASYNC event of that id. Corresponding warning messages for
708 // unmatched events will be shown in the analysis view.
710 // Records a single NESTABLE_ASYNC_BEGIN event called "name" immediately, with
711 // 0, 1 or 2 associated arguments. If the category is not enabled, then this
712 // does nothing.
713 #define TRACE_EVENT_NESTABLE_ASYNC_BEGIN0(category_group, name, id) \
714 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, \
715 category_group, name, id, \
716 TRACE_EVENT_FLAG_NONE)
717 #define TRACE_EVENT_NESTABLE_ASYNC_BEGIN1(category_group, name, id, arg1_name, \
718 arg1_val) \
719 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, \
720 category_group, name, id, \
721 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
722 #define TRACE_EVENT_NESTABLE_ASYNC_BEGIN2(category_group, name, id, arg1_name, \
723 arg1_val, arg2_name, arg2_val) \
724 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
725 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \
726 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
727 // Records a single NESTABLE_ASYNC_END event called "name" immediately, with 0
728 // or 2 associated arguments. If the category is not enabled, then this does
729 // nothing.
730 #define TRACE_EVENT_NESTABLE_ASYNC_END0(category_group, name, id) \
731 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, \
732 category_group, name, id, \
733 TRACE_EVENT_FLAG_NONE)
734 // Records a single NESTABLE_ASYNC_END event called "name" immediately, with 1
735 // associated argument. If the category is not enabled, then this does nothing.
736 #define TRACE_EVENT_NESTABLE_ASYNC_END1(category_group, name, id, arg1_name, \
737 arg1_val) \
738 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, \
739 category_group, name, id, \
740 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
741 #define TRACE_EVENT_NESTABLE_ASYNC_END2(category_group, name, id, arg1_name, \
742 arg1_val, arg2_name, arg2_val) \
743 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
744 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \
745 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
747 // Records a single NESTABLE_ASYNC_INSTANT event called "name" immediately,
748 // with one associated argument. If the category is not enabled, then this
749 // does nothing.
750 #define TRACE_EVENT_NESTABLE_ASYNC_INSTANT1(category_group, name, id, \
751 arg1_name, arg1_val) \
752 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT, \
753 category_group, name, id, \
754 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
755 // Records a single NESTABLE_ASYNC_INSTANT event called "name" immediately,
756 // with 2 associated arguments. If the category is not enabled, then this
757 // does nothing.
758 #define TRACE_EVENT_NESTABLE_ASYNC_INSTANT2( \
759 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \
760 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
761 TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT, category_group, name, id, \
762 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
764 #define TRACE_EVENT_COPY_NESTABLE_ASYNC_BEGIN_WITH_TTS2( \
765 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \
766 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
767 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \
768 TRACE_EVENT_FLAG_ASYNC_TTS | TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \
769 arg2_name, arg2_val)
770 #define TRACE_EVENT_COPY_NESTABLE_ASYNC_END_WITH_TTS2( \
771 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \
772 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
773 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \
774 TRACE_EVENT_FLAG_ASYNC_TTS | TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \
775 arg2_name, arg2_val)
777 // Similar to TRACE_EVENT_NESTABLE_ASYNC_{BEGIN,END}x but with a custom
778 // |timestamp| provided.
779 #define TRACE_EVENT_NESTABLE_ASYNC_BEGIN_WITH_TIMESTAMP0(category_group, name, \
780 id, timestamp) \
781 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
782 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \
783 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE)
785 #define TRACE_EVENT_NESTABLE_ASYNC_END_WITH_TIMESTAMP0(category_group, name, \
786 id, timestamp) \
787 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
788 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \
789 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE)
791 #define TRACE_EVENT_COPY_NESTABLE_ASYNC_BEGIN_WITH_TIMESTAMP0( \
792 category_group, name, id, timestamp) \
793 INTERNAL_TRACE_EVENT_ADD_WITH_ID_AND_TIMESTAMP( \
794 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \
795 timestamp, TRACE_EVENT_FLAG_COPY)
796 #define TRACE_EVENT_COPY_NESTABLE_ASYNC_END_WITH_TIMESTAMP0( \
797 category_group, name, id, timestamp) \
798 INTERNAL_TRACE_EVENT_ADD_WITH_ID_AND_TIMESTAMP( \
799 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \
800 timestamp, TRACE_EVENT_FLAG_COPY)
802 // Records a single NESTABLE_ASYNC_INSTANT event called "name" immediately,
803 // with 2 associated arguments. If the category is not enabled, then this
804 // does nothing.
805 #define TRACE_EVENT_NESTABLE_ASYNC_INSTANT2( \
806 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \
807 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
808 TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT, category_group, name, id, \
809 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
811 // Records a single FLOW_BEGIN event called "name" immediately, with 0, 1 or 2
812 // associated arguments. If the category is not enabled, then this
813 // does nothing.
814 // - category and name strings must have application lifetime (statics or
815 // literals). They may not include " chars.
816 // - |id| is used to match the FLOW_BEGIN event with the FLOW_END event. FLOW
817 // events are considered to match if their category_group, name and id values
818 // all match. |id| must either be a pointer or an integer value up to 64 bits.
819 // If it's a pointer, the bits will be xored with a hash of the process ID so
820 // that the same pointer on two different processes will not collide.
821 // FLOW events are different from ASYNC events in how they are drawn by the
822 // tracing UI. A FLOW defines asynchronous data flow, such as posting a task
823 // (FLOW_BEGIN) and later executing that task (FLOW_END). Expect FLOWs to be
824 // drawn as lines or arrows from FLOW_BEGIN scopes to FLOW_END scopes. Similar
825 // to ASYNC, a FLOW can consist of multiple phases. The first phase is defined
826 // by the FLOW_BEGIN calls. Additional phases can be defined using the FLOW_STEP
827 // macros. When the operation completes, call FLOW_END. An async operation can
828 // span threads and processes, but all events in that operation must use the
829 // same |name| and |id|. Each event can have its own args.
830 #define TRACE_EVENT_FLOW_BEGIN0(category_group, name, id) \
831 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \
832 category_group, name, id, \
833 TRACE_EVENT_FLAG_NONE)
834 #define TRACE_EVENT_FLOW_BEGIN1(category_group, name, id, arg1_name, arg1_val) \
835 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \
836 category_group, name, id, \
837 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val)
838 #define TRACE_EVENT_FLOW_BEGIN2(category_group, name, id, arg1_name, arg1_val, \
839 arg2_name, arg2_val) \
840 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
841 TRACE_EVENT_PHASE_FLOW_BEGIN, category_group, name, id, \
842 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val)
843 #define TRACE_EVENT_COPY_FLOW_BEGIN0(category_group, name, id) \
844 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \
845 category_group, name, id, \
846 TRACE_EVENT_FLAG_COPY)
847 #define TRACE_EVENT_COPY_FLOW_BEGIN1(category_group, name, id, arg1_name, \
848 arg1_val) \
849 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \
850 category_group, name, id, \
851 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val)
852 #define TRACE_EVENT_COPY_FLOW_BEGIN2(category_group, name, id, arg1_name, \
853 arg1_val, arg2_name, arg2_val) \
854 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
855 TRACE_EVENT_PHASE_FLOW_BEGIN, category_group, name, id, \
856 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, arg2_val)
858 // Records a single FLOW_STEP event for |step| immediately. If the category
859 // is not enabled, then this does nothing. The |name| and |id| must match the
860 // FLOW_BEGIN event above. The |step| param identifies this step within the
861 // async event. This should be called at the beginning of the next phase of an
862 // asynchronous operation.
863 #define TRACE_EVENT_FLOW_STEP0(category_group, name, id, step) \
864 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_STEP, \
865 category_group, name, id, \
866 TRACE_EVENT_FLAG_NONE, "step", step)
867 #define TRACE_EVENT_FLOW_STEP1(category_group, name, id, step, arg1_name, \
868 arg1_val) \
869 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
870 TRACE_EVENT_PHASE_FLOW_STEP, category_group, name, id, \
871 TRACE_EVENT_FLAG_NONE, "step", step, arg1_name, arg1_val)
872 #define TRACE_EVENT_COPY_FLOW_STEP0(category_group, name, id, step) \
873 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_STEP, \
874 category_group, name, id, \
875 TRACE_EVENT_FLAG_COPY, "step", step)
876 #define TRACE_EVENT_COPY_FLOW_STEP1(category_group, name, id, step, arg1_name, \
877 arg1_val) \
878 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
879 TRACE_EVENT_PHASE_FLOW_STEP, category_group, name, id, \
880 TRACE_EVENT_FLAG_COPY, "step", step, arg1_name, arg1_val)
882 // Records a single FLOW_END event for "name" immediately. If the category
883 // is not enabled, then this does nothing.
884 #define TRACE_EVENT_FLOW_END0(category_group, name, id) \
885 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
886 name, id, TRACE_EVENT_FLAG_NONE)
887 #define TRACE_EVENT_FLOW_END_BIND_TO_ENCLOSING0(category_group, name, id) \
888 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
889 name, id, \
890 TRACE_EVENT_FLAG_BIND_TO_ENCLOSING)
891 #define TRACE_EVENT_FLOW_END1(category_group, name, id, arg1_name, arg1_val) \
892 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
893 name, id, TRACE_EVENT_FLAG_NONE, arg1_name, \
894 arg1_val)
895 #define TRACE_EVENT_FLOW_END2(category_group, name, id, arg1_name, arg1_val, \
896 arg2_name, arg2_val) \
897 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
898 name, id, TRACE_EVENT_FLAG_NONE, arg1_name, \
899 arg1_val, arg2_name, arg2_val)
900 #define TRACE_EVENT_COPY_FLOW_END0(category_group, name, id) \
901 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
902 name, id, TRACE_EVENT_FLAG_COPY)
903 #define TRACE_EVENT_COPY_FLOW_END1(category_group, name, id, arg1_name, \
904 arg1_val) \
905 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
906 name, id, TRACE_EVENT_FLAG_COPY, arg1_name, \
907 arg1_val)
908 #define TRACE_EVENT_COPY_FLOW_END2(category_group, name, id, arg1_name, \
909 arg1_val, arg2_name, arg2_val) \
910 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \
911 name, id, TRACE_EVENT_FLAG_COPY, arg1_name, \
912 arg1_val, arg2_name, arg2_val)
914 // Macros to track the life time and value of arbitrary client objects.
915 // See also TraceTrackableObject.
916 #define TRACE_EVENT_OBJECT_CREATED_WITH_ID(category_group, name, id) \
917 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
918 TRACE_EVENT_PHASE_CREATE_OBJECT, category_group, name, \
919 TRACE_ID_DONT_MANGLE(id), TRACE_EVENT_FLAG_NONE)
921 #define TRACE_EVENT_OBJECT_SNAPSHOT_WITH_ID(category_group, name, id, \
922 snapshot) \
923 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
924 TRACE_EVENT_PHASE_SNAPSHOT_OBJECT, category_group, name, \
925 TRACE_ID_DONT_MANGLE(id), TRACE_EVENT_FLAG_NONE, "snapshot", snapshot)
927 #define TRACE_EVENT_OBJECT_SNAPSHOT_WITH_ID_AND_TIMESTAMP( \
928 category_group, name, id, timestamp, snapshot) \
929 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \
930 TRACE_EVENT_PHASE_SNAPSHOT_OBJECT, category_group, name, \
931 TRACE_ID_DONT_MANGLE(id), TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, \
932 TRACE_EVENT_FLAG_NONE, "snapshot", snapshot)
934 #define TRACE_EVENT_OBJECT_DELETED_WITH_ID(category_group, name, id) \
935 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \
936 TRACE_EVENT_PHASE_DELETE_OBJECT, category_group, name, \
937 TRACE_ID_DONT_MANGLE(id), TRACE_EVENT_FLAG_NONE)
939 // Macro to efficiently determine if a given category group is enabled.
940 #define TRACE_EVENT_CATEGORY_GROUP_ENABLED(category_group, ret) \
941 do { \
942 INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category_group); \
943 if (INTERNAL_TRACE_EVENT_CATEGORY_GROUP_ENABLED_FOR_RECORDING_MODE()) { \
944 *ret = true; \
945 } else { \
946 *ret = false; \
948 } while (0)
950 // Macro to explicitly warm up a given category group. This could be useful in
951 // cases where we want to initialize a category group before any trace events
952 // for that category group is reported. For example, to have a category group
953 // always show up in the "record categories" list for manually selecting
954 // settings in about://tracing.
955 #define TRACE_EVENT_WARMUP_CATEGORY(category_group) \
956 INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category_group)
958 // Macro to efficiently determine, through polling, if a new trace has begun.
959 #define TRACE_EVENT_IS_NEW_TRACE(ret) \
960 do { \
961 static int INTERNAL_TRACE_EVENT_UID(lastRecordingNumber) = 0; \
962 int num_traces_recorded = TRACE_EVENT_API_GET_NUM_TRACES_RECORDED(); \
963 if (num_traces_recorded != -1 && \
964 num_traces_recorded != \
965 INTERNAL_TRACE_EVENT_UID(lastRecordingNumber)) { \
966 INTERNAL_TRACE_EVENT_UID(lastRecordingNumber) = num_traces_recorded; \
967 *ret = true; \
968 } else { \
969 *ret = false; \
971 } while (0)
973 // Notes regarding the following definitions:
974 // New values can be added and propagated to third party libraries, but existing
975 // definitions must never be changed, because third party libraries may use old
976 // definitions.
978 // Phase indicates the nature of an event entry. E.g. part of a begin/end pair.
979 #define TRACE_EVENT_PHASE_BEGIN ('B')
980 #define TRACE_EVENT_PHASE_END ('E')
981 #define TRACE_EVENT_PHASE_COMPLETE ('X')
982 #define TRACE_EVENT_PHASE_INSTANT ('I')
983 #define TRACE_EVENT_PHASE_ASYNC_BEGIN ('S')
984 #define TRACE_EVENT_PHASE_ASYNC_STEP_INTO ('T')
985 #define TRACE_EVENT_PHASE_ASYNC_STEP_PAST ('p')
986 #define TRACE_EVENT_PHASE_ASYNC_END ('F')
987 #define TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN ('b')
988 #define TRACE_EVENT_PHASE_NESTABLE_ASYNC_END ('e')
989 #define TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT ('n')
990 #define TRACE_EVENT_PHASE_FLOW_BEGIN ('s')
991 #define TRACE_EVENT_PHASE_FLOW_STEP ('t')
992 #define TRACE_EVENT_PHASE_FLOW_END ('f')
993 #define TRACE_EVENT_PHASE_METADATA ('M')
994 #define TRACE_EVENT_PHASE_COUNTER ('C')
995 #define TRACE_EVENT_PHASE_SAMPLE ('P')
996 #define TRACE_EVENT_PHASE_CREATE_OBJECT ('N')
997 #define TRACE_EVENT_PHASE_SNAPSHOT_OBJECT ('O')
998 #define TRACE_EVENT_PHASE_DELETE_OBJECT ('D')
999 #define TRACE_EVENT_PHASE_MEMORY_DUMP ('v')
1000 #define TRACE_EVENT_PHASE_MARK ('R')
1002 // Flags for changing the behavior of TRACE_EVENT_API_ADD_TRACE_EVENT.
1003 #define TRACE_EVENT_FLAG_NONE (static_cast<unsigned int>(0))
1004 #define TRACE_EVENT_FLAG_COPY (static_cast<unsigned int>(1 << 0))
1005 #define TRACE_EVENT_FLAG_HAS_ID (static_cast<unsigned int>(1 << 1))
1006 #define TRACE_EVENT_FLAG_MANGLE_ID (static_cast<unsigned int>(1 << 2))
1007 #define TRACE_EVENT_FLAG_SCOPE_OFFSET (static_cast<unsigned int>(1 << 3))
1008 #define TRACE_EVENT_FLAG_SCOPE_EXTRA (static_cast<unsigned int>(1 << 4))
1009 #define TRACE_EVENT_FLAG_EXPLICIT_TIMESTAMP (static_cast<unsigned int>(1 << 5))
1010 #define TRACE_EVENT_FLAG_ASYNC_TTS (static_cast<unsigned int>(1 << 6))
1011 #define TRACE_EVENT_FLAG_BIND_TO_ENCLOSING (static_cast<unsigned int>(1 << 7))
1012 #define TRACE_EVENT_FLAG_FLOW_IN (static_cast<unsigned int>(1 << 8))
1013 #define TRACE_EVENT_FLAG_FLOW_OUT (static_cast<unsigned int>(1 << 9))
1014 #define TRACE_EVENT_FLAG_HAS_CONTEXT_ID (static_cast<unsigned int>(1 << 10))
1016 #define TRACE_EVENT_FLAG_SCOPE_MASK \
1017 (static_cast<unsigned int>(TRACE_EVENT_FLAG_SCOPE_OFFSET | \
1018 TRACE_EVENT_FLAG_SCOPE_EXTRA))
1020 // Type values for identifying types in the TraceValue union.
1021 #define TRACE_VALUE_TYPE_BOOL (static_cast<unsigned char>(1))
1022 #define TRACE_VALUE_TYPE_UINT (static_cast<unsigned char>(2))
1023 #define TRACE_VALUE_TYPE_INT (static_cast<unsigned char>(3))
1024 #define TRACE_VALUE_TYPE_DOUBLE (static_cast<unsigned char>(4))
1025 #define TRACE_VALUE_TYPE_POINTER (static_cast<unsigned char>(5))
1026 #define TRACE_VALUE_TYPE_STRING (static_cast<unsigned char>(6))
1027 #define TRACE_VALUE_TYPE_COPY_STRING (static_cast<unsigned char>(7))
1028 #define TRACE_VALUE_TYPE_CONVERTABLE (static_cast<unsigned char>(8))
1030 // Enum reflecting the scope of an INSTANT event. Must fit within
1031 // TRACE_EVENT_FLAG_SCOPE_MASK.
1032 #define TRACE_EVENT_SCOPE_GLOBAL (static_cast<unsigned char>(0 << 3))
1033 #define TRACE_EVENT_SCOPE_PROCESS (static_cast<unsigned char>(1 << 3))
1034 #define TRACE_EVENT_SCOPE_THREAD (static_cast<unsigned char>(2 << 3))
1036 #define TRACE_EVENT_SCOPE_NAME_GLOBAL ('g')
1037 #define TRACE_EVENT_SCOPE_NAME_PROCESS ('p')
1038 #define TRACE_EVENT_SCOPE_NAME_THREAD ('t')