= Trace2 API 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. == Trace2 Targets Trace2 defines the following set of Trace2 Targets. Format details are given in a later section. === The Normal Format Target The normal format target is a tradition printf format and similar to GIT_TRACE format. This format is enabled with the `GIT_TRACE2` environment variable or the `trace2.normalTarget` system or global config setting. For example ------------ $ export GIT_TRACE2=~/log.normal $ git version git version 2.20.1.155.g426c96fcdb ------------ or ------------ $ git config --global trace2.normalTarget ~/log.normal $ git version git version 2.20.1.155.g426c96fcdb ------------ yields ------------ $ cat ~/log.normal 12:28:42.620009 common-main.c:38 version 2.20.1.155.g426c96fcdb 12:28:42.620989 common-main.c:39 start git version 12:28:42.621101 git.c:432 cmd_name version (version) 12:28:42.621215 git.c:662 exit elapsed:0.001227 code:0 12:28:42.621250 trace2/tr2_tgt_normal.c:124 atexit elapsed:0.001265 code:0 ------------ === The Performance Format Target The performance format target (PERF) is a column-based format to replace GIT_TRACE_PERFORMANCE and is suitable for development and testing, possibly to complement tools like gprof. This format is enabled with the `GIT_TRACE2_PERF` environment variable or the `trace2.perfTarget` system or global config setting. For example ------------ $ export GIT_TRACE2_PERF=~/log.perf $ git version git version 2.20.1.155.g426c96fcdb ------------ or ------------ $ git config --global trace2.perfTarget ~/log.perf $ git version git version 2.20.1.155.g426c96fcdb ------------ yields ------------ $ cat ~/log.perf 12:28:42.620675 common-main.c:38 | d0 | main | version | | | | | 2.20.1.155.g426c96fcdb 12:28:42.621001 common-main.c:39 | d0 | main | start | | 0.001173 | | | git version 12:28:42.621111 git.c:432 | d0 | main | cmd_name | | | | | version (version) 12:28:42.621225 git.c:662 | d0 | main | exit | | 0.001227 | | | code:0 12:28:42.621259 trace2/tr2_tgt_perf.c:211 | d0 | main | atexit | | 0.001265 | | | code:0 ------------ === The Event Format Target The event format target is a JSON-based format of event data suitable for telemetry analysis. This format is enabled with the `GIT_TRACE2_EVENT` environment variable or the `trace2.eventTarget` system or global config setting. For example ------------ $ export GIT_TRACE2_EVENT=~/log.event $ git version git version 2.20.1.155.g426c96fcdb ------------ or ------------ $ git config --global trace2.eventTarget ~/log.event $ git version git version 2.20.1.155.g426c96fcdb ------------ yields ------------ $ cat ~/log.event {"event":"version","sid":"sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"3","exe":"2.20.1.155.g426c96fcdb"} {"event":"start","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621027Z","file":"common-main.c","line":39,"t_abs":0.001173,"argv":["git","version"]} {"event":"cmd_name","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621122Z","file":"git.c","line":432,"name":"version","hierarchy":"version"} {"event":"exit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621236Z","file":"git.c","line":662,"t_abs":0.001227,"code":0} {"event":"atexit","sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.621268Z","file":"trace2/tr2_tgt_event.c","line":163,"t_abs":0.001265,"code":0} ------------ === Enabling a Target To enable a target, set the corresponding environment variable or system or global config value to one of the following: include::../trace2-target-values.txt[] When trace files are written to a target directory, they will be named according to the last component of the SID (optionally followed by a counter to avoid filename collisions). == Trace2 API All public Trace2 functions and macros are defined in `trace2.h` and `trace2.c`. All public symbols are prefixed with `trace2_`. There are no public Trace2 data structures. The Trace2 code also defines a set of private functions and data types in the `trace2/` directory. These symbols are prefixed with `tr2_` and should only be used by functions in `trace2.c`. == Conventions for Public Functions and Macros The functions defined by the Trace2 API are declared and documented in `trace2.h`. It defines the API functions and wrapper macros for Trace2. Some functions have a `_fl()` suffix to indicate that they take `file` and `line-number` arguments. Some functions have a `_va_fl()` suffix to indicate that they also take a `va_list` argument. Some functions have a `_printf_fl()` suffix to indicate that they also take a varargs argument. There are CPP wrapper macros and ifdefs to hide most of these details. See `trace2.h` for more details. The following discussion will only describe the simplified forms. == Public API All Trace2 API functions send a message to all of the active Trace2 Targets. This section describes the set of available messages. It helps to divide these functions into groups for discussion purposes. === Basic Command Messages These are concerned with the lifetime of the overall git process. e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`, `int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`. === Command Detail Messages These are concerned with describing the specific Git command after the command line, config, and environment are inspected. e.g: `void trace2_cmd_name(const char *name)`, `void trace2_cmd_mode(const char *mode)`. === Child Process Messages These are concerned with the various spawned child processes, including shell scripts, git commands, editors, pagers, and hooks. e.g: `void trace2_child_start(struct child_process *cmd)`. === Git Thread Messages These messages are concerned with Git thread usage. e.g: `void trace2_thread_start(const char *thread_name)`. === Region and Data Messages These are concerned with recording performance data over regions or spans of code. e.g: `void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`. Refer to trace2.h for details about all trace2 functions. == Trace2 Target Formats === NORMAL Format Events are written as lines of the form: ------------ [