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 // scoped_refptr<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_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) 231 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) 239 240 // UNSHIPPED_TRACE_EVENT* are like TRACE_EVENT* except that they are not 241 // included in official builds. 242 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 249 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 282 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) 311 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) 321 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) 349 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) 378 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) 405 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) 409 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) 414 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) 418 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) 423 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) 452 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)) 465 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)) 483 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)) 500 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)) 522 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) 529 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) 535 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) 543 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. 557 // 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. 565 // 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) 598 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) 611 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) 627 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) 636 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) 652 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) 682 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) 689 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. 703 // 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. 709 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) 746 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) 763 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) 776 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) 784 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) 790 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) 801 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) 810 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) 857 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) 881 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) 913 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) 920 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) 926 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) 933 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) 938 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; \ 947 } \ 948 } while (0) 949 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) 957 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; \ 970 } \ 971 } while (0) 972 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. 977 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') 1001 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)) 1015 1016 #define TRACE_EVENT_FLAG_SCOPE_MASK \ 1017 (static_cast<unsigned int>(TRACE_EVENT_FLAG_SCOPE_OFFSET | \ 1018 TRACE_EVENT_FLAG_SCOPE_EXTRA)) 1019 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)) 1029 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)) 1035 1036 #define TRACE_EVENT_SCOPE_NAME_GLOBAL ('g') 1037 #define TRACE_EVENT_SCOPE_NAME_PROCESS ('p') 1038 #define TRACE_EVENT_SCOPE_NAME_THREAD ('t') 1039
