trace2.normalTarget::
This variable controls the normal target destination.
- It may be overridden by the `GIT_TR2` environment variable.
+ It may be overridden by the `GIT_TRACE2` environment variable.
The following table shows possible values.
trace2.perfTarget::
This variable controls the performance target destination.
- It may be overridden by the `GIT_TR2_PERF` environment variable.
+ It may be overridden by the `GIT_TRACE2_PERF` environment variable.
The following table shows possible values.
trace2.eventTarget::
This variable controls the event target destination.
- It may be overridden by the `GIT_TR2_EVENT` environment variable.
+ It may be overridden by the `GIT_TRACE2_EVENT` environment variable.
The following table shows possible values.
+
include::../trace2-target-values.txt[]
trace2.normalBrief::
Boolean. When true `time`, `filename`, and `line` fields are
omitted from normal output. May be overridden by the
- `GIT_TR2_BRIEF` environment variable. Defaults to false.
+ `GIT_TRACE2_BRIEF` environment variable. Defaults to false.
trace2.perfBrief::
Boolean. When true `time`, `filename`, and `line` fields are
omitted from PERF output. May be overridden by the
- `GIT_TR2_PERF_BRIEF` environment variable. Defaults to false.
+ `GIT_TRACE2_PERF_BRIEF` environment variable. Defaults to false.
trace2.eventBrief::
Boolean. When true `time`, `filename`, and `line` fields are
omitted from event output. May be overridden by the
- `GIT_TR2_EVENT_BRIEF` environment variable. Defaults to false.
+ `GIT_TRACE2_EVENT_BRIEF` environment variable. Defaults to false.
trace2.eventNesting::
Integer. Specifies desired depth of nested regions in the
event output. Regions deeper than this value will be
- omitted. May be overridden by the `GIT_TR2_EVENT_NESTING`
+ omitted. May be overridden by the `GIT_TRACE2_EVENT_NESTING`
environment variable. Defaults to 2.
trace2.configParams::
settings that should be recorded in the trace2 output.
For example, `core.*,remote.*.url` would cause the trace2
output to contain events listing each configured remote.
- May be overridden by the `GIT_TR2_CONFIG_PARAMS` environment
+ May be overridden by the `GIT_TRACE2_CONFIG_PARAMS` environment
variable. Unset by default.
trace2.destinationDebug::
trace target destination cannot be opened for writing.
By default, these errors are suppressed and tracing is
silently disabled. May be overridden by the
- `GIT_TR2_DST_DEBUG` environment variable.
+ `GIT_TRACE2_DST_DEBUG` environment variable.
When a curl trace is enabled (see `GIT_TRACE_CURL` above), do not dump
data (that is, only dump info lines and headers).
-`GIT_TR2`::
+`GIT_TRACE2`::
Enables more detailed trace messages from the "trace2" library.
- Output from `GIT_TR2` is a simple text-based format for human
+ Output from `GIT_TRACE2` is a simple text-based format for human
readability.
+
-The `GIT_TR2` variables can take many values. Any value available to
-the `GIT_TRACE` variables is also available to `GIT_TR2`. The `GIT_TR2`
+The `GIT_TRACE2` variables can take many values. Any value available to
+the `GIT_TRACE` variables is also available to `GIT_TRACE2`. The `GIT_TRACE2`
variables can also specify a Unix Domain Socket. See
link:technical/api-trace2.html[Trace2 documentation] for full details.
-`GIT_TR2_EVENT`::
+`GIT_TRACE2_EVENT`::
This setting writes a JSON-based format that is suited for machine
interpretation. See link:technical/api-trace2.html[Trace2 documentation]
for full details.
-`GIT_TR2_PERF`::
- In addition to the text-based messages available in `GIT_TR2`, this
+`GIT_TRACE2_PERF`::
+ In addition to the text-based messages available in `GIT_TRACE2`, this
setting writes a column-based format for understanding nesting
regions. See link:technical/api-trace2.html[Trace2 documentation]
for full details.
for example.
Trace2 is controlled using `trace2.*` config values in the system and
-global config files and `GIT_TR2*` environment variables. Trace2 does
+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 example
------------
-$ export GIT_TR2=~/log.normal
+$ export GIT_TRACE2=~/log.normal
$ git version
git version 2.20.1.155.g426c96fcdb
------------
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_TR2_PERF` environment variable or the
+enabled with the `GIT_TRACE2_PERF` environment variable or the
`trace2.perfTarget` system or global config setting.
For example
------------
-$ export GIT_TR2_PERF=~/log.perf
+$ export GIT_TRACE2_PERF=~/log.perf
$ git version
git version 2.20.1.155.g426c96fcdb
------------
=== 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_TR2_EVENT`
+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_TR2_EVENT=~/log.event
+$ export GIT_TRACE2_EVENT=~/log.event
$ git version
git version 2.20.1.155.g426c96fcdb
------------
Emits a "def_param" messages for "important" configuration
settings.
+
-The environment variable `GIT_TR2_CONFIG_PARAMS` or the `trace2.configParams`
+The environment variable `GIT_TRACE2_CONFIG_PARAMS` or the `trace2.configParams`
config value can be set to a
list of patterns of important configuration settings, for example:
`core.*,remote.*.url`. This function will iterate over all config
Note that this may contain embedded LF or CRLF characters that are
not escaped, so the event may spill across multiple lines.
-If `GIT_TR2_BRIEF` or `trace2.normalBrief` is true, the `time`, `filename`,
+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
15:33:33.532712 wt-status.c:2331 | d0 | main | region_leave | r1 | 0.127568 | 0.001504 | status | label:print
------------
-If `GIT_TR2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`,
+If `GIT_TRACE2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`,
and `line` fields are omitted.
------------
`"repo":<repo-id>`::
when present, is the integer repo-id as described previously.
-If `GIT_TR2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file`
+If `GIT_TRACE2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file`
and `line` fields are omitted from all events and the `time` field is
only present on the "start" and "atexit" events.
The `category` field may be used in a future enhancement to
do category-based filtering.
+
-`GIT_TR2_EVENT_NESTING` or `trace2.eventNesting` can be used to
+`GIT_TRACE2_EVENT_NESTING` or `trace2.eventNesting` can be used to
filter deeply nested regions and data events. It defaults to "2".
`"region_leave"`::
5.199 seconds and of that 4.932 was in ssh.
+
----------------
-$ export GIT_TR2_BRIEF=1
-$ export GIT_TR2=~/log.normal
+$ export GIT_TRACE2_BRIEF=1
+$ export GIT_TRACE2=~/log.normal
$ git fetch origin
...
----------------
indented for clarity.)
+
----------------
-$ export GIT_TR2_BRIEF=1
-$ export GIT_TR2=~/log.normal
+$ export GIT_TRACE2_BRIEF=1
+$ export GIT_TRACE2=~/log.normal
$ git fetch origin
...
----------------
+0.027149 (since the process started) and took 0.014581 seconds.
+
----------------
-$ export GIT_TR2_PERF_BRIEF=1
-$ export GIT_TR2_PERF=~/log.perf
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
$ git status
...
We can further investigate the time spent scanning for untracked files.
+
----------------
-$ export GIT_TR2_PERF_BRIEF=1
-$ export GIT_TR2_PERF=~/log.perf
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
$ git status
...
$ cat ~/log.perf
This example shows that the index contained 3552 entries.
+
----------------
-$ export GIT_TR2_PERF_BRIEF=1
-$ export GIT_TR2_PERF=~/log.perf
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
$ git status
...
$ cat ~/log.perf
to report the per-thread parameters.
+
----------------
-$ export GIT_TR2_PERF_BRIEF=1
-$ export GIT_TR2_PERF=~/log.perf
+$ export GIT_TRACE2_PERF_BRIEF=1
+$ export GIT_TRACE2_PERF=~/log.perf
$ git status
...
$ cat ~/log.perf
sed -n \
-e "/^GIT_PREFIX=/d" \
-e "/^GIT_TEXTDOMAINDIR=/d" \
- -e "/^GIT_TR2_PARENT/d" \
+ -e "/^GIT_TRACE2_PARENT/d" \
-e "/^GIT_/s/=.*//p" |
sort
EOF
. ./test-lib.sh
# Turn off any inherited trace2 settings for this test.
-sane_unset GIT_TR2 GIT_TR2_PERF GIT_TR2_EVENT
-sane_unset GIT_TR2_BRIEF
-sane_unset GIT_TR2_CONFIG_PARAMS
+sane_unset GIT_TRACE2 GIT_TRACE2_PERF GIT_TRACE2_EVENT
+sane_unset GIT_TRACE2_BRIEF
+sane_unset GIT_TRACE2_CONFIG_PARAMS
# Add t/helper directory to PATH so that we can use a relative
# path to run nested instances of test-tool.exe (see 004child).
# to whatever filtering that target decides to do).
# This script tests the normal target in isolation.
#
-# Defer setting GIT_TR2 until the actual command line we want to test
+# Defer setting GIT_TRACE2 until the actual command line we want to test
# because hidden git and test-tool commands run by the test harness
# can contaminate our output.
# Enable "brief" feature which turns off "<clock> <file>:<line> " prefix.
-GIT_TR2_BRIEF=1 && export GIT_TR2_BRIEF
+GIT_TRACE2_BRIEF=1 && export GIT_TRACE2_BRIEF
# Basic tests of the trace2 normal stream. Since this stream is used
# primarily with printf-style debugging/tracing, we do limited testing
test_expect_success 'normal stream, return code 0' '
test_when_finished "rm trace.normal actual expect" &&
- GIT_TR2="$(pwd)/trace.normal" test-tool trace2 001return 0 &&
+ GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 001return 0 &&
perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
cat >expect <<-EOF &&
version $V
test_expect_success 'normal stream, return code 1' '
test_when_finished "rm trace.normal actual expect" &&
- test_must_fail env GIT_TR2="$(pwd)/trace.normal" test-tool trace2 001return 1 &&
+ test_must_fail env GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 001return 1 &&
perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
cat >expect <<-EOF &&
version $V
test_expect_success 'automatic filename' '
test_when_finished "rm -r traces actual expect" &&
mkdir traces &&
- GIT_TR2="$(pwd)/traces" test-tool trace2 001return 0 &&
+ GIT_TRACE2="$(pwd)/traces" test-tool trace2 001return 0 &&
perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <"$(ls traces/*)" >actual &&
cat >expect <<-EOF &&
version $V
test_expect_success 'normal stream, exit code 0' '
test_when_finished "rm trace.normal actual expect" &&
- GIT_TR2="$(pwd)/trace.normal" test-tool trace2 002exit 0 &&
+ GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 002exit 0 &&
perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
cat >expect <<-EOF &&
version $V
test_expect_success 'normal stream, exit code 1' '
test_when_finished "rm trace.normal actual expect" &&
- test_must_fail env GIT_TR2="$(pwd)/trace.normal" test-tool trace2 002exit 1 &&
+ test_must_fail env GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 002exit 1 &&
perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
cat >expect <<-EOF &&
version $V
test_expect_success 'normal stream, error event' '
test_when_finished "rm trace.normal actual expect" &&
- GIT_TR2="$(pwd)/trace.normal" test-tool trace2 003error "hello world" "this is a test" &&
+ GIT_TRACE2="$(pwd)/trace.normal" test-tool trace2 003error "hello world" "this is a test" &&
perl "$TEST_DIRECTORY/t0210/scrub_normal.perl" <trace.normal >actual &&
cat >expect <<-EOF &&
version $V
test_cmp expect actual
'
-sane_unset GIT_TR2_BRIEF
+sane_unset GIT_TRACE2_BRIEF
# Now test without environment variables and get all Trace2 settings
# from the global config.
. ./test-lib.sh
# Turn off any inherited trace2 settings for this test.
-sane_unset GIT_TR2 GIT_TR2_PERF GIT_TR2_EVENT
-sane_unset GIT_TR2_PERF_BRIEF
-sane_unset GIT_TR2_CONFIG_PARAMS
+sane_unset GIT_TRACE2 GIT_TRACE2_PERF GIT_TRACE2_EVENT
+sane_unset GIT_TRACE2_PERF_BRIEF
+sane_unset GIT_TRACE2_CONFIG_PARAMS
# Add t/helper directory to PATH so that we can use a relative
# path to run nested instances of test-tool.exe (see 004child).
# to whatever filtering that target decides to do).
# Test each target independently.
#
-# Defer setting GIT_TR2_PERF until the actual command we want to
+# Defer setting GIT_TRACE2_PERF until the actual command we want to
# test because hidden git and test-tool commands in the test
# harness can contaminate our output.
# Enable "brief" feature which turns off the prefix:
# "<clock> <file>:<line> | <nr_parents> | "
-GIT_TR2_PERF_BRIEF=1 && export GIT_TR2_PERF_BRIEF
+GIT_TRACE2_PERF_BRIEF=1 && export GIT_TRACE2_PERF_BRIEF
# Repeat some of the t0210 tests using the perf target stream instead of
# the normal stream.
test_expect_success 'perf stream, return code 0' '
test_when_finished "rm trace.perf actual expect" &&
- GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 0 &&
+ GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 0 &&
perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
cat >expect <<-EOF &&
d0|main|version|||||$V
test_expect_success 'perf stream, return code 1' '
test_when_finished "rm trace.perf actual expect" &&
- test_must_fail env GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 1 &&
+ test_must_fail env GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 001return 1 &&
perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
cat >expect <<-EOF &&
d0|main|version|||||$V
test_expect_success 'perf stream, error event' '
test_when_finished "rm trace.perf actual expect" &&
- GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 003error "hello world" "this is a test" &&
+ GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 003error "hello world" "this is a test" &&
perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
cat >expect <<-EOF &&
d0|main|version|||||$V
test_expect_success 'perf stream, child processes' '
test_when_finished "rm trace.perf actual expect" &&
- GIT_TR2_PERF="$(pwd)/trace.perf" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
+ GIT_TRACE2_PERF="$(pwd)/trace.perf" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
perl "$TEST_DIRECTORY/t0211/scrub_perf.perl" <trace.perf >actual &&
cat >expect <<-EOF &&
d0|main|version|||||$V
test_cmp expect actual
'
-sane_unset GIT_TR2_PERF_BRIEF
+sane_unset GIT_TRACE2_PERF_BRIEF
# Now test without environment variables and get all Trace2 settings
# from the global config.
. ./test-lib.sh
# Turn off any inherited trace2 settings for this test.
-sane_unset GIT_TR2 GIT_TR2_PERF GIT_TR2_EVENT
-sane_unset GIT_TR2_BARE
-sane_unset GIT_TR2_CONFIG_PARAMS
+sane_unset GIT_TRACE2 GIT_TRACE2_PERF GIT_TRACE2_EVENT
+sane_unset GIT_TRACE2_BARE
+sane_unset GIT_TRACE2_CONFIG_PARAMS
perl -MJSON::PP -e 0 >/dev/null 2>&1 && test_set_prereq JSON_PP
# to whatever filtering that target decides to do).
# Test each target independently.
#
-# Defer setting GIT_TR2_PERF until the actual command we want to
+# Defer setting GIT_TRACE2_PERF until the actual command we want to
# test because hidden git and test-tool commands in the test
# harness can contaminate our output.
test_expect_success JSON_PP 'event stream, error event' '
test_when_finished "rm trace.event actual expect" &&
- GIT_TR2_EVENT="$(pwd)/trace.event" test-tool trace2 003error "hello world" "this is a test" &&
+ GIT_TRACE2_EVENT="$(pwd)/trace.event" test-tool trace2 003error "hello world" "this is a test" &&
perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
sed -e "s/^|//" >expect <<-EOF &&
|VAR1 = {
test_expect_success JSON_PP 'event stream, return code 0' '
test_when_finished "rm trace.event actual expect" &&
- GIT_TR2_EVENT="$(pwd)/trace.event" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
+ GIT_TRACE2_EVENT="$(pwd)/trace.event" test-tool trace2 004child test-tool trace2 004child test-tool trace2 001return 0 &&
perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
sed -e "s/^|//" >expect <<-EOF &&
|VAR1 = {
test_when_finished "rm trace.event actual expect" &&
git config --local t0212.abc 1 &&
git config --local t0212.def "hello world" &&
- GIT_TR2_EVENT="$(pwd)/trace.event" GIT_TR2_CONFIG_PARAMS="t0212.*" test-tool trace2 001return 0 &&
+ GIT_TRACE2_EVENT="$(pwd)/trace.event" GIT_TRACE2_CONFIG_PARAMS="t0212.*" test-tool trace2 001return 0 &&
perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
sed -e "s/^|//" >expect <<-EOF &&
|VAR1 = {
test_expect_success JSON_PP 'basic trace2_data' '
test_when_finished "rm trace.event actual expect" &&
- GIT_TR2_EVENT="$(pwd)/trace.event" test-tool trace2 006data test_category k1 v1 test_category k2 v2 &&
+ GIT_TRACE2_EVENT="$(pwd)/trace.event" test-tool trace2 006data test_category k1 v1 test_category k2 v2 &&
perl "$TEST_DIRECTORY/t0212/parse_events.perl" <trace.event >actual &&
sed -e "s/^|//" >expect <<-EOF &&
|VAR1 = {
# The version of the trace2 event target format that we understand.
# This is reported in the 'version' event in the 'evt' field.
-# It comes from the GIT_TR2_EVENT_VERSION macro in trace2/tr2_tgt_event.c
+# It comes from the GIT_TRACE2_EVENT_VERSION macro in trace2/tr2_tgt_event.c
my $evt_version = '1';
my $show_children = 1;
* list of patterns configured important. For example:
* git config --system trace2.configParams 'core.*,remote.*.url'
* or:
- * GIT_TR2_CONFIG_PARAMS=core.*,remote.*.url"
+ * GIT_TRACE2_CONFIG_PARAMS=core.*,remote.*.url"
*
* Note: this routine does a read-only iteration on the config data
* (using read_early_config()), so it must not be called until enough
#include "cache.h"
#include "trace2/tr2_cmd_name.h"
-#define TR2_ENVVAR_PARENT_NAME "GIT_TR2_PARENT_NAME"
+#define TR2_ENVVAR_PARENT_NAME "GIT_TRACE2_PARENT_NAME"
static struct strbuf tr2cmdname_hierarchy = STRBUF_INIT;
#include "trace2/tr2_tbuf.h"
#include "trace2/tr2_sid.h"
-#define TR2_ENVVAR_PARENT_SID "GIT_TR2_PARENT_SID"
+#define TR2_ENVVAR_PARENT_SID "GIT_TRACE2_PARENT_SID"
static struct strbuf tr2sid_buf = STRBUF_INIT;
static int tr2sid_nr_git_parents;
* The strings in this table are constant and must match the published
* config and environment variable names as described in the documentation.
*
- * We do not define entries for the GIT_TR2_PARENT_* environment
+ * We do not define entries for the GIT_TRACE2_PARENT_* environment
* variables because they are transient and used to pass information
* from parent to child git processes, rather than settings.
*/
/* clang-format off */
static struct tr2_sysenv_entry tr2_sysenv_settings[] = {
- [TR2_SYSENV_CFG_PARAM] = { "GIT_TR2_CONFIG_PARAMS",
+ [TR2_SYSENV_CFG_PARAM] = { "GIT_TRACE2_CONFIG_PARAMS",
"trace2.configparams" },
- [TR2_SYSENV_DST_DEBUG] = { "GIT_TR2_DST_DEBUG",
+ [TR2_SYSENV_DST_DEBUG] = { "GIT_TRACE2_DST_DEBUG",
"trace2.destinationdebug" },
- [TR2_SYSENV_NORMAL] = { "GIT_TR2",
+ [TR2_SYSENV_NORMAL] = { "GIT_TRACE2",
"trace2.normaltarget" },
- [TR2_SYSENV_NORMAL_BRIEF] = { "GIT_TR2_BRIEF",
+ [TR2_SYSENV_NORMAL_BRIEF] = { "GIT_TRACE2_BRIEF",
"trace2.normalbrief" },
- [TR2_SYSENV_EVENT] = { "GIT_TR2_EVENT",
+ [TR2_SYSENV_EVENT] = { "GIT_TRACE2_EVENT",
"trace2.eventtarget" },
- [TR2_SYSENV_EVENT_BRIEF] = { "GIT_TR2_EVENT_BRIEF",
+ [TR2_SYSENV_EVENT_BRIEF] = { "GIT_TRACE2_EVENT_BRIEF",
"trace2.eventbrief" },
- [TR2_SYSENV_EVENT_NESTING] = { "GIT_TR2_EVENT_NESTING",
+ [TR2_SYSENV_EVENT_NESTING] = { "GIT_TRACE2_EVENT_NESTING",
"trace2.eventnesting" },
- [TR2_SYSENV_PERF] = { "GIT_TR2_PERF",
+ [TR2_SYSENV_PERF] = { "GIT_TRACE2_PERF",
"trace2.perftarget" },
- [TR2_SYSENV_PERF_BRIEF] = { "GIT_TR2_PERF_BRIEF",
+ [TR2_SYSENV_PERF_BRIEF] = { "GIT_TRACE2_PERF_BRIEF",
"trace2.perfbrief" },
};
/* clang-format on */
*
* Note that this set does not contain any of the transient
* environment variables used to pass information from parent
- * to child git processes, such "GIT_TR2_PARENT_SID".
+ * to child git processes, such "GIT_TRACE2_PARENT_SID".
*/
enum tr2_sysenv_variable {
TR2_SYSENV_CFG_PARAM = 0,