1 #ifndef TRACE2_H 2 #define TRACE2_H 3 4 /** 5 * The Trace2 API can be used to print debug, performance, and telemetry 6 * information to stderr or a file. The Trace2 feature is inactive unless 7 * explicitly enabled by enabling one or more Trace2 Targets. 8 * 9 * The Trace2 API is intended to replace the existing (Trace1) 10 * printf-style tracing provided by the existing `GIT_TRACE` and 11 * `GIT_TRACE_PERFORMANCE` facilities. During initial implementation, 12 * Trace2 and Trace1 may operate in parallel. 13 * 14 * The Trace2 API defines a set of high-level messages with known fields, 15 * such as (`start`: `argv`) and (`exit`: {`exit-code`, `elapsed-time`}). 16 * 17 * Trace2 instrumentation throughout the Git code base sends Trace2 18 * messages to the enabled Trace2 Targets. Targets transform these 19 * messages content into purpose-specific formats and write events to 20 * their data streams. In this manner, the Trace2 API can drive 21 * many different types of analysis. 22 * 23 * Targets are defined using a VTable allowing easy extension to other 24 * formats in the future. This might be used to define a binary format, 25 * for example. 26 * 27 * Trace2 is controlled using `trace2.*` config values in the system and 28 * global config files and `GIT_TRACE2*` environment variables. Trace2 does 29 * not read from repo local or worktree config files or respect `-c` 30 * command line config settings. 31 * 32 * For more info about: trace2 targets, conventions for public functions and 33 * macros, trace2 target formats and examples on trace2 API usage refer to 34 * Documentation/technical/api-trace2.txt 35 * 36 */ 37 38 struct child_process; 39 struct repository; 40 struct json_writer; 41 42 /* 43 * The public TRACE2 routines are grouped into the following groups: 44 * 45 * [] trace2_initialize -- initialization. 46 * [] trace2_cmd_* -- emit command/control messages. 47 * [] trace2_child* -- emit child start/stop messages. 48 * [] trace2_exec* -- emit exec start/stop messages. 49 * [] trace2_thread* -- emit thread start/stop messages. 50 * [] trace2_def* -- emit definition/parameter mesasges. 51 * [] trace2_region* -- emit region nesting messages. 52 * [] trace2_data* -- emit region/thread/repo data messages. 53 * [] trace2_printf* -- legacy trace[1] messages. 54 */ 55 56 /* 57 * Initialize the TRACE2 clock and do nothing else, in particular 58 * no mallocs, no system inspection, and no environment inspection. 59 * 60 * This should be called at the very top of main() to capture the 61 * process start time. This is intended to reduce chicken-n-egg 62 * bootstrap pressure. 63 * 64 * It is safe to call this more than once. This allows capturing 65 * absolute startup costs on Windows which uses a little trickery 66 * to do setup work before common-main.c:main() is called. 67 * 68 * The main trace2_initialize_fl() may be called a little later 69 * after more infrastructure is established. 70 */ 71 void trace2_initialize_clock(void); 72 73 /* 74 * Initialize TRACE2 tracing facility if any of the builtin TRACE2 75 * targets are enabled in the system config or the environment. 76 * This includes setting up the Trace2 thread local storage (TLS). 77 * Emits a 'version' message containing the version of git 78 * and the Trace2 protocol. 79 * 80 * This function should be called from `main()` as early as possible in 81 * the life of the process after essential process initialization. 82 * 83 * Cleanup/Termination is handled automatically by a registered 84 * atexit() routine. 85 */ 86 void trace2_initialize_fl(const char *file, int line); 87 88 #define trace2_initialize() trace2_initialize_fl(__FILE__, __LINE__) 89 90 /* 91 * Return 1 if trace2 is enabled (at least one target is active). 92 */ 93 int trace2_is_enabled(void); 94 95 /* 96 * Emit a 'start' event with the original (unmodified) argv. 97 */ 98 void trace2_cmd_start_fl(const char *file, int line, const char **argv); 99 100 #define trace2_cmd_start(argv) trace2_cmd_start_fl(__FILE__, __LINE__, (argv)) 101 102 /* 103 * Emit an 'exit' event. 104 * 105 * Write the exit-code that will be passed to exit() or returned 106 * from main(). 107 * 108 * Use this prior to actually calling exit(). 109 * See "#define exit()" in git-compat-util.h 110 */ 111 int trace2_cmd_exit_fl(const char *file, int line, int code); 112 113 #define trace2_cmd_exit(code) (trace2_cmd_exit_fl(__FILE__, __LINE__, (code))) 114 115 /* 116 * Emit an 'error' event. 117 * 118 * Write an error message to the TRACE2 targets. 119 */ 120 void trace2_cmd_error_va_fl(const char *file, int line, const char *fmt, 121 va_list ap); 122 123 #define trace2_cmd_error_va(fmt, ap) \ 124 trace2_cmd_error_va_fl(__FILE__, __LINE__, (fmt), (ap)) 125 126 /* 127 * Emit a 'pathname' event with the canonical pathname of the current process 128 * This gives post-processors a simple field to identify the command without 129 * having to parse the argv. For example, to distinguish invocations from 130 * installed versus debug executables. 131 */ 132 void trace2_cmd_path_fl(const char *file, int line, const char *pathname); 133 134 #define trace2_cmd_path(p) trace2_cmd_path_fl(__FILE__, __LINE__, (p)) 135 136 /* 137 * Emit an 'ancestry' event with the process name of the current process's 138 * parent process. 139 * This gives post-processors a way to determine what invoked the command and 140 * learn more about usage patterns. 141 */ 142 void trace2_cmd_ancestry_fl(const char *file, int line, const char **parent_names); 143 144 #define trace2_cmd_ancestry(v) trace2_cmd_ancestry_fl(__FILE__, __LINE__, (v)) 145 146 /* 147 * Emit a 'cmd_name' event with the canonical name of the command. 148 * This gives post-processors a simple field to identify the command 149 * without having to parse the argv. 150 */ 151 void trace2_cmd_name_fl(const char *file, int line, const char *name); 152 153 #define trace2_cmd_name(v) trace2_cmd_name_fl(__FILE__, __LINE__, (v)) 154 155 /* 156 * Emit a 'cmd_mode' event to further describe the command being run. 157 * For example, "checkout" can checkout a single file or can checkout a 158 * different branch. This gives post-processors a simple field to compare 159 * equivalent commands without having to parse the argv. 160 */ 161 void trace2_cmd_mode_fl(const char *file, int line, const char *mode); 162 163 #define trace2_cmd_mode(sv) trace2_cmd_mode_fl(__FILE__, __LINE__, (sv)) 164 165 /* 166 * Emits an "alias" message containing the alias used and the argument 167 * expansion. 168 */ 169 void trace2_cmd_alias_fl(const char *file, int line, const char *alias, 170 const char **argv); 171 172 #define trace2_cmd_alias(alias, argv) \ 173 trace2_cmd_alias_fl(__FILE__, __LINE__, (alias), (argv)) 174 175 /* 176 * Emit one or more 'def_param' events for "important" configuration 177 * settings. 178 * 179 * Use the TR2_SYSENV_CFG_PARAM setting to register a comma-separated 180 * list of patterns configured important. For example: 181 * git config --system trace2.configParams 'core.*,remote.*.url' 182 * or: 183 * GIT_TRACE2_CONFIG_PARAMS=core.*,remote.*.url" 184 * 185 * Note: this routine does a read-only iteration on the config data 186 * (using read_early_config()), so it must not be called until enough 187 * of the process environment has been established. This includes the 188 * location of the git and worktree directories, expansion of any "-c" 189 * and "-C" command line options, and etc. 190 */ 191 void trace2_cmd_list_config_fl(const char *file, int line); 192 193 #define trace2_cmd_list_config() trace2_cmd_list_config_fl(__FILE__, __LINE__) 194 195 /* 196 * Emit one or more 'def_param' events for "important" environment variables. 197 * 198 * Use the TR2_SYSENV_ENV_VARS setting to register a comma-separated list of 199 * environment variables considered important. For example: 200 * git config --system trace2.envVars 'GIT_HTTP_USER_AGENT,GIT_CONFIG' 201 * or: 202 * GIT_TRACE2_ENV_VARS="GIT_HTTP_USER_AGENT,GIT_CONFIG" 203 */ 204 void trace2_cmd_list_env_vars_fl(const char *file, int line); 205 206 #define trace2_cmd_list_env_vars() trace2_cmd_list_env_vars_fl(__FILE__, __LINE__) 207 208 /* 209 * Emit a "def_param" event for the given config key/value pair IF 210 * we consider the key to be "important". 211 * 212 * Use this for new/updated config settings created/updated after 213 * trace2_cmd_list_config() is called. 214 */ 215 void trace2_cmd_set_config_fl(const char *file, int line, const char *key, 216 const char *value); 217 218 #define trace2_cmd_set_config(k, v) \ 219 trace2_cmd_set_config_fl(__FILE__, __LINE__, (k), (v)) 220 221 /** 222 * Emits a "child_start" message containing the "child-id", 223 * "child-argv", and "child-classification". 224 * 225 * Before calling optionally set "cmd->trace2_child_class" to a string 226 * describing the type of the child process. For example, "editor" or 227 * "pager". 228 * 229 * This function assigns a unique "child-id" to `cmd->trace2_child_id`. 230 * This field is used later during the "child_exit" message to associate 231 * it with the "child_start" message. 232 * 233 * This function should be called before spawning the child process. 234 */ 235 void trace2_child_start_fl(const char *file, int line, 236 struct child_process *cmd); 237 238 #define trace2_child_start(cmd) trace2_child_start_fl(__FILE__, __LINE__, (cmd)) 239 240 /** 241 * Emits a "child_exit" message containing the "child-id", 242 * the child's elapsed time and exit-code. 243 * 244 * The reported elapsed time includes the process creation overhead and 245 * time spend waiting for it to exit, so it may be slightly longer than 246 * the time reported by the child itself. 247 * 248 * This function should be called after reaping the child process. 249 */ 250 void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd, 251 int child_exit_code); 252 253 #define trace2_child_exit(cmd, code) \ 254 trace2_child_exit_fl(__FILE__, __LINE__, (cmd), (code)) 255 256 /** 257 * Emits a "child_ready" message containing the "child-id" and a flag 258 * indicating whether the child was considered "ready" when we 259 * released it. 260 * 261 * This function should be called after starting a daemon process in 262 * the background (and after giving it sufficient time to boot 263 * up) to indicate that we no longer control or own it. 264 * 265 * The "ready" argument should contain one of { "ready", "timeout", 266 * "error" } to indicate the state of the running daemon when we 267 * released it. 268 * 269 * If the daemon process fails to start or it exits or is terminated 270 * while we are still waiting for it, the caller should emit a 271 * regular "child_exit" to report the normal process exit information. 272 * 273 */ 274 void trace2_child_ready_fl(const char *file, int line, 275 struct child_process *cmd, 276 const char *ready); 277 278 #define trace2_child_ready(cmd, ready) \ 279 trace2_child_ready_fl(__FILE__, __LINE__, (cmd), (ready)) 280 281 /** 282 * Emit an 'exec' event prior to calling one of exec(), execv(), 283 * execvp(), and etc. On Unix-derived systems, this will be the 284 * last event emitted for the current process, unless the exec 285 * fails. On Windows, exec() behaves like 'child_start' and a 286 * waitpid(), so additional events may be emitted. 287 * 288 * Returns a unique "exec-id". This value is used later 289 * if the exec() fails and a "exec-result" message is necessary. 290 */ 291 int trace2_exec_fl(const char *file, int line, const char *exe, 292 const char **argv); 293 294 #define trace2_exec(exe, argv) trace2_exec_fl(__FILE__, __LINE__, (exe), (argv)) 295 296 /** 297 * Emit an 'exec_result' when possible. On Unix-derived systems, 298 * this should be called after exec() returns (which only happens 299 * when there is an error starting the new process). On Windows, 300 * this should be called after the waitpid(). 301 * 302 * The "exec_id" should be the value returned from trace2_exec(). 303 */ 304 void trace2_exec_result_fl(const char *file, int line, int exec_id, int code); 305 306 #define trace2_exec_result(id, code) \ 307 trace2_exec_result_fl(__FILE__, __LINE__, (id), (code)) 308 309 /* 310 * Emit a 'thread_start' event. This must be called from inside the 311 * thread-proc to set up the trace2 TLS data for the thread. 312 * 313 * Thread names should be descriptive, like "preload_index". 314 * Thread names will be decorated with an instance number automatically. 315 */ 316 void trace2_thread_start_fl(const char *file, int line, 317 const char *thread_name); 318 319 #define trace2_thread_start(thread_name) \ 320 trace2_thread_start_fl(__FILE__, __LINE__, (thread_name)) 321 322 /* 323 * Emit a 'thread_exit' event. This must be called from inside the 324 * thread-proc to report thread-specific data and cleanup TLS data 325 * for the thread. 326 */ 327 void trace2_thread_exit_fl(const char *file, int line); 328 329 #define trace2_thread_exit() trace2_thread_exit_fl(__FILE__, __LINE__) 330 331 /* 332 * Emits a "def_param" message containing a key/value pair. 333 * 334 * This message is intended to report some global aspect of the current 335 * command, such as a configuration setting or command line switch that 336 * significantly affects program performance or behavior, such as 337 * `core.abbrev`, `status.showUntrackedFiles`, or `--no-ahead-behind`. 338 */ 339 void trace2_def_param_fl(const char *file, int line, const char *param, 340 const char *value); 341 342 #define trace2_def_param(param, value) \ 343 trace2_def_param_fl(__FILE__, __LINE__, (param), (value)) 344 345 /* 346 * Tell trace2 about a newly instantiated repo object and assign 347 * a trace2-repo-id to be used in subsequent activity events. 348 * 349 * Emits a 'worktree' event for this repo instance. 350 * 351 * Region and data messages may refer to this repo-id. 352 * 353 * The main/top-level repository will have repo-id value 1 (aka "r1"). 354 * 355 * The repo-id field is in anticipation of future in-proc submodule 356 * repositories. 357 */ 358 void trace2_def_repo_fl(const char *file, int line, struct repository *repo); 359 360 #define trace2_def_repo(repo) trace2_def_repo_fl(__FILE__, __LINE__, repo) 361 362 /** 363 * Emit a 'region_enter' event for <category>.<label> with optional 364 * repo-id and printf message. 365 * 366 * This function pushes a new region nesting stack level on the current 367 * thread and starts a clock for the new stack frame. 368 * 369 * The `category` field is an arbitrary category name used to classify 370 * regions by feature area, such as "status" or "index". At this time 371 * it is only just printed along with the rest of the message. It may 372 * be used in the future to filter messages. 373 * 374 * The `label` field is an arbitrary label used to describe the activity 375 * being started, such as "read_recursive" or "do_read_index". 376 * 377 * The `repo` field, if set, will be used to get the "repo-id", so that 378 * recursive operations can be attributed to the correct repository. 379 */ 380 void trace2_region_enter_fl(const char *file, int line, const char *category, 381 const char *label, const struct repository *repo, ...); 382 383 #define trace2_region_enter(category, label, repo) \ 384 trace2_region_enter_fl(__FILE__, __LINE__, (category), (label), (repo)) 385 386 void trace2_region_enter_printf_va_fl(const char *file, int line, 387 const char *category, const char *label, 388 const struct repository *repo, 389 const char *fmt, va_list ap); 390 391 #define trace2_region_enter_printf_va(category, label, repo, fmt, ap) \ 392 trace2_region_enter_printf_va_fl(__FILE__, __LINE__, (category), \ 393 (label), (repo), (fmt), (ap)) 394 395 void trace2_region_enter_printf_fl(const char *file, int line, 396 const char *category, const char *label, 397 const struct repository *repo, 398 const char *fmt, ...); 399 400 #ifdef HAVE_VARIADIC_MACROS 401 #define trace2_region_enter_printf(category, label, repo, ...) \ 402 trace2_region_enter_printf_fl(__FILE__, __LINE__, (category), (label), \ 403 (repo), __VA_ARGS__) 404 #else 405 /* clang-format off */ 406 __attribute__((format (region_enter_printf, 4, 5))) 407 void trace2_region_enter_printf(const char *category, const char *label, 408 const struct repository *repo, const char *fmt, 409 ...); 410 /* clang-format on */ 411 #endif 412 413 /** 414 * Emit a 'region_leave' event for <category>.<label> with optional 415 * repo-id and printf message. 416 * 417 * Leave current nesting level and report the elapsed time spent 418 * in this nesting level. 419 * 420 * The `category`, `label`, and `repo` fields are the same as 421 * trace2_region_enter_fl. The `category` and `label` do not 422 * need to match the corresponding "region_enter" message, 423 * but it makes the data stream easier to understand. 424 */ 425 void trace2_region_leave_fl(const char *file, int line, const char *category, 426 const char *label, const struct repository *repo, ...); 427 428 #define trace2_region_leave(category, label, repo) \ 429 trace2_region_leave_fl(__FILE__, __LINE__, (category), (label), (repo)) 430 431 void trace2_region_leave_printf_va_fl(const char *file, int line, 432 const char *category, const char *label, 433 const struct repository *repo, 434 const char *fmt, va_list ap); 435 436 #define trace2_region_leave_printf_va(category, label, repo, fmt, ap) \ 437 trace2_region_leave_printf_va_fl(__FILE__, __LINE__, (category), \ 438 (label), (repo), (fmt), (ap)) 439 440 void trace2_region_leave_printf_fl(const char *file, int line, 441 const char *category, const char *label, 442 const struct repository *repo, 443 const char *fmt, ...); 444 445 #ifdef HAVE_VARIADIC_MACROS 446 #define trace2_region_leave_printf(category, label, repo, ...) \ 447 trace2_region_leave_printf_fl(__FILE__, __LINE__, (category), (label), \ 448 (repo), __VA_ARGS__) 449 #else 450 /* clang-format off */ 451 __attribute__((format (region_leave_printf, 4, 5))) 452 void trace2_region_leave_printf(const char *category, const char *label, 453 const struct repository *repo, const char *fmt, 454 ...); 455 /* clang-format on */ 456 #endif 457 458 /** 459 * Emit a key-value pair 'data' event of the form <category>.<key> = <value>. 460 * This event implicitly contains information about thread, nesting region, 461 * and optional repo-id. 462 * This could be used to print the number of files in a directory during 463 * a multi-threaded recursive tree walk. 464 * 465 * On event-based TRACE2 targets, this generates a 'data' event suitable 466 * for post-processing. On printf-based TRACE2 targets, this is converted 467 * into a fixed-format printf message. 468 */ 469 void trace2_data_string_fl(const char *file, int line, const char *category, 470 const struct repository *repo, const char *key, 471 const char *value); 472 473 #define trace2_data_string(category, repo, key, value) \ 474 trace2_data_string_fl(__FILE__, __LINE__, (category), (repo), (key), \ 475 (value)) 476 477 void trace2_data_intmax_fl(const char *file, int line, const char *category, 478 const struct repository *repo, const char *key, 479 intmax_t value); 480 481 #define trace2_data_intmax(category, repo, key, value) \ 482 trace2_data_intmax_fl(__FILE__, __LINE__, (category), (repo), (key), \ 483 (value)) 484 485 void trace2_data_json_fl(const char *file, int line, const char *category, 486 const struct repository *repo, const char *key, 487 const struct json_writer *jw); 488 489 #define trace2_data_json(category, repo, key, value) \ 490 trace2_data_json_fl(__FILE__, __LINE__, (category), (repo), (key), \ 491 (value)) 492 493 /* 494 * Emit a 'printf' event. 495 * 496 * Write an arbitrary formatted message to the TRACE2 targets. These 497 * text messages should be considered as human-readable strings without 498 * any formatting guidelines. Post-processors may choose to ignore 499 * them. 500 */ 501 void trace2_printf_va_fl(const char *file, int line, const char *fmt, 502 va_list ap); 503 504 #define trace2_printf_va(fmt, ap) \ 505 trace2_printf_va_fl(__FILE__, __LINE__, (fmt), (ap)) 506 507 void trace2_printf_fl(const char *file, int line, const char *fmt, ...); 508 509 #ifdef HAVE_VARIADIC_MACROS 510 #define trace2_printf(...) trace2_printf_fl(__FILE__, __LINE__, __VA_ARGS__) 511 #else 512 /* clang-format off */ 513 __attribute__((format (printf, 1, 2))) 514 void trace2_printf(const char *fmt, ...); 515 /* clang-format on */ 516 #endif 517 518 /* 519 * Optional platform-specific code to dump information about the 520 * current and any parent process(es). This is intended to allow 521 * post-processors to know who spawned this git instance and anything 522 * else that the platform may be able to tell us about the current process. 523 */ 524 525 enum trace2_process_info_reason { 526 TRACE2_PROCESS_INFO_STARTUP, 527 TRACE2_PROCESS_INFO_EXIT, 528 }; 529 530 void trace2_collect_process_info(enum trace2_process_info_reason reason); 531 532 const char *trace2_session_id(void); 533 534 #endif /* TRACE2_H */ 535