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. 4 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. 11 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. 14 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 19// 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) 25// 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: 29// 30// TRACE_EVENT_INSTANT0("input,views", "OnMouseOver", TRACE_EVENT_SCOPE_THREAD) 31// 32// We can enable/disable tracing of OnMouseOver by enabling/disabling either 33// category. 34// 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. 42// 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// } 49// 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// } 56// 57// The trace system will automatically add to this information the 58// current process id, thread id, and a timestamp in microseconds. 59// 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// } 85// 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); 89// 90// Counters are process-specific. The macro itself can be issued from any 91// thread, however. 92// 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. 103// 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. 106// 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. 111// 112// 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 120// 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. 126// 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")); 137// 138// 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. 146// 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// }; 157// 158// TRACE_EVENT1("foo", "bar", "data", 159// std::unique_ptr<ConvertableToTraceFormat>(new MyData())); 160// 161// The trace framework will take ownership if the passed pointer and it will 162// be free'd when the trace buffer is flushed. 163// 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. 166// 167// 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. 172// 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. 178// 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. 187// 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. 191 192#if defined(TRACE_EVENT0) 193#error "Another copy of this file has already been included." 194#endif 195 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 199 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_EVENT_ADD_SCOPED(category_group, name) 207#define TRACE_EVENT_WITH_FLOW0(category_group, name, bind_id, flow_flags) \ 208 INTERNAL_TRACE_EVENT_ADD_SCOPED_WITH_FLOW(category_group, name, bind_id, \ 209 flow_flags) 210#define TRACE_EVENT1(category_group, name, arg1_name, arg1_val) \ 211 INTERNAL_TRACE_EVENT_ADD_SCOPED(category_group, name, arg1_name, arg1_val) 212#define TRACE_EVENT_WITH_FLOW1(category_group, name, bind_id, flow_flags, \ 213 arg1_name, arg1_val) \ 214 INTERNAL_TRACE_EVENT_ADD_SCOPED_WITH_FLOW(category_group, name, bind_id, \ 215 flow_flags, arg1_name, arg1_val) 216#define TRACE_EVENT2(category_group, name, arg1_name, arg1_val, arg2_name, \ 217 arg2_val) \ 218 INTERNAL_TRACE_EVENT_ADD_SCOPED(category_group, name, arg1_name, arg1_val, \ 219 arg2_name, arg2_val) 220#define TRACE_EVENT_WITH_FLOW2(category_group, name, bind_id, flow_flags, \ 221 arg1_name, arg1_val, arg2_name, arg2_val) \ 222 INTERNAL_TRACE_EVENT_ADD_SCOPED_WITH_FLOW(category_group, name, bind_id, \ 223 flow_flags, arg1_name, arg1_val, \ 224 arg2_name, arg2_val) 225 226// Records a single event called "name" immediately, with 0, 1 or 2 227// associated arguments. If the category is not enabled, then this 228// does nothing. 229// - category and name strings must have application lifetime (statics or 230// literals). They may not include " chars. 231#define TRACE_EVENT_INSTANT0(category_group, name, scope) \ 232 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \ 233 TRACE_EVENT_FLAG_NONE | scope) 234#define TRACE_EVENT_INSTANT1(category_group, name, scope, arg1_name, arg1_val) \ 235 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \ 236 TRACE_EVENT_FLAG_NONE | scope, arg1_name, arg1_val) 237#define TRACE_EVENT_INSTANT2(category_group, name, scope, arg1_name, arg1_val, \ 238 arg2_name, arg2_val) \ 239 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \ 240 TRACE_EVENT_FLAG_NONE | scope, arg1_name, arg1_val, \ 241 arg2_name, arg2_val) 242#define TRACE_EVENT_COPY_INSTANT0(category_group, name, scope) \ 243 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \ 244 TRACE_EVENT_FLAG_COPY | scope) 245#define TRACE_EVENT_COPY_INSTANT1(category_group, name, scope, arg1_name, \ 246 arg1_val) \ 247 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \ 248 TRACE_EVENT_FLAG_COPY | scope, arg1_name, arg1_val) 249#define TRACE_EVENT_COPY_INSTANT2(category_group, name, scope, arg1_name, \ 250 arg1_val, arg2_name, arg2_val) \ 251 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_INSTANT, category_group, name, \ 252 TRACE_EVENT_FLAG_COPY | scope, arg1_name, arg1_val, \ 253 arg2_name, arg2_val) 254 255#define TRACE_EVENT_INSTANT_WITH_TIMESTAMP0(category_group, name, scope, \ 256 timestamp) \ 257 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 258 TRACE_EVENT_PHASE_INSTANT, category_group, name, timestamp, \ 259 TRACE_EVENT_FLAG_NONE | scope) 260 261// Records a single BEGIN event called "name" immediately, with 0, 1 or 2 262// associated arguments. If the category is not enabled, then this 263// does nothing. 264// - category and name strings must have application lifetime (statics or 265// literals). They may not include " chars. 266#define TRACE_EVENT_BEGIN0(category_group, name) \ 267 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \ 268 TRACE_EVENT_FLAG_NONE) 269#define TRACE_EVENT_BEGIN1(category_group, name, arg1_name, arg1_val) \ 270 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \ 271 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 272#define TRACE_EVENT_BEGIN2(category_group, name, arg1_name, arg1_val, \ 273 arg2_name, arg2_val) \ 274 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \ 275 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \ 276 arg2_name, arg2_val) 277#define TRACE_EVENT_COPY_BEGIN0(category_group, name) \ 278 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \ 279 TRACE_EVENT_FLAG_COPY) 280#define TRACE_EVENT_COPY_BEGIN1(category_group, name, arg1_name, arg1_val) \ 281 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \ 282 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 283#define TRACE_EVENT_COPY_BEGIN2(category_group, name, arg1_name, arg1_val, \ 284 arg2_name, arg2_val) \ 285 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_BEGIN, category_group, name, \ 286 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \ 287 arg2_name, arg2_val) 288 289// Similar to TRACE_EVENT_BEGINx but with a custom |at| timestamp provided. 290// - |id| is used to match the _BEGIN event with the _END event. 291// Events are considered to match if their category_group, name and id values 292// all match. |id| must either be a pointer or an integer value up to 64 bits. 293// If it's a pointer, the bits will be xored with a hash of the process ID so 294// that the same pointer on two different processes will not collide. 295#define TRACE_EVENT_BEGIN_WITH_ID_TID_AND_TIMESTAMP0(category_group, name, id, \ 296 thread_id, timestamp) \ 297 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 298 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \ 299 timestamp, TRACE_EVENT_FLAG_NONE) 300#define TRACE_EVENT_COPY_BEGIN_WITH_ID_TID_AND_TIMESTAMP0( \ 301 category_group, name, id, thread_id, timestamp) \ 302 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 303 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \ 304 timestamp, TRACE_EVENT_FLAG_COPY) 305#define TRACE_EVENT_COPY_BEGIN_WITH_ID_TID_AND_TIMESTAMP1( \ 306 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val) \ 307 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 308 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \ 309 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 310#define TRACE_EVENT_COPY_BEGIN_WITH_ID_TID_AND_TIMESTAMP2( \ 311 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val, \ 312 arg2_name, arg2_val) \ 313 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 314 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, thread_id, \ 315 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, \ 316 arg2_val) 317 318// Records a single END event for "name" immediately. If the category 319// is not enabled, then this does nothing. 320// - category and name strings must have application lifetime (statics or 321// literals). They may not include " chars. 322#define TRACE_EVENT_END0(category_group, name) \ 323 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \ 324 TRACE_EVENT_FLAG_NONE) 325#define TRACE_EVENT_END1(category_group, name, arg1_name, arg1_val) \ 326 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \ 327 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 328#define TRACE_EVENT_END2(category_group, name, arg1_name, arg1_val, arg2_name, \ 329 arg2_val) \ 330 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \ 331 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, \ 332 arg2_name, arg2_val) 333#define TRACE_EVENT_COPY_END0(category_group, name) \ 334 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \ 335 TRACE_EVENT_FLAG_COPY) 336#define TRACE_EVENT_COPY_END1(category_group, name, arg1_name, arg1_val) \ 337 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \ 338 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 339#define TRACE_EVENT_COPY_END2(category_group, name, arg1_name, arg1_val, \ 340 arg2_name, arg2_val) \ 341 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_END, category_group, name, \ 342 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \ 343 arg2_name, arg2_val) 344 345#define TRACE_EVENT_MARK_WITH_TIMESTAMP0(category_group, name, timestamp) \ 346 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 347 TRACE_EVENT_PHASE_MARK, category_group, name, timestamp, \ 348 TRACE_EVENT_FLAG_NONE) 349 350#define TRACE_EVENT_MARK_WITH_TIMESTAMP1(category_group, name, timestamp, \ 351 arg1_name, arg1_val) \ 352 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 353 TRACE_EVENT_PHASE_MARK, category_group, name, timestamp, \ 354 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 355 356#define TRACE_EVENT_COPY_MARK(category_group, name) \ 357 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_MARK, category_group, name, \ 358 TRACE_EVENT_FLAG_COPY) 359 360#define TRACE_EVENT_COPY_MARK_WITH_TIMESTAMP(category_group, name, timestamp) \ 361 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 362 TRACE_EVENT_PHASE_MARK, category_group, name, timestamp, \ 363 TRACE_EVENT_FLAG_COPY) 364 365// Similar to TRACE_EVENT_ENDx but with a custom |at| timestamp provided. 366// - |id| is used to match the _BEGIN event with the _END event. 367// Events are considered to match if their category_group, name and id values 368// all match. |id| must either be a pointer or an integer value up to 64 bits. 369// If it's a pointer, the bits will be xored with a hash of the process ID so 370// that the same pointer on two different processes will not collide. 371#define TRACE_EVENT_END_WITH_ID_TID_AND_TIMESTAMP0(category_group, name, id, \ 372 thread_id, timestamp) \ 373 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 374 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \ 375 timestamp, TRACE_EVENT_FLAG_NONE) 376#define TRACE_EVENT_COPY_END_WITH_ID_TID_AND_TIMESTAMP0( \ 377 category_group, name, id, thread_id, timestamp) \ 378 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 379 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \ 380 timestamp, TRACE_EVENT_FLAG_COPY) 381#define TRACE_EVENT_COPY_END_WITH_ID_TID_AND_TIMESTAMP1( \ 382 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val) \ 383 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 384 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \ 385 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 386#define TRACE_EVENT_COPY_END_WITH_ID_TID_AND_TIMESTAMP2( \ 387 category_group, name, id, thread_id, timestamp, arg1_name, arg1_val, \ 388 arg2_name, arg2_val) \ 389 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 390 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, thread_id, \ 391 timestamp, TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, \ 392 arg2_val) 393 394// Records the value of a counter called "name" immediately. Value 395// must be representable as a 32 bit integer. 396// - category and name strings must have application lifetime (statics or 397// literals). They may not include " chars. 398#define TRACE_COUNTER1(category_group, name, value) \ 399 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \ 400 TRACE_EVENT_FLAG_NONE, "value", \ 401 static_cast<int>(value)) 402#define TRACE_COPY_COUNTER1(category_group, name, value) \ 403 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \ 404 TRACE_EVENT_FLAG_COPY, "value", \ 405 static_cast<int>(value)) 406 407// Records the values of a multi-parted counter called "name" immediately. 408// The UI will treat value1 and value2 as parts of a whole, displaying their 409// values as a stacked-bar chart. 410// - category and name strings must have application lifetime (statics or 411// literals). They may not include " chars. 412#define TRACE_COUNTER2(category_group, name, value1_name, value1_val, \ 413 value2_name, value2_val) \ 414 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \ 415 TRACE_EVENT_FLAG_NONE, value1_name, \ 416 static_cast<int>(value1_val), value2_name, \ 417 static_cast<int>(value2_val)) 418#define TRACE_COPY_COUNTER2(category_group, name, value1_name, value1_val, \ 419 value2_name, value2_val) \ 420 INTERNAL_TRACE_EVENT_ADD(TRACE_EVENT_PHASE_COUNTER, category_group, name, \ 421 TRACE_EVENT_FLAG_COPY, value1_name, \ 422 static_cast<int>(value1_val), value2_name, \ 423 static_cast<int>(value2_val)) 424 425// Similar to TRACE_COUNTERx, but with a custom |timestamp| provided. 426#define TRACE_COUNTER_WITH_TIMESTAMP1(category_group, name, timestamp, value) \ 427 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 428 TRACE_EVENT_PHASE_COUNTER, category_group, name, timestamp, \ 429 TRACE_EVENT_FLAG_NONE, "value", static_cast<int>(value)) 430 431#define TRACE_COUNTER_WITH_TIMESTAMP2(category_group, name, timestamp, \ 432 value1_name, value1_val, value2_name, \ 433 value2_val) \ 434 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 435 TRACE_EVENT_PHASE_COUNTER, category_group, name, timestamp, \ 436 TRACE_EVENT_FLAG_NONE, value1_name, static_cast<int>(value1_val), \ 437 value2_name, static_cast<int>(value2_val)) 438 439// Records the value of a counter called "name" immediately. Value 440// must be representable as a 32 bit integer. 441// - category and name strings must have application lifetime (statics or 442// literals). They may not include " chars. 443// - |id| is used to disambiguate counters with the same name. It must either 444// be a pointer or an integer value up to 64 bits. If it's a pointer, the bits 445// will be xored with a hash of the process ID so that the same pointer on 446// two different processes will not collide. 447#define TRACE_COUNTER_ID1(category_group, name, id, value) \ 448 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \ 449 name, id, TRACE_EVENT_FLAG_NONE, "value", \ 450 static_cast<int>(value)) 451#define TRACE_COPY_COUNTER_ID1(category_group, name, id, value) \ 452 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \ 453 name, id, TRACE_EVENT_FLAG_COPY, "value", \ 454 static_cast<int>(value)) 455 456// Records the values of a multi-parted counter called "name" immediately. 457// The UI will treat value1 and value2 as parts of a whole, displaying their 458// values as a stacked-bar chart. 459// - category and name strings must have application lifetime (statics or 460// literals). They may not include " chars. 461// - |id| is used to disambiguate counters with the same name. It must either 462// be a pointer or an integer value up to 64 bits. If it's a pointer, the bits 463// will be xored with a hash of the process ID so that the same pointer on 464// two different processes will not collide. 465#define TRACE_COUNTER_ID2(category_group, name, id, value1_name, value1_val, \ 466 value2_name, value2_val) \ 467 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \ 468 name, id, TRACE_EVENT_FLAG_NONE, \ 469 value1_name, static_cast<int>(value1_val), \ 470 value2_name, static_cast<int>(value2_val)) 471#define TRACE_COPY_COUNTER_ID2(category_group, name, id, value1_name, \ 472 value1_val, value2_name, value2_val) \ 473 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_COUNTER, category_group, \ 474 name, id, TRACE_EVENT_FLAG_COPY, \ 475 value1_name, static_cast<int>(value1_val), \ 476 value2_name, static_cast<int>(value2_val)) 477 478// TRACE_EVENT_SAMPLE_* events are injected by the sampling profiler. 479#define TRACE_EVENT_SAMPLE_WITH_TID_AND_TIMESTAMP0(category_group, name, \ 480 thread_id, timestamp) \ 481 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 482 TRACE_EVENT_PHASE_SAMPLE, category_group, name, 0, thread_id, timestamp, \ 483 TRACE_EVENT_FLAG_NONE) 484 485#define TRACE_EVENT_SAMPLE_WITH_TID_AND_TIMESTAMP1( \ 486 category_group, name, thread_id, timestamp, arg1_name, arg1_val) \ 487 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 488 TRACE_EVENT_PHASE_SAMPLE, category_group, name, 0, thread_id, timestamp, \ 489 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 490 491#define TRACE_EVENT_SAMPLE_WITH_TID_AND_TIMESTAMP2(category_group, name, \ 492 thread_id, timestamp, \ 493 arg1_name, arg1_val, \ 494 arg2_name, arg2_val) \ 495 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 496 TRACE_EVENT_PHASE_SAMPLE, category_group, name, 0, thread_id, timestamp, \ 497 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 498 499#define TRACE_EVENT_SAMPLE_WITH_ID1(category_group, name, id, arg1_name, \ 500 arg1_val) \ 501 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_SAMPLE, category_group, \ 502 name, id, TRACE_EVENT_FLAG_NONE, arg1_name, \ 503 arg1_val) 504 505// ASYNC_STEP_* APIs should be only used by legacy code. New code should 506// consider using NESTABLE_ASYNC_* APIs to describe substeps within an async 507// event. 508// Records a single ASYNC_BEGIN event called "name" immediately, with 0, 1 or 2 509// associated arguments. If the category is not enabled, then this 510// does nothing. 511// - category and name strings must have application lifetime (statics or 512// literals). They may not include " chars. 513// - |id| is used to match the ASYNC_BEGIN event with the ASYNC_END event. ASYNC 514// events are considered to match if their category_group, name and id values 515// all match. |id| must either be a pointer or an integer value up to 64 bits. 516// If it's a pointer, the bits will be xored with a hash of the process ID so 517// that the same pointer on two different processes will not collide. 518// 519// An asynchronous operation can consist of multiple phases. The first phase is 520// defined by the ASYNC_BEGIN calls. Additional phases can be defined using the 521// ASYNC_STEP_INTO or ASYNC_STEP_PAST macros. The ASYNC_STEP_INTO macro will 522// annotate the block following the call. The ASYNC_STEP_PAST macro will 523// annotate the block prior to the call. Note that any particular event must use 524// only STEP_INTO or STEP_PAST macros; they can not mix and match. When the 525// operation completes, call ASYNC_END. 526// 527// An ASYNC trace typically occurs on a single thread (if not, they will only be 528// drawn on the thread defined in the ASYNC_BEGIN event), but all events in that 529// operation must use the same |name| and |id|. Each step can have its own 530// args. 531#define TRACE_EVENT_ASYNC_BEGIN0(category_group, name, id) \ 532 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \ 533 category_group, name, id, \ 534 TRACE_EVENT_FLAG_NONE) 535#define TRACE_EVENT_ASYNC_BEGIN1(category_group, name, id, arg1_name, \ 536 arg1_val) \ 537 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \ 538 category_group, name, id, \ 539 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 540#define TRACE_EVENT_ASYNC_BEGIN2(category_group, name, id, arg1_name, \ 541 arg1_val, arg2_name, arg2_val) \ 542 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 543 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \ 544 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 545#define TRACE_EVENT_COPY_ASYNC_BEGIN0(category_group, name, id) \ 546 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \ 547 category_group, name, id, \ 548 TRACE_EVENT_FLAG_COPY) 549#define TRACE_EVENT_COPY_ASYNC_BEGIN1(category_group, name, id, arg1_name, \ 550 arg1_val) \ 551 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_BEGIN, \ 552 category_group, name, id, \ 553 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 554#define TRACE_EVENT_COPY_ASYNC_BEGIN2(category_group, name, id, arg1_name, \ 555 arg1_val, arg2_name, arg2_val) \ 556 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 557 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \ 558 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, arg2_val) 559 560// Similar to TRACE_EVENT_ASYNC_BEGINx but with a custom |at| timestamp 561// provided. 562#define TRACE_EVENT_ASYNC_BEGIN_WITH_TIMESTAMP0(category_group, name, id, \ 563 timestamp) \ 564 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 565 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \ 566 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE) 567#define TRACE_EVENT_ASYNC_BEGIN_WITH_TIMESTAMP1( \ 568 category_group, name, id, timestamp, arg1_name, arg1_val) \ 569 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 570 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \ 571 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \ 572 arg1_name, arg1_val) 573#define TRACE_EVENT_ASYNC_BEGIN_WITH_TIMESTAMP2(category_group, name, id, \ 574 timestamp, arg1_name, \ 575 arg1_val, arg2_name, arg2_val) \ 576 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 577 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \ 578 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \ 579 arg1_name, arg1_val, arg2_name, arg2_val) 580#define TRACE_EVENT_COPY_ASYNC_BEGIN_WITH_TIMESTAMP0(category_group, name, id, \ 581 timestamp) \ 582 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 583 TRACE_EVENT_PHASE_ASYNC_BEGIN, category_group, name, id, \ 584 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_COPY) 585 586// Records a single ASYNC_STEP_INTO event for |step| immediately. If the 587// category is not enabled, then this does nothing. The |name| and |id| must 588// match the ASYNC_BEGIN event above. The |step| param identifies this step 589// within the async event. This should be called at the beginning of the next 590// phase of an asynchronous operation. The ASYNC_BEGIN event must not have any 591// ASYNC_STEP_PAST events. 592#define TRACE_EVENT_ASYNC_STEP_INTO0(category_group, name, id, step) \ 593 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_STEP_INTO, \ 594 category_group, name, id, \ 595 TRACE_EVENT_FLAG_NONE, "step", step) 596#define TRACE_EVENT_ASYNC_STEP_INTO1(category_group, name, id, step, \ 597 arg1_name, arg1_val) \ 598 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 599 TRACE_EVENT_PHASE_ASYNC_STEP_INTO, category_group, name, id, \ 600 TRACE_EVENT_FLAG_NONE, "step", step, arg1_name, arg1_val) 601 602// Similar to TRACE_EVENT_ASYNC_STEP_INTOx but with a custom |at| timestamp 603// provided. 604#define TRACE_EVENT_ASYNC_STEP_INTO_WITH_TIMESTAMP0(category_group, name, id, \ 605 step, timestamp) \ 606 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 607 TRACE_EVENT_PHASE_ASYNC_STEP_INTO, category_group, name, id, \ 608 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \ 609 "step", step) 610 611// Records a single ASYNC_STEP_PAST event for |step| immediately. If the 612// category is not enabled, then this does nothing. The |name| and |id| must 613// match the ASYNC_BEGIN event above. The |step| param identifies this step 614// within the async event. This should be called at the beginning of the next 615// phase of an asynchronous operation. The ASYNC_BEGIN event must not have any 616// ASYNC_STEP_INTO events. 617#define TRACE_EVENT_ASYNC_STEP_PAST0(category_group, name, id, step) \ 618 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_STEP_PAST, \ 619 category_group, name, id, \ 620 TRACE_EVENT_FLAG_NONE, "step", step) 621#define TRACE_EVENT_ASYNC_STEP_PAST1(category_group, name, id, step, \ 622 arg1_name, arg1_val) \ 623 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 624 TRACE_EVENT_PHASE_ASYNC_STEP_PAST, category_group, name, id, \ 625 TRACE_EVENT_FLAG_NONE, "step", step, arg1_name, arg1_val) 626 627// Records a single ASYNC_END event for "name" immediately. If the category 628// is not enabled, then this does nothing. 629#define TRACE_EVENT_ASYNC_END0(category_group, name, id) \ 630 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \ 631 category_group, name, id, \ 632 TRACE_EVENT_FLAG_NONE) 633#define TRACE_EVENT_ASYNC_END1(category_group, name, id, arg1_name, arg1_val) \ 634 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \ 635 category_group, name, id, \ 636 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 637#define TRACE_EVENT_ASYNC_END2(category_group, name, id, arg1_name, arg1_val, \ 638 arg2_name, arg2_val) \ 639 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 640 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \ 641 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 642#define TRACE_EVENT_COPY_ASYNC_END0(category_group, name, id) \ 643 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \ 644 category_group, name, id, \ 645 TRACE_EVENT_FLAG_COPY) 646#define TRACE_EVENT_COPY_ASYNC_END1(category_group, name, id, arg1_name, \ 647 arg1_val) \ 648 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_ASYNC_END, \ 649 category_group, name, id, \ 650 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 651#define TRACE_EVENT_COPY_ASYNC_END2(category_group, name, id, arg1_name, \ 652 arg1_val, arg2_name, arg2_val) \ 653 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 654 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \ 655 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, arg2_val) 656 657// Similar to TRACE_EVENT_ASYNC_ENDx but with a custom |at| timestamp provided. 658#define TRACE_EVENT_ASYNC_END_WITH_TIMESTAMP0(category_group, name, id, \ 659 timestamp) \ 660 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 661 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \ 662 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE) 663#define TRACE_EVENT_ASYNC_END_WITH_TIMESTAMP1(category_group, name, id, \ 664 timestamp, arg1_name, arg1_val) \ 665 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 666 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \ 667 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \ 668 arg1_name, arg1_val) 669#define TRACE_EVENT_ASYNC_END_WITH_TIMESTAMP2(category_group, name, id, \ 670 timestamp, arg1_name, arg1_val, \ 671 arg2_name, arg2_val) \ 672 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 673 TRACE_EVENT_PHASE_ASYNC_END, category_group, name, id, \ 674 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \ 675 arg1_name, arg1_val, arg2_name, arg2_val) 676 677// NESTABLE_ASYNC_* APIs are used to describe an async operation, which can 678// be nested within a NESTABLE_ASYNC event and/or have inner NESTABLE_ASYNC 679// events. 680// - category and name strings must have application lifetime (statics or 681// literals). They may not include " chars. 682// - A pair of NESTABLE_ASYNC_BEGIN event and NESTABLE_ASYNC_END event is 683// considered as a match if their category_group, name and id all match. 684// - |id| must either be a pointer or an integer value up to 64 bits. 685// If it's a pointer, the bits will be xored with a hash of the process ID so 686// that the same pointer on two different processes will not collide. 687// - |id| is used to match a child NESTABLE_ASYNC event with its parent 688// NESTABLE_ASYNC event. Therefore, events in the same nested event tree must 689// be logged using the same id and category_group. 690// 691// Unmatched NESTABLE_ASYNC_END event will be parsed as an event that starts 692// at the first NESTABLE_ASYNC event of that id, and unmatched 693// NESTABLE_ASYNC_BEGIN event will be parsed as an event that ends at the last 694// NESTABLE_ASYNC event of that id. Corresponding warning messages for 695// unmatched events will be shown in the analysis view. 696 697// Records a single NESTABLE_ASYNC_BEGIN event called "name" immediately, with 698// 0, 1 or 2 associated arguments. If the category is not enabled, then this 699// does nothing. 700#define TRACE_EVENT_NESTABLE_ASYNC_BEGIN0(category_group, name, id) \ 701 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, \ 702 category_group, name, id, \ 703 TRACE_EVENT_FLAG_NONE) 704#define TRACE_EVENT_NESTABLE_ASYNC_BEGIN1(category_group, name, id, arg1_name, \ 705 arg1_val) \ 706 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, \ 707 category_group, name, id, \ 708 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 709#define TRACE_EVENT_NESTABLE_ASYNC_BEGIN2(category_group, name, id, arg1_name, \ 710 arg1_val, arg2_name, arg2_val) \ 711 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 712 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \ 713 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 714// Records a single NESTABLE_ASYNC_END event called "name" immediately, with 0 715// or 2 associated arguments. If the category is not enabled, then this does 716// nothing. 717#define TRACE_EVENT_NESTABLE_ASYNC_END0(category_group, name, id) \ 718 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, \ 719 category_group, name, id, \ 720 TRACE_EVENT_FLAG_NONE) 721// Records a single NESTABLE_ASYNC_END event called "name" immediately, with 1 722// associated argument. If the category is not enabled, then this does nothing. 723#define TRACE_EVENT_NESTABLE_ASYNC_END1(category_group, name, id, arg1_name, \ 724 arg1_val) \ 725 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, \ 726 category_group, name, id, \ 727 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 728#define TRACE_EVENT_NESTABLE_ASYNC_END2(category_group, name, id, arg1_name, \ 729 arg1_val, arg2_name, arg2_val) \ 730 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 731 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \ 732 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 733 734// Records a single NESTABLE_ASYNC_INSTANT event called "name" immediately, 735// with none, one or two associated argument. If the category is not enabled, 736// then this does nothing. 737#define TRACE_EVENT_NESTABLE_ASYNC_INSTANT0(category_group, name, id) \ 738 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT, \ 739 category_group, name, id, \ 740 TRACE_EVENT_FLAG_NONE) 741 742#define TRACE_EVENT_NESTABLE_ASYNC_INSTANT1(category_group, name, id, \ 743 arg1_name, arg1_val) \ 744 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT, \ 745 category_group, name, id, \ 746 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 747 748#define TRACE_EVENT_NESTABLE_ASYNC_INSTANT2( \ 749 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \ 750 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 751 TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT, category_group, name, id, \ 752 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 753 754#define TRACE_EVENT_COPY_NESTABLE_ASYNC_BEGIN_WITH_TTS2( \ 755 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \ 756 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 757 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \ 758 TRACE_EVENT_FLAG_ASYNC_TTS | TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \ 759 arg2_name, arg2_val) 760#define TRACE_EVENT_COPY_NESTABLE_ASYNC_END_WITH_TTS2( \ 761 category_group, name, id, arg1_name, arg1_val, arg2_name, arg2_val) \ 762 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 763 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \ 764 TRACE_EVENT_FLAG_ASYNC_TTS | TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, \ 765 arg2_name, arg2_val) 766 767// Similar to TRACE_EVENT_NESTABLE_ASYNC_{BEGIN,END}x but with a custom 768// |timestamp| provided. 769#define TRACE_EVENT_NESTABLE_ASYNC_BEGIN_WITH_TIMESTAMP0(category_group, name, \ 770 id, timestamp) \ 771 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 772 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \ 773 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE) 774 775#define TRACE_EVENT_NESTABLE_ASYNC_END_WITH_TIMESTAMP0(category_group, name, \ 776 id, timestamp) \ 777 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 778 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \ 779 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE) 780 781#define TRACE_EVENT_COPY_NESTABLE_ASYNC_BEGIN_WITH_TIMESTAMP0( \ 782 category_group, name, id, timestamp) \ 783 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 784 TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN, category_group, name, id, \ 785 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_COPY) 786#define TRACE_EVENT_COPY_NESTABLE_ASYNC_END_WITH_TIMESTAMP0( \ 787 category_group, name, id, timestamp) \ 788 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 789 TRACE_EVENT_PHASE_NESTABLE_ASYNC_END, category_group, name, id, \ 790 TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_COPY) 791 792// Records a single FLOW_BEGIN event called "name" immediately, with 0, 1 or 2 793// associated arguments. If the category is not enabled, then this 794// does nothing. 795// - category and name strings must have application lifetime (statics or 796// literals). They may not include " chars. 797// - |id| is used to match the FLOW_BEGIN event with the FLOW_END event. FLOW 798// events are considered to match if their category_group, name and id values 799// all match. |id| must either be a pointer or an integer value up to 64 bits. 800// If it's a pointer, the bits will be xored with a hash of the process ID so 801// that the same pointer on two different processes will not collide. 802// FLOW events are different from ASYNC events in how they are drawn by the 803// tracing UI. A FLOW defines asynchronous data flow, such as posting a task 804// (FLOW_BEGIN) and later executing that task (FLOW_END). Expect FLOWs to be 805// drawn as lines or arrows from FLOW_BEGIN scopes to FLOW_END scopes. Similar 806// to ASYNC, a FLOW can consist of multiple phases. The first phase is defined 807// by the FLOW_BEGIN calls. Additional phases can be defined using the FLOW_STEP 808// macros. When the operation completes, call FLOW_END. An async operation can 809// span threads and processes, but all events in that operation must use the 810// same |name| and |id|. Each event can have its own args. 811#define TRACE_EVENT_FLOW_BEGIN0(category_group, name, id) \ 812 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \ 813 category_group, name, id, \ 814 TRACE_EVENT_FLAG_NONE) 815#define TRACE_EVENT_FLOW_BEGIN1(category_group, name, id, arg1_name, arg1_val) \ 816 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \ 817 category_group, name, id, \ 818 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val) 819#define TRACE_EVENT_FLOW_BEGIN2(category_group, name, id, arg1_name, arg1_val, \ 820 arg2_name, arg2_val) \ 821 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 822 TRACE_EVENT_PHASE_FLOW_BEGIN, category_group, name, id, \ 823 TRACE_EVENT_FLAG_NONE, arg1_name, arg1_val, arg2_name, arg2_val) 824#define TRACE_EVENT_COPY_FLOW_BEGIN0(category_group, name, id) \ 825 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \ 826 category_group, name, id, \ 827 TRACE_EVENT_FLAG_COPY) 828#define TRACE_EVENT_COPY_FLOW_BEGIN1(category_group, name, id, arg1_name, \ 829 arg1_val) \ 830 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_BEGIN, \ 831 category_group, name, id, \ 832 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val) 833#define TRACE_EVENT_COPY_FLOW_BEGIN2(category_group, name, id, arg1_name, \ 834 arg1_val, arg2_name, arg2_val) \ 835 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 836 TRACE_EVENT_PHASE_FLOW_BEGIN, category_group, name, id, \ 837 TRACE_EVENT_FLAG_COPY, arg1_name, arg1_val, arg2_name, arg2_val) 838 839// Records a single FLOW_STEP event for |step| immediately. If the category 840// is not enabled, then this does nothing. The |name| and |id| must match the 841// FLOW_BEGIN event above. The |step| param identifies this step within the 842// async event. This should be called at the beginning of the next phase of an 843// asynchronous operation. 844#define TRACE_EVENT_FLOW_STEP0(category_group, name, id, step) \ 845 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_STEP, \ 846 category_group, name, id, \ 847 TRACE_EVENT_FLAG_NONE, "step", step) 848#define TRACE_EVENT_FLOW_STEP1(category_group, name, id, step, arg1_name, \ 849 arg1_val) \ 850 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 851 TRACE_EVENT_PHASE_FLOW_STEP, category_group, name, id, \ 852 TRACE_EVENT_FLAG_NONE, "step", step, arg1_name, arg1_val) 853#define TRACE_EVENT_COPY_FLOW_STEP0(category_group, name, id, step) \ 854 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_STEP, \ 855 category_group, name, id, \ 856 TRACE_EVENT_FLAG_COPY, "step", step) 857#define TRACE_EVENT_COPY_FLOW_STEP1(category_group, name, id, step, arg1_name, \ 858 arg1_val) \ 859 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 860 TRACE_EVENT_PHASE_FLOW_STEP, category_group, name, id, \ 861 TRACE_EVENT_FLAG_COPY, "step", step, arg1_name, arg1_val) 862 863// Records a single FLOW_END event for "name" immediately. If the category 864// is not enabled, then this does nothing. 865#define TRACE_EVENT_FLOW_END0(category_group, name, id) \ 866 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 867 name, id, TRACE_EVENT_FLAG_NONE) 868#define TRACE_EVENT_FLOW_END_BIND_TO_ENCLOSING0(category_group, name, id) \ 869 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 870 name, id, \ 871 TRACE_EVENT_FLAG_BIND_TO_ENCLOSING) 872#define TRACE_EVENT_FLOW_END1(category_group, name, id, arg1_name, arg1_val) \ 873 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 874 name, id, TRACE_EVENT_FLAG_NONE, arg1_name, \ 875 arg1_val) 876#define TRACE_EVENT_FLOW_END2(category_group, name, id, arg1_name, arg1_val, \ 877 arg2_name, arg2_val) \ 878 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 879 name, id, TRACE_EVENT_FLAG_NONE, arg1_name, \ 880 arg1_val, arg2_name, arg2_val) 881#define TRACE_EVENT_COPY_FLOW_END0(category_group, name, id) \ 882 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 883 name, id, TRACE_EVENT_FLAG_COPY) 884#define TRACE_EVENT_COPY_FLOW_END1(category_group, name, id, arg1_name, \ 885 arg1_val) \ 886 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 887 name, id, TRACE_EVENT_FLAG_COPY, arg1_name, \ 888 arg1_val) 889#define TRACE_EVENT_COPY_FLOW_END2(category_group, name, id, arg1_name, \ 890 arg1_val, arg2_name, arg2_val) \ 891 INTERNAL_TRACE_EVENT_ADD_WITH_ID(TRACE_EVENT_PHASE_FLOW_END, category_group, \ 892 name, id, TRACE_EVENT_FLAG_COPY, arg1_name, \ 893 arg1_val, arg2_name, arg2_val) 894 895// Special trace event macro to trace task execution with the location where it 896// was posted from. 897#define TRACE_TASK_EXECUTION(run_function, task) \ 898 INTERNAL_TRACE_TASK_EXECUTION(run_function, task) 899 900// TRACE_EVENT_METADATA* events are information related to other 901// injected events, not events in their own right. 902#define TRACE_EVENT_METADATA1(category_group, name, arg1_name, arg1_val) \ 903 INTERNAL_TRACE_EVENT_METADATA_ADD(category_group, name, arg1_name, arg1_val) 904 905// Records a clock sync event. 906#define TRACE_EVENT_CLOCK_SYNC_RECEIVER(sync_id) \ 907 INTERNAL_TRACE_EVENT_ADD( \ 908 TRACE_EVENT_PHASE_CLOCK_SYNC, "__metadata", "clock_sync", \ 909 TRACE_EVENT_FLAG_NONE, "sync_id", sync_id) 910#define TRACE_EVENT_CLOCK_SYNC_ISSUER(sync_id, issue_ts, issue_end_ts) \ 911 INTERNAL_TRACE_EVENT_ADD_WITH_TIMESTAMP( \ 912 TRACE_EVENT_PHASE_CLOCK_SYNC, "__metadata", "clock_sync", \ 913 issue_end_ts, TRACE_EVENT_FLAG_NONE, \ 914 "sync_id", sync_id, "issue_ts", issue_ts) 915 916// Macros to track the life time and value of arbitrary client objects. 917// See also TraceTrackableObject. 918#define TRACE_EVENT_OBJECT_CREATED_WITH_ID(category_group, name, id) \ 919 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 920 TRACE_EVENT_PHASE_CREATE_OBJECT, category_group, name, id, \ 921 TRACE_EVENT_FLAG_NONE) 922 923#define TRACE_EVENT_OBJECT_SNAPSHOT_WITH_ID(category_group, name, id, \ 924 snapshot) \ 925 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 926 TRACE_EVENT_PHASE_SNAPSHOT_OBJECT, category_group, name, \ 927 id, TRACE_EVENT_FLAG_NONE, "snapshot", snapshot) 928 929#define TRACE_EVENT_OBJECT_SNAPSHOT_WITH_ID_AND_TIMESTAMP( \ 930 category_group, name, id, timestamp, snapshot) \ 931 INTERNAL_TRACE_EVENT_ADD_WITH_ID_TID_AND_TIMESTAMP( \ 932 TRACE_EVENT_PHASE_SNAPSHOT_OBJECT, category_group, name, \ 933 id, TRACE_EVENT_API_CURRENT_THREAD_ID, timestamp, TRACE_EVENT_FLAG_NONE, \ 934 "snapshot", snapshot) 935 936#define TRACE_EVENT_OBJECT_DELETED_WITH_ID(category_group, name, id) \ 937 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 938 TRACE_EVENT_PHASE_DELETE_OBJECT, category_group, name, id, \ 939 TRACE_EVENT_FLAG_NONE) 940 941// Records entering and leaving trace event contexts. |category_group| and 942// |name| specify the context category and type. |context| is a 943// snapshotted context object id. 944#define TRACE_EVENT_ENTER_CONTEXT(category_group, name, context) \ 945 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 946 TRACE_EVENT_PHASE_ENTER_CONTEXT, category_group, name, context, \ 947 TRACE_EVENT_FLAG_NONE) 948#define TRACE_EVENT_LEAVE_CONTEXT(category_group, name, context) \ 949 INTERNAL_TRACE_EVENT_ADD_WITH_ID( \ 950 TRACE_EVENT_PHASE_LEAVE_CONTEXT, category_group, name, context, \ 951 TRACE_EVENT_FLAG_NONE) 952#define TRACE_EVENT_SCOPED_CONTEXT(category_group, name, context) \ 953 INTERNAL_TRACE_EVENT_SCOPED_CONTEXT(category_group, name, context) 954 955// Macro to specify that two trace IDs are identical. For example, 956// TRACE_LINK_IDS( 957// "category", "name", 958// TRACE_ID_WITH_SCOPE("net::URLRequest", 0x1000), 959// TRACE_ID_WITH_SCOPE("blink::ResourceFetcher::FetchRequest", 0x2000)) 960// tells the trace consumer that events with ID ("net::URLRequest", 0x1000) from 961// the current process have the same ID as events with ID 962// ("blink::ResourceFetcher::FetchRequest", 0x2000). 963#define TRACE_LINK_IDS(category_group, name, id, linked_id) \ 964 INTERNAL_TRACE_EVENT_ADD_LINK_IDS(category_group, name, id, linked_id); 965 966// Macro to efficiently determine if a given category group is enabled. 967#define TRACE_EVENT_CATEGORY_GROUP_ENABLED(category_group, ret) \ 968 do { \ 969 INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category_group); \ 970 if (INTERNAL_TRACE_EVENT_CATEGORY_GROUP_ENABLED_FOR_RECORDING_MODE()) { \ 971 *ret = true; \ 972 } else { \ 973 *ret = false; \ 974 } \ 975 } while (0) 976 977// Macro to explicitly warm up a given category group. This could be useful in 978// cases where we want to initialize a category group before any trace events 979// for that category group is reported. For example, to have a category group 980// always show up in the "record categories" list for manually selecting 981// settings in about://tracing. 982#define TRACE_EVENT_WARMUP_CATEGORY(category_group) \ 983 INTERNAL_TRACE_EVENT_GET_CATEGORY_INFO(category_group) 984 985// Macro to efficiently determine, through polling, if a new trace has begun. 986#define TRACE_EVENT_IS_NEW_TRACE(ret) \ 987 do { \ 988 static int INTERNAL_TRACE_EVENT_UID(lastRecordingNumber) = 0; \ 989 int num_traces_recorded = TRACE_EVENT_API_GET_NUM_TRACES_RECORDED(); \ 990 if (num_traces_recorded != -1 && \ 991 num_traces_recorded != \ 992 INTERNAL_TRACE_EVENT_UID(lastRecordingNumber)) { \ 993 INTERNAL_TRACE_EVENT_UID(lastRecordingNumber) = num_traces_recorded; \ 994 *ret = true; \ 995 } else { \ 996 *ret = false; \ 997 } \ 998 } while (0) 999 1000// Notes regarding the following definitions: 1001// New values can be added and propagated to third party libraries, but existing 1002// definitions must never be changed, because third party libraries may use old 1003// definitions. 1004 1005// Phase indicates the nature of an event entry. E.g. part of a begin/end pair. 1006#define TRACE_EVENT_PHASE_BEGIN ('B') 1007#define TRACE_EVENT_PHASE_END ('E') 1008#define TRACE_EVENT_PHASE_COMPLETE ('X') 1009#define TRACE_EVENT_PHASE_INSTANT ('I') 1010#define TRACE_EVENT_PHASE_ASYNC_BEGIN ('S') 1011#define TRACE_EVENT_PHASE_ASYNC_STEP_INTO ('T') 1012#define TRACE_EVENT_PHASE_ASYNC_STEP_PAST ('p') 1013#define TRACE_EVENT_PHASE_ASYNC_END ('F') 1014#define TRACE_EVENT_PHASE_NESTABLE_ASYNC_BEGIN ('b') 1015#define TRACE_EVENT_PHASE_NESTABLE_ASYNC_END ('e') 1016#define TRACE_EVENT_PHASE_NESTABLE_ASYNC_INSTANT ('n') 1017#define TRACE_EVENT_PHASE_FLOW_BEGIN ('s') 1018#define TRACE_EVENT_PHASE_FLOW_STEP ('t') 1019#define TRACE_EVENT_PHASE_FLOW_END ('f') 1020#define TRACE_EVENT_PHASE_METADATA ('M') 1021#define TRACE_EVENT_PHASE_COUNTER ('C') 1022#define TRACE_EVENT_PHASE_SAMPLE ('P') 1023#define TRACE_EVENT_PHASE_CREATE_OBJECT ('N') 1024#define TRACE_EVENT_PHASE_SNAPSHOT_OBJECT ('O') 1025#define TRACE_EVENT_PHASE_DELETE_OBJECT ('D') 1026#define TRACE_EVENT_PHASE_MEMORY_DUMP ('v') 1027#define TRACE_EVENT_PHASE_MARK ('R') 1028#define TRACE_EVENT_PHASE_CLOCK_SYNC ('c') 1029#define TRACE_EVENT_PHASE_ENTER_CONTEXT ('(') 1030#define TRACE_EVENT_PHASE_LEAVE_CONTEXT (')') 1031#define TRACE_EVENT_PHASE_LINK_IDS ('=') 1032 1033// Flags for changing the behavior of TRACE_EVENT_API_ADD_TRACE_EVENT. 1034#define TRACE_EVENT_FLAG_NONE (static_cast<unsigned int>(0)) 1035#define TRACE_EVENT_FLAG_COPY (static_cast<unsigned int>(1 << 0)) 1036#define TRACE_EVENT_FLAG_HAS_ID (static_cast<unsigned int>(1 << 1)) 1037// TODO(crbug.com/639003): Free this bit after ID mangling is deprecated. 1038#define TRACE_EVENT_FLAG_MANGLE_ID (static_cast<unsigned int>(1 << 2)) 1039#define TRACE_EVENT_FLAG_SCOPE_OFFSET (static_cast<unsigned int>(1 << 3)) 1040#define TRACE_EVENT_FLAG_SCOPE_EXTRA (static_cast<unsigned int>(1 << 4)) 1041#define TRACE_EVENT_FLAG_EXPLICIT_TIMESTAMP (static_cast<unsigned int>(1 << 5)) 1042#define TRACE_EVENT_FLAG_ASYNC_TTS (static_cast<unsigned int>(1 << 6)) 1043#define TRACE_EVENT_FLAG_BIND_TO_ENCLOSING (static_cast<unsigned int>(1 << 7)) 1044#define TRACE_EVENT_FLAG_FLOW_IN (static_cast<unsigned int>(1 << 8)) 1045#define TRACE_EVENT_FLAG_FLOW_OUT (static_cast<unsigned int>(1 << 9)) 1046#define TRACE_EVENT_FLAG_HAS_CONTEXT_ID (static_cast<unsigned int>(1 << 10)) 1047#define TRACE_EVENT_FLAG_HAS_PROCESS_ID (static_cast<unsigned int>(1 << 11)) 1048#define TRACE_EVENT_FLAG_HAS_LOCAL_ID (static_cast<unsigned int>(1 << 12)) 1049#define TRACE_EVENT_FLAG_HAS_GLOBAL_ID (static_cast<unsigned int>(1 << 13)) 1050 1051#define TRACE_EVENT_FLAG_SCOPE_MASK \ 1052 (static_cast<unsigned int>(TRACE_EVENT_FLAG_SCOPE_OFFSET | \ 1053 TRACE_EVENT_FLAG_SCOPE_EXTRA)) 1054 1055// Type values for identifying types in the TraceValue union. 1056#define TRACE_VALUE_TYPE_BOOL (static_cast<unsigned char>(1)) 1057#define TRACE_VALUE_TYPE_UINT (static_cast<unsigned char>(2)) 1058#define TRACE_VALUE_TYPE_INT (static_cast<unsigned char>(3)) 1059#define TRACE_VALUE_TYPE_DOUBLE (static_cast<unsigned char>(4)) 1060#define TRACE_VALUE_TYPE_POINTER (static_cast<unsigned char>(5)) 1061#define TRACE_VALUE_TYPE_STRING (static_cast<unsigned char>(6)) 1062#define TRACE_VALUE_TYPE_COPY_STRING (static_cast<unsigned char>(7)) 1063#define TRACE_VALUE_TYPE_CONVERTABLE (static_cast<unsigned char>(8)) 1064 1065// Enum reflecting the scope of an INSTANT event. Must fit within 1066// TRACE_EVENT_FLAG_SCOPE_MASK. 1067#define TRACE_EVENT_SCOPE_GLOBAL (static_cast<unsigned char>(0 << 3)) 1068#define TRACE_EVENT_SCOPE_PROCESS (static_cast<unsigned char>(1 << 3)) 1069#define TRACE_EVENT_SCOPE_THREAD (static_cast<unsigned char>(2 << 3)) 1070 1071#define TRACE_EVENT_SCOPE_NAME_GLOBAL ('g') 1072#define TRACE_EVENT_SCOPE_NAME_PROCESS ('p') 1073#define TRACE_EVENT_SCOPE_NAME_THREAD ('t') 1074