trace2: update docs to describe system/global config settings
Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jeff Hostetler
Junio C Hamano
parent
08881b9a4c
commit
81567caf87
@ -422,6 +422,8 @@ include::config/submodule.txt[]
|
||||
|
||||
include::config/tag.txt[]
|
||||
|
||||
include::config/trace2.txt[]
|
||||
|
||||
include::config/transfer.txt[]
|
||||
|
||||
include::config/uploadarchive.txt[]
|
||||
|
||||
56
Documentation/config/trace2.txt
Normal file
56
Documentation/config/trace2.txt
Normal file
@ -0,0 +1,56 @@
|
||||
Trace2 config settings are only read from the system and global
|
||||
config files; repository local and worktree config files and `-c`
|
||||
command line arguments are not respected.
|
||||
|
||||
trace2.normalTarget::
|
||||
This variable controls the normal target destination.
|
||||
It may be overridden by the `GIT_TR2` 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.
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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`
|
||||
environment variable. Defaults to 2.
|
||||
|
||||
trace2.configParams::
|
||||
A comma-separated list of patterns of "important" config
|
||||
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
|
||||
variable. Unset by default.
|
||||
|
||||
trace2.destinationDebug::
|
||||
Boolean. When true Git will print error messages when a
|
||||
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.
|
||||
@ -22,21 +22,41 @@ 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_TR2*` 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.
|
||||
|
||||
`GIT_TR2` (NORMAL)::
|
||||
=== 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_TR`
|
||||
environment variable or the `trace2.normalTarget` system or global
|
||||
config setting.
|
||||
|
||||
For example
|
||||
|
||||
a simple printf format like GIT_TRACE.
|
||||
+
|
||||
------------
|
||||
$ export GIT_TR2=~/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
|
||||
@ -46,17 +66,32 @@ $ cat ~/log.normal
|
||||
12:28:42.621250 trace2/tr2_tgt_normal.c:124 atexit elapsed:0.001265 code:0
|
||||
------------
|
||||
|
||||
`GIT_TR2_PERF` (PERF)::
|
||||
=== 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_TR2_PERF` environment variable or the
|
||||
`trace2.perfTarget` system or global config setting.
|
||||
|
||||
For example
|
||||
|
||||
a column-based format to replace GIT_TRACE_PERFORMANCE suitable for
|
||||
development and testing, possibly to complement tools like gprof.
|
||||
+
|
||||
------------
|
||||
$ export GIT_TR2_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
|
||||
@ -66,56 +101,46 @@ $ cat ~/log.perf
|
||||
12:28:42.621259 trace2/tr2_tgt_perf.c:211 | d0 | main | atexit | | 0.001265 | | | code:0
|
||||
------------
|
||||
|
||||
`GIT_TR2_EVENT` (EVENT)::
|
||||
=== 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`
|
||||
environment variable or the `trace2.eventTarget` system or global config
|
||||
setting.
|
||||
|
||||
For example
|
||||
|
||||
a JSON-based format of event data suitable for telemetry analysis.
|
||||
+
|
||||
------------
|
||||
$ export GIT_TR2_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-P028492","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-P028492","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-P028492","thread":"main","time":"2019-01-16T17:28:42.621122Z","file":"git.c","line":432,"name":"version","hierarchy":"version"}
|
||||
{"event":"exit","sid":"20190408T191610.507018Z-H9b68c35f-P028492","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-P028492","thread":"main","time":"2019-01-16T17:28:42.621268Z","file":"trace2/tr2_tgt_event.c","line":163,"t_abs":0.001265,"code":0}
|
||||
{"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
|
||||
=== Enabling a Target
|
||||
|
||||
A Trace2 Target is enabled when the corresponding environment variable
|
||||
(`GIT_TR2`, `GIT_TR2_PERF`, or `GIT_TR2_EVENT`) is set. The following
|
||||
values are recognized.
|
||||
To enable a target, set the corresponding environment variable or
|
||||
system or global config value to one of the following:
|
||||
|
||||
`0`::
|
||||
`false`::
|
||||
|
||||
Disables the target.
|
||||
|
||||
`1`::
|
||||
`true`::
|
||||
|
||||
Enables the target and writes stream to `STDERR`.
|
||||
|
||||
`[2-9]`::
|
||||
|
||||
Enables the target and writes to the already opened file descriptor.
|
||||
|
||||
`<absolute-pathname>`::
|
||||
|
||||
Enables the target, opens and writes to the file in append mode.
|
||||
|
||||
`af_unix:[<socket_type>:]<absolute-pathname>`::
|
||||
|
||||
Enables the target, opens and writes to a Unix Domain Socket
|
||||
(on platforms that support them).
|
||||
+
|
||||
Socket type can be either `stream` or `dgram`. If the socket type is
|
||||
omitted, Git will try both.
|
||||
include::../trace2-target-values.txt[]
|
||||
|
||||
== Trace2 API
|
||||
|
||||
@ -243,15 +268,16 @@ significantly affects program performance or behavior, such as
|
||||
Emits a "def_param" messages for "important" configuration
|
||||
settings.
|
||||
+
|
||||
The environment variable `GIT_TR2_CONFIG_PARAMS` can be set to a
|
||||
The environment variable `GIT_TR2_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
|
||||
settings and emit a "def_param" message for each match.
|
||||
|
||||
`void trace2_cmd_set_config(const char *key, const char *value)`::
|
||||
|
||||
Emits a "def_param" message for a specific configuration
|
||||
setting IFF it matches the `GIT_TR2_CONFIG_PARAMS` pattern.
|
||||
Emits a "def_param" message for a new or updated key/value
|
||||
pair IF `key` is considered important.
|
||||
+
|
||||
This is used to hook into `git_config_set()` and catch any
|
||||
configuration changes and update a value previously reported by
|
||||
@ -418,9 +444,6 @@ recursive tree walk.
|
||||
|
||||
=== NORMAL Format
|
||||
|
||||
NORMAL format is enabled when the `GIT_TR2` environment variable is
|
||||
set.
|
||||
|
||||
Events are written as lines of the form:
|
||||
|
||||
------------
|
||||
@ -437,8 +460,8 @@ Events are written as lines of the form:
|
||||
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` is true, the `time`, `filename`, and `line` fields
|
||||
are omitted.
|
||||
If `GIT_TR2_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
|
||||
@ -446,9 +469,6 @@ data messages, for example.
|
||||
|
||||
=== PERF Format
|
||||
|
||||
PERF format is enabled when the `GIT_TR2_PERF` environment variable
|
||||
is set.
|
||||
|
||||
Events are written as lines of the form:
|
||||
|
||||
------------
|
||||
@ -508,8 +528,8 @@ This field is in anticipation of in-proc submodules in the future.
|
||||
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` is true, the `time`, `file`, and `line`
|
||||
fields are omitted.
|
||||
If `GIT_TR2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`,
|
||||
and `line` fields are omitted.
|
||||
|
||||
------------
|
||||
d0 | main | region_leave | r1 | 0.011717 | 0.009122 | index | label:preload
|
||||
@ -520,9 +540,6 @@ during development and is quite noisy.
|
||||
|
||||
=== EVENT Format
|
||||
|
||||
EVENT format is enabled when the `GIT_TR2_EVENT` environment
|
||||
variable is set.
|
||||
|
||||
Each event is a JSON-object containing multiple key/value pairs
|
||||
written as a single line and followed by a LF.
|
||||
|
||||
@ -540,7 +557,7 @@ The following key/value pairs are common to all events:
|
||||
------------
|
||||
{
|
||||
"event":"version",
|
||||
"sid":"20190408T191827.272759Z-H9b68c35f-P011764",
|
||||
"sid":"20190408T191827.272759Z-H9b68c35f-P00003510",
|
||||
"thread":"main",
|
||||
"time":"2019-04-08T19:18:27.282761Z",
|
||||
"file":"common-main.c",
|
||||
@ -576,9 +593,9 @@ The following key/value pairs are common to all events:
|
||||
`"repo":<repo-id>`::
|
||||
when present, is the integer repo-id as described previously.
|
||||
|
||||
If `GIT_TR2_EVENT_BRIEF` 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.
|
||||
If `GIT_TR2_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.
|
||||
|
||||
==== Event-Specific Key/Value Pairs
|
||||
|
||||
@ -889,7 +906,7 @@ visited.
|
||||
The `category` field may be used in a future enhancement to
|
||||
do category-based filtering.
|
||||
+
|
||||
The `GIT_TR2_EVENT_NESTING` environment variable can be used to
|
||||
`GIT_TR2_EVENT_NESTING` or `trace2.eventNesting` can be used to
|
||||
filter deeply nested regions and data events. It defaults to "2".
|
||||
|
||||
`"region_leave"`::
|
||||
|
||||
10
Documentation/trace2-target-values.txt
Normal file
10
Documentation/trace2-target-values.txt
Normal file
@ -0,0 +1,10 @@
|
||||
--
|
||||
* `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.
|
||||
* `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.
|
||||
--
|
||||
Loading…
Reference in New Issue
Block a user