trace2.h

   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 */