about summary refs log tree commit diff
path: root/third_party/git/trace2.h
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/trace2.h')
-rw-r--r--third_party/git/trace2.h124
1 files changed, 22 insertions, 102 deletions
diff --git a/third_party/git/trace2.h b/third_party/git/trace2.h
index e5e81c05332f..050bf3c8c19d 100644
--- a/third_party/git/trace2.h
+++ b/third_party/git/trace2.h
@@ -1,40 +1,6 @@
 #ifndef TRACE2_H
 #define TRACE2_H
 
-/**
- * The Trace2 API can be used to print debug, performance, and telemetry
- * information to stderr or a file.  The Trace2 feature is inactive unless
- * explicitly enabled by enabling one or more Trace2 Targets.
- *
- * The Trace2 API is intended to replace the existing (Trace1)
- * printf-style tracing provided by the existing `GIT_TRACE` and
- * `GIT_TRACE_PERFORMANCE` facilities.  During initial implementation,
- * Trace2 and Trace1 may operate in parallel.
- *
- * The Trace2 API defines a set of high-level messages with known fields,
- * such as (`start`: `argv`) and (`exit`: {`exit-code`, `elapsed-time`}).
- *
- * Trace2 instrumentation throughout the Git code base sends Trace2
- * messages to the enabled Trace2 Targets.  Targets transform these
- * messages content into purpose-specific formats and write events to
- * their data streams.  In this manner, the Trace2 API can drive
- * many different types of analysis.
- *
- * Targets are defined using a VTable allowing easy extension to other
- * formats in the future.  This might be used to define a binary format,
- * for example.
- *
- * Trace2 is controlled using `trace2.*` config values in the system and
- * global config files and `GIT_TRACE2*` environment variables.  Trace2 does
- * not read from repo local or worktree config files or respect `-c`
- * command line config settings.
- *
- * For more info about: trace2 targets, conventions for public functions and
- * macros, trace2 target formats and examples on trace2 API usage refer to
- * Documentation/technical/api-trace2.txt
- *
- */
-
 struct child_process;
 struct repository;
 struct json_writer;
@@ -73,12 +39,7 @@ void trace2_initialize_clock(void);
 /*
  * Initialize TRACE2 tracing facility if any of the builtin TRACE2
  * targets are enabled in the system config or the environment.
- * This includes setting up the Trace2 thread local storage (TLS).
- * Emits a 'version' message containing the version of git
- * and the Trace2 protocol.
- *
- * This function should be called from `main()` as early as possible in
- * the life of the process after essential process initialization.
+ * Emits a 'version' event.
  *
  * Cleanup/Termination is handled automatically by a registered
  * atexit() routine.
@@ -88,7 +49,7 @@ void trace2_initialize_fl(const char *file, int line);
 #define trace2_initialize() trace2_initialize_fl(__FILE__, __LINE__)
 
 /*
- * Return 1 if trace2 is enabled (at least one target is active).
+ * Return true if trace2 is enabled.
  */
 int trace2_is_enabled(void);
 
@@ -153,8 +114,7 @@ void trace2_cmd_mode_fl(const char *file, int line, const char *mode);
 #define trace2_cmd_mode(sv) trace2_cmd_mode_fl(__FILE__, __LINE__, (sv))
 
 /*
- * Emits an "alias" message containing the alias used and the argument
- * expansion.
+ * Emit an 'alias' expansion event.
  */
 void trace2_cmd_alias_fl(const char *file, int line, const char *alias,
 			 const char **argv);
@@ -163,7 +123,7 @@ void trace2_cmd_alias_fl(const char *file, int line, const char *alias,
 	trace2_cmd_alias_fl(__FILE__, __LINE__, (alias), (argv))
 
 /*
- * Emit one or more 'def_param' events for "important" configuration
+ * Emit one or more 'def_param' events for "interesting" configuration
  * settings.
  *
  * Use the TR2_SYSENV_CFG_PARAM setting to register a comma-separated
@@ -184,7 +144,7 @@ void trace2_cmd_list_config_fl(const char *file, int line);
 
 /*
  * Emit a "def_param" event for the given config key/value pair IF
- * we consider the key to be "important".
+ * we consider the key to be "interesting".
  *
  * Use this for new/updated config settings created/updated after
  * trace2_cmd_list_config() is called.
@@ -195,34 +155,20 @@ void trace2_cmd_set_config_fl(const char *file, int line, const char *key,
 #define trace2_cmd_set_config(k, v) \
 	trace2_cmd_set_config_fl(__FILE__, __LINE__, (k), (v))
 
-/**
- * Emits a "child_start" message containing the "child-id",
- * "child-argv", and "child-classification".
+/*
+ * Emit a 'child_start' event prior to spawning a child process.
  *
  * Before calling optionally set "cmd->trace2_child_class" to a string
  * describing the type of the child process.  For example, "editor" or
  * "pager".
- *
- * This function assigns a unique "child-id" to `cmd->trace2_child_id`.
- * This field is used later during the "child_exit" message to associate
- * it with the "child_start" message.
- *
- * This function should be called before spawning the child process.
  */
 void trace2_child_start_fl(const char *file, int line,
 			   struct child_process *cmd);
 
 #define trace2_child_start(cmd) trace2_child_start_fl(__FILE__, __LINE__, (cmd))
 
-/**
- * Emits a "child_exit" message containing the "child-id",
- * the child's elapsed time and exit-code.
- *
- * The reported elapsed time includes the process creation overhead and
- * time spend waiting for it to exit, so it may be slightly longer than
- * the time reported by the child itself.
- *
- * This function should be called after reaping the child process.
+/*
+ * Emit a 'child_exit' event after the child process completes.
  */
 void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd,
 			  int child_exit_code);
@@ -230,22 +176,21 @@ void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd,
 #define trace2_child_exit(cmd, code) \
 	trace2_child_exit_fl(__FILE__, __LINE__, (cmd), (code))
 
-/**
+/*
  * Emit an 'exec' event prior to calling one of exec(), execv(),
  * execvp(), and etc.  On Unix-derived systems, this will be the
  * last event emitted for the current process, unless the exec
  * fails.  On Windows, exec() behaves like 'child_start' and a
  * waitpid(), so additional events may be emitted.
  *
- * Returns a unique "exec-id".  This value is used later
- * if the exec() fails and a "exec-result" message is necessary.
+ * Returns the "exec_id".
  */
 int trace2_exec_fl(const char *file, int line, const char *exe,
 		   const char **argv);
 
 #define trace2_exec(exe, argv) trace2_exec_fl(__FILE__, __LINE__, (exe), (argv))
 
-/**
+/*
  * Emit an 'exec_result' when possible.  On Unix-derived systems,
  * this should be called after exec() returns (which only happens
  * when there is an error starting the new process).  On Windows,
@@ -281,12 +226,11 @@ void trace2_thread_exit_fl(const char *file, int line);
 #define trace2_thread_exit() trace2_thread_exit_fl(__FILE__, __LINE__)
 
 /*
- * Emits a "def_param" message containing a key/value pair.
+ * Emit a 'param' event.
  *
- * This message is intended to report some global aspect of the current
- * command, such as a configuration setting or command line switch that
- * significantly affects program performance or behavior, such as
- * `core.abbrev`, `status.showUntrackedFiles`, or `--no-ahead-behind`.
+ * Write a "<param> = <value>" pair describing some aspect of the
+ * run such as an important configuration setting or command line
+ * option that significantly changes command behavior.
  */
 void trace2_def_param_fl(const char *file, int line, const char *param,
 			 const char *value);
@@ -299,35 +243,18 @@ void trace2_def_param_fl(const char *file, int line, const char *param,
  * a trace2-repo-id to be used in subsequent activity events.
  *
  * Emits a 'worktree' event for this repo instance.
- *
- * Region and data messages may refer to this repo-id.
- *
- * The main/top-level repository will have repo-id value 1 (aka "r1").
- *
- * The repo-id field is in anticipation of future in-proc submodule
- * repositories.
  */
 void trace2_def_repo_fl(const char *file, int line, struct repository *repo);
 
 #define trace2_def_repo(repo) trace2_def_repo_fl(__FILE__, __LINE__, repo)
 
-/**
+/*
  * Emit a 'region_enter' event for <category>.<label> with optional
  * repo-id and printf message.
  *
- * This function pushes a new region nesting stack level on the current
- * thread and starts a clock for the new stack frame.
- *
- * The `category` field is an arbitrary category name used to classify
- * regions by feature area, such as "status" or "index".  At this time
- * it is only just printed along with the rest of the message.  It may
- * be used in the future to filter messages.
- *
- * The `label` field is an arbitrary label used to describe the activity
- * being started, such as "read_recursive" or "do_read_index".
- *
- * The `repo` field, if set, will be used to get the "repo-id", so that
- * recursive oerations can be attributed to the correct repository.
+ * Enter a new nesting level on the current thread and remember the
+ * current time.  This controls the indenting of all subsequent events
+ * on this thread.
  */
 void trace2_region_enter_fl(const char *file, int line, const char *category,
 			    const char *label, const struct repository *repo, ...);
@@ -362,17 +289,12 @@ void trace2_region_enter_printf(const char *category, const char *label,
 /* clang-format on */
 #endif
 
-/**
+/*
  * Emit a 'region_leave' event for <category>.<label> with optional
  * repo-id and printf message.
  *
  * Leave current nesting level and report the elapsed time spent
  * in this nesting level.
- *
- * The `category`, `label`, and `repo` fields are the same as
- * trace2_region_enter_fl. The `category` and `label` do not
- * need to match the corresponding "region_enter" message,
- * but it makes the data stream easier to understand.
  */
 void trace2_region_leave_fl(const char *file, int line, const char *category,
 			    const char *label, const struct repository *repo, ...);
@@ -407,12 +329,10 @@ void trace2_region_leave_printf(const char *category, const char *label,
 /* clang-format on */
 #endif
 
-/**
+/*
  * Emit a key-value pair 'data' event of the form <category>.<key> = <value>.
  * This event implicitly contains information about thread, nesting region,
  * and optional repo-id.
- * This could be used to print the number of files in a directory during
- * a multi-threaded recursive tree walk.
  *
  * On event-based TRACE2 targets, this generates a 'data' event suitable
  * for post-processing.  On printf-based TRACE2 targets, this is converted