Text of kernel.org › pub › software › scm › git › docs › technical › api-trace2.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Trace2 API

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, nor does it 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 traditional printf () format and similar to the 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":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"4","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: 0 or false - Disables the target.

1 or true - Writes to STDERR . [ 2-9 ] - Writes to the already opened file descriptor. <absolute-pathname> - Writes to the file in append mode. If the target already exists and is a directory, the traces will be written to files (one per process) underneath the given directory. af_unix: [ <socket-type> : ] <absolute-pathname> - Write to a Unix DomainSocket (on platforms that support them). Socket type can be either stream or dgram ; if omitted Git will try both.

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 The Trace2 public API is defined and documented in trace2.h ; refer to it for more information. All public functions and macros are prefixed with trace2_ and are implemented in trace2.c . 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 (or other private source files in trace2/ ). Conventions for Public Functions and Macros 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 printf () style format with a variable number of arguments. CPP wrapper macros are defined to hide most of these details. Trace2 Target Formats NORMAL Format Events are written as lines of the form: [<time> SP <filename>:<line> SP+] <event-name> [[SP] <event-message>] LF <event-name> is the event name. <event-message> is a free-form printf () message intended for human consumption.

Note that this may contain embedded LF or CRLF characters that are not escaped, so the event may spill across multiple lines. If GIT_TRACE2_BRIEF or trace2.normalBrief is true, the time , filename , and line fields are omitted. This target is intended to be more of a summary (like GIT_TRACE) and less detailed than the other targets. It ignores thread, region, and data messages, for example. PERF Format Events are written as lines of the form: [<time> SP <filename>:<line> SP+ BAR SP] d<depth> SP BAR SP <thread-name> SP+ BAR SP <event-name> SP+ BAR SP [r<repo-id>] SP+ BAR SP [<t_abs>] SP+ BAR SP [<t_rel>] SP+ BAR SP [<category>] SP+ BAR SP DOTS* <perf-event-message> LF <depth> is the git process depth.

This is the number of parent git processes. A top-level git command has depth value "d0". A child of it has depth value "d1". A second level child has depth value "d2" and so on. <thread-name> is a unique name for the thread. The primary thread is called "main". Other thread names are of the form "th%d:%s" and include a unique number and the name of the thread-proc. <event-name> is the event name. <repo-id> when present, is a number indicating the repository in use.

A def_repo event is emitted when a repository is opened. This defines the repo-id and associated worktree. Subsequent repo-specific events will reference this repo-id. Currently, this is always "r1" for the main repository. This field is in anticipation of in-proc submodules in the fut

The rest of this page is on the live site.