= 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":"1","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[]
If the target already exists and is a directory, the traces will be
written to files (one per process) underneath the given 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_`
|