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