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