trace2.h

   1 #ifndef TRACE2_H
   2 #define TRACE2_H
   3
   4 struct child_process;
   5 struct repository;
   6 struct json_writer;
   7
   8 /*
   9  * The public TRACE2 routines are grouped into the following groups:
  10  *
  11  * [] trace2_initialize -- initialization.
  12  * [] trace2_cmd_*      -- emit command/control messages.
  13  * [] trace2_child*     -- emit child start/stop messages.
  14  * [] trace2_exec*      -- emit exec start/stop messages.
  15  * [] trace2_thread*    -- emit thread start/stop messages.
  16  * [] trace2_def*       -- emit definition/parameter mesasges.
  17  * [] trace2_region*    -- emit region nesting messages.
  18  * [] trace2_data*      -- emit region/thread/repo data messages.
  19  * [] trace2_printf*    -- legacy trace[1] messages.
  20  */
  21
  22 /*
  23  * Initialize the TRACE2 clock and do nothing else, in particular
  24  * no mallocs, no system inspection, and no environment inspection.
  25  *
  26  * This should be called at the very top of main() to capture the
  27  * process start time.  This is intended to reduce chicken-n-egg
  28  * bootstrap pressure.
  29  *
  30  * It is safe to call this more than once.  This allows capturing
  31  * absolute startup costs on Windows which uses a little trickery
  32  * to do setup work before common-main.c:main() is called.
  33  *
  34  * The main trace2_initialize_fl() may be called a little later
  35  * after more infrastructure is established.
  36  */
  37 void trace2_initialize_clock(void);
  38
  39 /*
  40  * Initialize TRACE2 tracing facility if any of the builtin TRACE2
  41  * targets are enabled in the environment.  Emits a 'version' event.
  42  *
  43  * Cleanup/Termination is handled automatically by a registered
  44  * atexit() routine.
  45  */
  46 void trace2_initialize_fl(const char *file, int line);
  47
  48 #define trace2_initialize() trace2_initialize_fl(__FILE__, __LINE__)
  49
  50 /*
  51  * Return true if trace2 is enabled.
  52  */
  53 int trace2_is_enabled(void);
  54
  55 /*
  56  * Emit a 'start' event with the original (unmodified) argv.
  57  */
  58 void trace2_cmd_start_fl(const char *file, int line, const char **argv);
  59
  60 #define trace2_cmd_start(argv) trace2_cmd_start_fl(__FILE__, __LINE__, (argv))
  61
  62 /*
  63  * Emit an 'exit' event.
  64  *
  65  * Write the exit-code that will be passed to exit() or returned
  66  * from main().
  67  *
  68  * Use this prior to actually calling exit().
  69  * See "#define exit()" in git-compat-util.h
  70  */
  71 int trace2_cmd_exit_fl(const char *file, int line, int code);
  72
  73 #define trace2_cmd_exit(code) (trace2_cmd_exit_fl(__FILE__, __LINE__, (code)))
  74
  75 /*
  76  * Emit an 'error' event.
  77  *
  78  * Write an error message to the TRACE2 targets.
  79  */
  80 void trace2_cmd_error_va_fl(const char *file, int line, const char *fmt,
  81                             va_list ap);
  82
  83 #define trace2_cmd_error_va(fmt, ap) \
  84         trace2_cmd_error_va_fl(__FILE__, __LINE__, (fmt), (ap))
  85
  86 /*
  87  * Emit a 'pathname' event with the canonical pathname of the current process
  88  * This gives post-processors a simple field to identify the command without
  89  * having to parse the argv.  For example, to distinguish invocations from
  90  * installed versus debug executables.
  91  */
  92 void trace2_cmd_path_fl(const char *file, int line, const char *pathname);
  93
  94 #define trace2_cmd_path(p) trace2_cmd_path_fl(__FILE__, __LINE__, (p))
  95
  96 /*
  97  * Emit a 'cmd_name' event with the canonical name of the command.
  98  * This gives post-processors a simple field to identify the command
  99  * without having to parse the argv.
 100  */
 101 void trace2_cmd_name_fl(const char *file, int line, const char *name);
 102
 103 #define trace2_cmd_name(v) trace2_cmd_name_fl(__FILE__, __LINE__, (v))
 104
 105 /*
 106  * Emit a 'cmd_mode' event to further describe the command being run.
 107  * For example, "checkout" can checkout a single file or can checkout a
 108  * different branch.  This gives post-processors a simple field to compare
 109  * equivalent commands without having to parse the argv.
 110  */
 111 void trace2_cmd_mode_fl(const char *file, int line, const char *mode);
 112
 113 #define trace2_cmd_mode(sv) trace2_cmd_mode_fl(__FILE__, __LINE__, (sv))
 114
 115 /*
 116  * Emit an 'alias' expansion event.
 117  */
 118 void trace2_cmd_alias_fl(const char *file, int line, const char *alias,
 119                          const char **argv);
 120
 121 #define trace2_cmd_alias(alias, argv) \
 122         trace2_cmd_alias_fl(__FILE__, __LINE__, (alias), (argv))
 123
 124 /*
 125  * Emit one or more 'def_param' events for "interesting" configuration
 126  * settings.
 127  *
 128  * The environment variable "GIT_TR2_CONFIG_PARAMS" can be set to a
 129  * list of patterns considered important.  For example:
 130  *
 131  *    GIT_TR2_CONFIG_PARAMS="core.*,remote.*.url"
 132  *
 133  * Note: this routine does a read-only iteration on the config data
 134  * (using read_early_config()), so it must not be called until enough
 135  * of the process environment has been established.  This includes the
 136  * location of the git and worktree directories, expansion of any "-c"
 137  * and "-C" command line options, and etc.
 138  */
 139 void trace2_cmd_list_config_fl(const char *file, int line);
 140
 141 #define trace2_cmd_list_config() trace2_cmd_list_config_fl(__FILE__, __LINE__)
 142
 143 /*
 144  * Emit a "def_param" event for the given config key/value pair IF
 145  * we consider the key to be "interesting".
 146  *
 147  * Use this for new/updated config settings created/updated after
 148  * trace2_cmd_list_config() is called.
 149  */
 150 void trace2_cmd_set_config_fl(const char *file, int line, const char *key,
 151                               const char *value);
 152
 153 #define trace2_cmd_set_config(k, v) \
 154         trace2_cmd_set_config_fl(__FILE__, __LINE__, (k), (v))
 155
 156 /*
 157  * Emit a 'child_start' event prior to spawning a child process.
 158  *
 159  * Before calling optionally set "cmd->trace2_child_class" to a string
 160  * describing the type of the child process.  For example, "editor" or
 161  * "pager".
 162  */
 163 void trace2_child_start_fl(const char *file, int line,
 164                            struct child_process *cmd);
 165
 166 #define trace2_child_start(cmd) trace2_child_start_fl(__FILE__, __LINE__, (cmd))
 167
 168 /*
 169  * Emit a 'child_exit' event after the child process completes.
 170  */
 171 void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd,
 172                           int child_exit_code);
 173
 174 #define trace2_child_exit(cmd, code) \
 175         trace2_child_exit_fl(__FILE__, __LINE__, (cmd), (code))
 176
 177 /*
 178  * Emit an 'exec' event prior to calling one of exec(), execv(),
 179  * execvp(), and etc.  On Unix-derived systems, this will be the
 180  * last event emitted for the current process, unless the exec
 181  * fails.  On Windows, exec() behaves like 'child_start' and a
 182  * waitpid(), so additional events may be emitted.
 183  *
 184  * Returns the "exec_id".
 185  */
 186 int trace2_exec_fl(const char *file, int line, const char *exe,
 187                    const char **argv);
 188
 189 #define trace2_exec(exe, argv) trace2_exec_fl(__FILE__, __LINE__, (exe), (argv))
 190
 191 /*
 192  * Emit an 'exec_result' when possible.  On Unix-derived systems,
 193  * this should be called after exec() returns (which only happens
 194  * when there is an error starting the new process).  On Windows,
 195  * this should be called after the waitpid().
 196  *
 197  * The "exec_id" should be the value returned from trace2_exec().
 198  */
 199 void trace2_exec_result_fl(const char *file, int line, int exec_id, int code);
 200
 201 #define trace2_exec_result(id, code) \
 202         trace2_exec_result_fl(__FILE__, __LINE__, (id), (code))
 203
 204 /*
 205  * Emit a 'thread_start' event.  This must be called from inside the
 206  * thread-proc to set up the trace2 TLS data for the thread.
 207  *
 208  * Thread names should be descriptive, like "preload_index".
 209  * Thread names will be decorated with an instance number automatically.
 210  */
 211 void trace2_thread_start_fl(const char *file, int line,
 212                             const char *thread_name);
 213
 214 #define trace2_thread_start(thread_name) \
 215         trace2_thread_start_fl(__FILE__, __LINE__, (thread_name))
 216
 217 /*
 218  * Emit a 'thread_exit' event.  This must be called from inside the
 219  * thread-proc to report thread-specific data and cleanup TLS data
 220  * for the thread.
 221  */
 222 void trace2_thread_exit_fl(const char *file, int line);
 223
 224 #define trace2_thread_exit() trace2_thread_exit_fl(__FILE__, __LINE__)
 225
 226 /*
 227  * Emit a 'param' event.
 228  *
 229  * Write a "<param> = <value>" pair describing some aspect of the
 230  * run such as an important configuration setting or command line
 231  * option that significantly changes command behavior.
 232  */
 233 void trace2_def_param_fl(const char *file, int line, const char *param,
 234                          const char *value);
 235
 236 #define trace2_def_param(param, value) \
 237         trace2_def_param_fl(__FILE__, __LINE__, (param), (value))
 238
 239 /*
 240  * Tell trace2 about a newly instantiated repo object and assign
 241  * a trace2-repo-id to be used in subsequent activity events.
 242  *
 243  * Emits a 'worktree' event for this repo instance.
 244  */
 245 void trace2_def_repo_fl(const char *file, int line, struct repository *repo);
 246
 247 #define trace2_def_repo(repo) trace2_def_repo_fl(__FILE__, __LINE__, repo)
 248
 249 /*
 250  * Emit a 'region_enter' event for <category>.<label> with optional
 251  * repo-id and printf message.
 252  *
 253  * Enter a new nesting level on the current thread and remember the
 254  * current time.  This controls the indenting of all subsequent events
 255  * on this thread.
 256  */
 257 void trace2_region_enter_fl(const char *file, int line, const char *category,
 258                             const char *label, const struct repository *repo);
 259
 260 #define trace2_region_enter(category, label, repo) \
 261         trace2_region_enter_fl(__FILE__, __LINE__, (category), (label), (repo))
 262
 263 void trace2_region_enter_printf_va_fl(const char *file, int line,
 264                                       const char *category, const char *label,
 265                                       const struct repository *repo,
 266                                       const char *fmt, va_list ap);
 267
 268 #define trace2_region_enter_printf_va(category, label, repo, fmt, ap)    \
 269         trace2_region_enter_printf_va_fl(__FILE__, __LINE__, (category), \
 270                                          (label), (repo), (fmt), (ap))
 271
 272 void trace2_region_enter_printf_fl(const char *file, int line,
 273                                    const char *category, const char *label,
 274                                    const struct repository *repo,
 275                                    const char *fmt, ...);
 276
 277 #ifdef HAVE_VARIADIC_MACROS
 278 #define trace2_region_enter_printf(category, label, repo, ...)                 \
 279         trace2_region_enter_printf_fl(__FILE__, __LINE__, (category), (label), \
 280                                       (repo), __VA_ARGS__)
 281 #else
 282 /* clang-format off */
 283 __attribute__((format (region_enter_printf, 4, 5)))
 284 void trace2_region_enter_printf(const char *category, const char *label,
 285                                 const struct repository *repo, const char *fmt,
 286                                 ...);
 287 /* clang-format on */
 288 #endif
 289
 290 /*
 291  * Emit a 'region_leave' event for <category>.<label> with optional
 292  * repo-id and printf message.
 293  *
 294  * Leave current nesting level and report the elapsed time spent
 295  * in this nesting level.
 296  */
 297 void trace2_region_leave_fl(const char *file, int line, const char *category,
 298                             const char *label, const struct repository *repo);
 299
 300 #define trace2_region_leave(category, label, repo) \
 301         trace2_region_leave_fl(__FILE__, __LINE__, (category), (label), (repo))
 302
 303 void trace2_region_leave_printf_va_fl(const char *file, int line,
 304                                       const char *category, const char *label,
 305                                       const struct repository *repo,
 306                                       const char *fmt, va_list ap);
 307
 308 #define trace2_region_leave_printf_va(category, label, repo, fmt, ap)    \
 309         trace2_region_leave_printf_va_fl(__FILE__, __LINE__, (category), \
 310                                          (label), (repo), (fmt), (ap))
 311
 312 void trace2_region_leave_printf_fl(const char *file, int line,
 313                                    const char *category, const char *label,
 314                                    const struct repository *repo,
 315                                    const char *fmt, ...);
 316
 317 #ifdef HAVE_VARIADIC_MACROS
 318 #define trace2_region_leave_printf(category, label, repo, ...)                 \
 319         trace2_region_leave_printf_fl(__FILE__, __LINE__, (category), (label), \
 320                                       (repo), __VA_ARGS__)
 321 #else
 322 /* clang-format off */
 323 __attribute__((format (region_leave_printf, 4, 5)))
 324 void trace2_region_leave_printf(const char *category, const char *label,
 325                                 const struct repository *repo, const char *fmt,
 326                                 ...);
 327 /* clang-format on */
 328 #endif
 329
 330 /*
 331  * Emit a key-value pair 'data' event of the form <category>.<key> = <value>.
 332  * This event implicitly contains information about thread, nesting region,
 333  * and optional repo-id.
 334  *
 335  * On event-based TRACE2 targets, this generates a 'data' event suitable
 336  * for post-processing.  On printf-based TRACE2 targets, this is converted
 337  * into a fixed-format printf message.
 338  */
 339 void trace2_data_string_fl(const char *file, int line, const char *category,
 340                            const struct repository *repo, const char *key,
 341                            const char *value);
 342
 343 #define trace2_data_string(category, repo, key, value)                       \
 344         trace2_data_string_fl(__FILE__, __LINE__, (category), (repo), (key), \
 345                               (value))
 346
 347 void trace2_data_intmax_fl(const char *file, int line, const char *category,
 348                            const struct repository *repo, const char *key,
 349                            intmax_t value);
 350
 351 #define trace2_data_intmax(category, repo, key, value)                       \
 352         trace2_data_intmax_fl(__FILE__, __LINE__, (category), (repo), (key), \
 353                               (value))
 354
 355 void trace2_data_json_fl(const char *file, int line, const char *category,
 356                          const struct repository *repo, const char *key,
 357                          const struct json_writer *jw);
 358
 359 #define trace2_data_json(category, repo, key, value)                       \
 360         trace2_data_json_fl(__FILE__, __LINE__, (category), (repo), (key), \
 361                             (value))
 362
 363 /*
 364  * Emit a 'printf' event.
 365  *
 366  * Write an arbitrary formatted message to the TRACE2 targets.  These
 367  * text messages should be considered as human-readable strings without
 368  * any formatting guidelines.  Post-processors may choose to ignore
 369  * them.
 370  */
 371 void trace2_printf_va_fl(const char *file, int line, const char *fmt,
 372                          va_list ap);
 373
 374 #define trace2_printf_va(fmt, ap) \
 375         trace2_printf_va_fl(__FILE__, __LINE__, (fmt), (ap))
 376
 377 void trace2_printf_fl(const char *file, int line, const char *fmt, ...);
 378
 379 #ifdef HAVE_VARIADIC_MACROS
 380 #define trace2_printf(...) trace2_printf_fl(__FILE__, __LINE__, __VA_ARGS__)
 381 #else
 382 /* clang-format off */
 383 __attribute__((format (printf, 1, 2)))
 384 void trace2_printf(const char *fmt, ...);
 385 /* clang-format on */
 386 #endif
 387
 388 /*
 389  * Optional platform-specific code to dump information about the
 390  * current and any parent process(es).  This is intended to allow
 391  * post-processors to know who spawned this git instance and anything
 392  * else the platform may be able to tell us about the current process.
 393  */
 394 #if defined(GIT_WINDOWS_NATIVE)
 395 void trace2_collect_process_info(void);
 396 #else
 397 #define trace2_collect_process_info() \
 398         do {                          \
 399         } while (0)
 400 #endif
 401
 402 #endif /* TRACE2_H */