1 // Copyright 2017 The Fuchsia 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 file contains definitions common to userspace and DDK tracing. 6 7 #ifndef TRACE_INTERNAL_EVENT_COMMON_H_ 8 #define TRACE_INTERNAL_EVENT_COMMON_H_ 9 10 #include <trace/event_args.h> 11 #include <trace/internal/event_internal.h> 12 13 // Returns true if tracing is enabled. 14 // 15 // Usage: 16 // 17 // if (TRACE_ENABLED()) { 18 // // do something possibly expensive only when tracing is enabled 19 // } 20 // 21 #ifndef NTRACE 22 #define TRACE_ENABLED() (trace_is_enabled()) 23 #else 24 #define TRACE_ENABLED() (false) 25 #endif // NTRACE 26 27 // Returns true if tracing of the specified category has been enabled (which 28 // implies that |TRACE_ENABLED()| is also true). 29 // 30 // |category_literal| must be a null-terminated static string constant. 31 // 32 // Usage: 33 // 34 // if (TRACE_CATEGORY_ENABLED("category")) { 35 // // do something possibly expensive only when tracing this category 36 // } 37 // 38 #ifndef NTRACE 39 #define TRACE_CATEGORY_ENABLED(category_literal) \ 40 (trace_is_category_enabled(category_literal)) 41 #else 42 #define TRACE_CATEGORY_ENABLED(category_literal) ((void)(category_literal), false) 43 #endif // NTRACE 44 45 // Returns a new unique 64-bit unsigned integer (within this process). 46 // Each invocation returns a different non-zero value. 47 // Useful for generating identifiers for async and flow events. 48 // 49 // Usage: 50 // 51 // trace_async_id_t async_id = TRACE_NONCE(); 52 // TRACE_ASYNC_BEGIN("category", "name", async_id); 53 // // a little while later... 54 // TRACE_ASYNC_END("category", "name", async_id); 55 // 56 #define TRACE_NONCE() (trace_generate_nonce()) 57 58 // Writes an instant event representing a single moment in time (a probe). 59 // 60 // 0 to 15 arguments can be associated with the event, each of which is used 61 // to annotate the moment with additional information. 62 // 63 // |category_literal| and |name_literal| must be null-terminated static string constants. 64 // |scope| is |TRACE_SCOPE_THREAD|, |TRACE_SCOPE_PROCESS|, or |TRACE_SCOPE_GLOBAL|. 65 // |args| is the list of argument key/value pairs. 66 // 67 // Usage: 68 // 69 // TRACE_INSTANT("category", "name", TRACE_SCOPE_PROCESS, "x", TA_INT32(42)); 70 // 71 #define TRACE_INSTANT(category_literal, name_literal, scope, args...) \ 72 TRACE_INTERNAL_INSTANT((category_literal), (name_literal), (scope), args) 73 74 // Writes a counter event with the specified id. 75 // 76 // The arguments to this event are numeric samples are typically represented by 77 // the visualizer as a stacked area chart. The id serves to distinguish multiple 78 // instances of counters which share the same category and name within the 79 // same process. 80 // 81 // 1 to 15 numeric arguments can be associated with the event, each of which is 82 // interpreted as a distinct time series. 83 // 84 // |category_literal| and |name_literal| must be null-terminated static string constants. 85 // |counter_id| is the correlation id of the counter. 86 // Must be unique for a given process, category, and name combination. 87 // |args| is the list of argument key/value pairs. 88 // 89 // Usage: 90 // 91 // trace_counter_id_t counter_id = 555; 92 // TRACE_COUNTER("category", "name", counter_id, "x", TA_INT32(42), "y", TA_DOUBLE(2.0)) 93 // 94 #define TRACE_COUNTER(category_literal, name_literal, counter_id, arg1, args...) \ 95 TRACE_INTERNAL_COUNTER((category_literal), (name_literal), (counter_id), arg1, ##args) 96 97 // Writes a duration event which ends when the current scope exits. 98 // 99 // Durations describe work which is happening synchronously on one thread. 100 // They can be nested to represent a control flow stack. 101 // 102 // 0 to 15 arguments can be associated with the event, each of which is used 103 // to annotate the duration with additional information. 104 // 105 // |category_literal| and |name_literal| must be null-terminated static string constants. 106 // |args| is the list of argument key/value pairs. 107 // 108 // Usage: 109 // 110 // void function(int arg) { 111 // TRACE_DURATION("category", "name", "arg", TA_INT32(arg)); 112 // // do something useful here 113 // } 114 // 115 #define TRACE_DURATION(category_literal, name_literal, args...) \ 116 TRACE_INTERNAL_DURATION((category_literal), (name_literal), args) 117 118 // Writes a duration begin event only. 119 // This event must be matched by a duration end event with the same category and name. 120 // 121 // Durations describe work which is happening synchronously on one thread. 122 // They can be nested to represent a control flow stack. 123 // 124 // 0 to 15 arguments can be associated with the event, each of which is used 125 // to annotate the duration with additional information. The arguments provided 126 // to matching duration begin and duration end events are combined together in 127 // the trace; it is not necessary to repeat them. 128 // 129 // |category_literal| and |name_literal| must be null-terminated static string constants. 130 // |args| is the list of argument key/value pairs. 131 // 132 // Usage: 133 // 134 // TRACE_DURATION_BEGIN("category", "name", "x", TA_INT32(42)); 135 // 136 #define TRACE_DURATION_BEGIN(category_literal, name_literal, args...) \ 137 TRACE_INTERNAL_DURATION_BEGIN((category_literal), (name_literal), args) 138 139 // Writes a duration end event only. 140 // 141 // Durations describe work which is happening synchronously on one thread. 142 // They can be nested to represent a control flow stack. 143 // 144 // 0 to 15 arguments can be associated with the event, each of which is used 145 // to annotate the duration with additional information. The arguments provided 146 // to matching duration begin and duration end events are combined together in 147 // the trace; it is not necessary to repeat them. 148 // 149 // |category_literal| and |name_literal| must be null-terminated static string constants. 150 // |args| is the list of argument key/value pairs. 151 // 152 // Usage: 153 // 154 // TRACE_DURATION_END("category", "name", "x", TA_INT32(42)); 155 // 156 #define TRACE_DURATION_END(category_literal, name_literal, args...) \ 157 TRACE_INTERNAL_DURATION_END((category_literal), (name_literal), args) 158 159 // Writes an asynchronous begin event with the specified id. 160 // This event may be followed by async instant events and must be matched by 161 // an async end event with the same category, name, and id. 162 // 163 // Asynchronous events describe work which is happening asynchronously and which 164 // may span multiple threads. Asynchronous events do not nest. The id serves 165 // to correlate the progress of distinct asynchronous operations which share 166 // the same category and name within the same process. 167 // 168 // 0 to 15 arguments can be associated with the event, each of which is used 169 // to annotate the asynchronous operation with additional information. The 170 // arguments provided to matching async begin, async instant, and async end 171 // events are combined together in the trace; it is not necessary to repeat them. 172 // 173 // |category_literal| and |name_literal| must be null-terminated static string constants. 174 // |async_id| is the correlation id of the asynchronous operation. 175 // Must be unique for a given process, category, and name combination. 176 // |args| is the list of argument key/value pairs. 177 // 178 // Usage: 179 // 180 // trace_async_id_t async_id = 555; 181 // TRACE_ASYNC_BEGIN("category", "name", async_id, "x", TA_INT32(42)); 182 // 183 #define TRACE_ASYNC_BEGIN(category_literal, name_literal, async_id, args...) \ 184 TRACE_INTERNAL_ASYNC_BEGIN((category_literal), (name_literal), (async_id), args) 185 186 // Writes an asynchronous instant event with the specified id. 187 // 188 // Asynchronous events describe work which is happening asynchronously and which 189 // may span multiple threads. Asynchronous events do not nest. The id serves 190 // to correlate the progress of distinct asynchronous operations which share 191 // the same category and name within the same process. 192 // 193 // 0 to 15 arguments can be associated with the event, each of which is used 194 // to annotate the asynchronous operation with additional information. The 195 // arguments provided to matching async begin, async instant, and async end 196 // events are combined together in the trace; it is not necessary to repeat them. 197 // 198 // |category_literal| and |name_literal| must be null-terminated static string constants. 199 // |async_id| is the correlation id of the asynchronous operation. 200 // Must be unique for a given process, category, and name combination. 201 // |args| is the list of argument key/value pairs. 202 // 203 // Usage: 204 // 205 // trace_async_id_t async_id = 555; 206 // TRACE_ASYNC_INSTANT("category", "name", async_id, "x", TA_INT32(42)); 207 // 208 #define TRACE_ASYNC_INSTANT(category_literal, name_literal, async_id, args...) \ 209 TRACE_INTERNAL_ASYNC_INSTANT((category_literal), (name_literal), (async_id), args) 210 211 // Writes an asynchronous end event with the specified id. 212 // 213 // Asynchronous events describe work which is happening asynchronously and which 214 // may span multiple threads. Asynchronous events do not nest. The id serves 215 // to correlate the progress of distinct asynchronous operations which share 216 // the same category and name within the same process. 217 // 218 // 0 to 15 arguments can be associated with the event, each of which is used 219 // to annotate the asynchronous operation with additional information. The 220 // arguments provided to matching async begin, async instant, and async end 221 // events are combined together in the trace; it is not necessary to repeat them. 222 // 223 // |category_literal| and |name_literal| must be null-terminated static string constants. 224 // |async_id| is the correlation id of the asynchronous operation. 225 // Must be unique for a given process, category, and name combination. 226 // |args| is the list of argument key/value pairs. 227 // 228 // Usage: 229 // 230 // trace_async_id_t async_id = 555; 231 // TRACE_ASYNC_END("category", "name", async_id, "x", TA_INT32(42)); 232 // 233 #define TRACE_ASYNC_END(category_literal, name_literal, async_id, args...) \ 234 TRACE_INTERNAL_ASYNC_END((category_literal), (name_literal), (async_id), args) 235 236 // Writes a flow begin event with the specified id. 237 // This event may be followed by flow steps events and must be matched by 238 // a flow end event with the same category, name, and id. 239 // 240 // Flow events describe control flow handoffs between threads or across processes. 241 // They are typically represented as arrows in a visualizer. Flow arrows are 242 // from the end of the duration event which encloses the beginning of the flow 243 // to the beginning of the duration event which encloses the next step or the 244 // end of the flow. The id serves to correlate flows which share the same 245 // category and name across processes. 246 // 247 // This event must be enclosed in a duration event which represents where 248 // the flow handoff occurs. 249 // 250 // 0 to 15 arguments can be associated with the event, each of which is used 251 // to annotate the flow with additional information. The arguments provided 252 // to matching flow begin, flow step, and flow end events are combined together 253 // in the trace; it is not necessary to repeat them. 254 // 255 // |category_literal| and |name_literal| must be null-terminated static string constants. 256 // |flow_id| is the correlation id of the flow. 257 // Must be unique for a given category and name combination. 258 // |args| is the list of argument key/value pairs. 259 // 260 // Usage: 261 // 262 // trace_flow_id_t flow_id = 555; 263 // TRACE_FLOW_BEGIN("category", "name", flow_id, "x", TA_INT32(42)); 264 // 265 #define TRACE_FLOW_BEGIN(category_literal, name_literal, flow_id, args...) \ 266 TRACE_INTERNAL_FLOW_BEGIN((category_literal), (name_literal), (flow_id), args) 267 268 // Writes a flow step event with the specified id. 269 // 270 // Flow events describe control flow handoffs between threads or across processes. 271 // They are typically represented as arrows in a visualizer. Flow arrows are 272 // from the end of the duration event which encloses the beginning of the flow 273 // to the beginning of the duration event which encloses the next step or the 274 // end of the flow. The id serves to correlate flows which share the same 275 // category and name across processes. 276 // 277 // This event must be enclosed in a duration event which represents where 278 // the flow handoff occurs. 279 // 280 // 0 to 15 arguments can be associated with the event, each of which is used 281 // to annotate the flow with additional information. The arguments provided 282 // to matching flow begin, flow step, and flow end events are combined together 283 // in the trace; it is not necessary to repeat them. 284 // 285 // |category_literal| and |name_literal| must be null-terminated static string constants. 286 // |flow_id| is the correlation id of the flow. 287 // Must be unique for a given category and name combination. 288 // |args| is the list of argument key/value pairs. 289 // 290 // Usage: 291 // 292 // trace_flow_id_t flow_id = 555; 293 // TRACE_FLOW_STEP("category", "name", flow_id, "x", TA_INT32(42)); 294 // 295 #define TRACE_FLOW_STEP(category_literal, name_literal, flow_id, args...) \ 296 TRACE_INTERNAL_FLOW_STEP((category_literal), (name_literal), (flow_id), args) 297 298 // Writes a flow end event with the specified id. 299 // 300 // Flow events describe control flow handoffs between threads or across processes. 301 // They are typically represented as arrows in a visualizer. Flow arrows are 302 // from the end of the duration event which encloses the beginning of the flow 303 // to the beginning of the duration event which encloses the next step or the 304 // end of the flow. The id serves to correlate flows which share the same 305 // category and name across processes. 306 // 307 // This event must be enclosed in a duration event which represents where 308 // the flow handoff occurs. 309 // 310 // 0 to 15 arguments can be associated with the event, each of which is used 311 // to annotate the flow with additional information. The arguments provided 312 // to matching flow begin, flow step, and flow end events are combined together 313 // in the trace; it is not necessary to repeat them. 314 // 315 // |category_literal| and |name_literal| must be null-terminated static string constants. 316 // |flow_id| is the correlation id of the flow. 317 // Must be unique for a given category and name combination. 318 // |args| is the list of argument key/value pairs. 319 // 320 // Usage: 321 // 322 // trace_flow_id_t id = 555; 323 // TRACE_FLOW_END("category", "name", flow_id, "x", TA_INT32(42)); 324 // 325 #define TRACE_FLOW_END(category_literal, name_literal, flow_id, args...) \ 326 TRACE_INTERNAL_FLOW_END((category_literal), (name_literal), (flow_id), args) 327 328 // Writes a description of a kernel object indicated by |handle|, 329 // including its koid, name, and the supplied arguments. 330 // 331 // 0 to 15 arguments can be associated with the record, each of which is used 332 // to annotate the handle with additional information. 333 // 334 // |handle| is the handle of the object being described. 335 // |args| is the list of argument key/value pairs. 336 // 337 // Usage: 338 // 339 // zx_handle_t handle = ...; 340 // TRACE_KERNEL_OBJECT(handle, "description", TA_STRING("some object")); 341 // 342 #define TRACE_KERNEL_OBJECT(handle, args...) \ 343 TRACE_INTERNAL_KERNEL_OBJECT((handle), args) 344 345 // Writes a blob of binary data to the trace buffer. 346 // 347 // |type| is the type of the blob, and must be one of the enums in type 348 // |trace_blob_type_t|. 349 // |name_ref| is the name of the blob, and must be a string literal. 350 // |blob| is a pointer to the data. 351 // |blob_size| is the size, in bytes, of the data. 352 // 353 // A size of zero is ok. The maximum size of a blob is defined by 354 // TRACE_MAX_BLOB_SIZE which is slighly less than 32K. 355 // Exercise caution when emitting blob records: space is shared with all 356 // trace records and large blobs can eat up space fast. 357 // The blob must fit in the remaining space in the buffer. If the blob does 358 // not fit the call silently fails, as do all calls that write trace records 359 // when the buffer is full. 360 // 361 // Usage: 362 // size_t blob_size = ...; 363 // const void* blob = ...; 364 // TRACE_BLOB(TRACE_BLOB_TYPE_DATA, "my-blob", blob, blob_size); 365 // 366 #define TRACE_BLOB(type, name, blob, blob_size) \ 367 TRACE_INTERNAL_BLOB((type), (name), (blob), (blob_size)) 368 369 #endif // TRACE_INTERNAL_EVENT_COMMON_H_ 370