Git 2.22 (Q2 2019) introduces trace2 with commit ee4512e by Jeff Hostetler :
trace2 : create a new combined tracer
Create a new unified tracer for git.
A possible intention is to replace the current routines trace_printf* and trace_performance* unified set of routines git_trace2* .
In addition to the regular printf-style API, trace2 provides a higher level event verb with fixed fields that allow you to write structured data.
This facilitates post-processing and analysis for external tools.
Trace2 defines 3 output targets.
They are set using the environment variables " GIT_TR2 ", " GIT_TR2_PERF " and " GIT_TR2_EVENT ".
They can be set to "1" or an absolute path (exactly the same as the current GIT_TRACE ).
Note: for the environment variable name, always use GIT_TRACExxx , not GIT_TRxxx .
So actually GIT_TRACE2 , GIT_TRACE2_PERF or GIT_TRACE2_EVENT .
See the renaming of Git 2.22, mentioned below.
The following is the initial work on this new trace function with the old environment variable names:
GIT_TR2 intended to replace the GIT_TRACE and the logs summary data.
GIT_TR2_PERF intended to replace GIT_TRACE_PERFORMANCE .
It expands the output columns for the team process, flow, repo, absolute and relative elapsed time. It reports events for starting / stopping a child process, starting / stopping a thread, and a function for each nesting thread.
GIT_TR2_EVENT is a new structured format. It records event data as a series of JSON records.
Trace2 function calls are logged into any of the 3 included output targets without the need to call the various routines trace_printf* or trace_performance* .
See commit a4d3a28 (March 21, 2019) by Josh Steadmon ( steadmon ) . (Merged by Junio C Hamano - [TG423] - in commit 1b40314 , 08 May 2019)
trace2 : write to target directory
If the value of the environment variable trace2 is an absolute path that refers to an existing directory, write the output to files (one per process) under the specified directory.
Files will be named according to the last SID trace2 component followed by a counter to avoid potential conflicts.
This makes it more convenient to collect traces for each git call, unconditionally setting the corresponding trace2 envvar constant directory name.
see also
commit f672dee (April 29, 2019) and commit 81567ca , commit 08881b9 , commit bad229a , commit 26c6f25 , commit bce9db6 , commit 800a7f9 , commit a7bc01e , commit 39f4317 , commit a089724 , commit 1703751 (April 15, 2019) Jeffrey jeffhostetler . (Merged by Junio C Hamano - [TG427] - in commit 5b2d1c0 , 13 May 2019)
new documentation
now includes configuration parameters that are read only from the system and global configuration files (which means that local configuration files and working tree configuration files and -c command line arguments are not taken into account). An example :
$ git config --global trace2.normalTarget ~/log.normal $ git version git version 2.20.1.155.g426c96fcdb
gives
$ 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
And for
performance indicator
:
$ git config --global trace2.perfTarget ~/log.perf $ git version git version 2.20.1.155.g426c96fcdb
gives
$ 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
As described in Git 2.23 (Q3 2019), the environment variable used is
GIT_TRACE2
. See commit 6114a40
(June 26, 2019) by Carlo Marcelo Arenas Belon ( carenas ) . See commit 3efa1c6
(June 12, 2019), author Æwar Arnfjord Bjarmason ( avar ) . (Merged by Junio C Hamano - [TG436] - in commit e9eaaa4 , 09 Jul 2019) This follows the work done in Git 2.22:
commit 4e0d3aa
commit e4b75d6 (May 19, 2019) SZEDER Gábor ( szeder ) . . (Merged by Junio C Hamano - [TG438] - in commit 463dca6 , 30 May 2019)
trace2 : rename environment variables to GIT_TRACE2 *
For the environment variable that users should set, the GIT_TR2* variables GIT_TR2* simply too obscure, inconsistent, and ugly.
Most of the established GIT_* environment variables don't use abbreviations, and in case of the few that do ( GIT_DIR , GIT_COMMON_DIR , GIT_DIFF_OPTS ) it quite obvious what the abbreviations ( DIR and OPTS ) stand for.
But what does TR stand for? Track, traditional, trailer, transaction, transfer, transformation, transition, translation, transplant, transport, traversal, tree, trigger, truncate, trust, or ...?!
The trace2 tool, as the suffix name "2" implies, should eventually replace the original Git trace.It is reasonable to expect the corresponding environment variables to follow suit, and after the original GIT_TRACE variables they are called GIT_TRACE2 ; there is no such thing as " GIT_TR ".
All trace2-specific configuration variables are very reasonable Section " trace2 ", not " tr2 ".
General relativity
we get nothing by omitting the last three “trace” characters from the names of these environment variables . So, let's rename all the GIT_TR2* environment variables to GIT_TRACE2* before they get to the stable release.
Git 2.24 (Q3 2019) improves the initialization of the Git repository.
Cm.
commit 22932d9 , commit 5732f2b , commit 58ebccb (August 6, 2019) by Jeff King ( peff ) . .
(Merged by Junio C Hamano - [TG456] - in commit b4a1eec , 09 Sep 2019)
common-main: trace2 initialization delay
We initialize the trace2 system in the general function main () so that all programs (even those that are not built-in) will include tracing.
But running trace2 relatively difficult, since we have to read the configuration on disk to decide whether to track.
This can cause unexpected interactions with other common core initializations. For example, we will prove the configuration code before calling initialize_the_repository() , and the usual invariant, which the_repository will never be NULL, will not be held.
Let's push the initialization of trace2 further down in general, so that shortly before we execute cmd_main() .