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>
Jeff Hostetler committed
Apr 15, 2019 at 13:39 UTC
81567caf87c655ba13260bd66d8ec67b8d6e492b
4 files changed
+152
-67
Documentation/config.txt
+2
@@ -422,6 +422,8 @@ include::config/submodule.txt[]
422
423
include::config/tag.txt[]
424
425
+include::config/trace2.txt[]
426
+
427
include::config/transfer.txt[]
428
429
include::config/uploadarchive.txt[]
Documentation/config/trace2.txt
new
+56
@@ -0,0 +1,56 @@
1
+Trace2 config settings are only read from the system and global
2
+config files; repository local and worktree config files and `-c`
3
+command line arguments are not respected.
4
+
5
+trace2.normalTarget::
6
+ This variable controls the normal target destination.
7
+ It may be overridden by the `GIT_TR2` environment variable.
8
+ The following table shows possible values.
9
+
10
+trace2.perfTarget::
11
+ This variable controls the performance target destination.
12
+ It may be overridden by the `GIT_TR2_PERF` environment variable.
13
+ The following table shows possible values.
14
+
15
+trace2.eventTarget::
16
+ This variable controls the event target destination.
17
+ It may be overridden by the `GIT_TR2_EVENT` environment variable.
18
+ The following table shows possible values.
19
++
20
+include::../trace2-target-values.txt[]
21
+
22
+trace2.normalBrief::
23
+ Boolean. When true `time`, `filename`, and `line` fields are
24
+ omitted from normal output. May be overridden by the
25
+ `GIT_TR2_BRIEF` environment variable. Defaults to false.
26
+
27
+trace2.perfBrief::
28
+ Boolean. When true `time`, `filename`, and `line` fields are
29
+ omitted from PERF output. May be overridden by the
30
+ `GIT_TR2_PERF_BRIEF` environment variable. Defaults to false.
31
+
32
+trace2.eventBrief::
33
+ Boolean. When true `time`, `filename`, and `line` fields are
34
+ omitted from event output. May be overridden by the
35
+ `GIT_TR2_EVENT_BRIEF` environment variable. Defaults to false.
36
+
37
+trace2.eventNesting::
38
+ Integer. Specifies desired depth of nested regions in the
39
+ event output. Regions deeper than this value will be
40
+ omitted. May be overridden by the `GIT_TR2_EVENT_NESTING`
41
+ environment variable. Defaults to 2.
42
+
43
+trace2.configParams::
44
+ A comma-separated list of patterns of "important" config
45
+ settings that should be recorded in the trace2 output.
46
+ For example, `core.*,remote.*.url` would cause the trace2
47
+ output to contain events listing each configured remote.
48
+ May be overridden by the `GIT_TR2_CONFIG_PARAMS` environment
49
+ variable. Unset by default.
50
+
51
+trace2.destinationDebug::
52
+ Boolean. When true Git will print error messages when a
53
+ trace target destination cannot be opened for writing.
54
+ By default, these errors are suppressed and tracing is
55
+ silently disabled. May be overridden by the
56
+ `GIT_TR2_DST_DEBUG` environment variable.
Documentation/technical/api-trace2.txt
+84
-67
@@ -22,21 +22,41 @@ Targets are defined using a VTable allowing easy extension to other
22
formats in the future. This might be used to define a binary format,
23
for example.
24
25
+Trace2 is controlled using `trace2.*` config values in the system and
26
+global config files and `GIT_TR2*` environment variables. Trace2 does
27
+not read from repo local or worktree config files or respect `-c`
28
+command line config settings.
29
+
30
== Trace2 Targets
31
32
Trace2 defines the following set of Trace2 Targets.
33
Format details are given in a later section.
34
30
-`GIT_TR2` (NORMAL)::
35
+=== The Normal Format Target
36
+
37
+The normal format target is a tradition printf format and similar
38
+to GIT_TRACE format. This format is enabled with the `GIT_TR`
39
+environment variable or the `trace2.normalTarget` system or global
40
+config setting.
41
+
42
+For example
43
32
- a simple printf format like GIT_TRACE.
33
-+
44
------------
45
$ export GIT_TR2=~/log.normal
46
$ git version
47
git version 2.20.1.155.g426c96fcdb
48
------------
39
-+
49
+
50
+or
51
+
52
+------------
53
+$ git config --global trace2.normalTarget ~/log.normal
54
+$ git version
55
+git version 2.20.1.155.g426c96fcdb
56
+------------
57
+
58
+yields
59
+
60
------------
61
$ cat ~/log.normal
62
12:28:42.620009 common-main.c:38 version 2.20.1.155.g426c96fcdb
@@ -46,17 +66,32 @@ $ cat ~/log.normal
66
12:28:42.621250 trace2/tr2_tgt_normal.c:124 atexit elapsed:0.001265 code:0
67
------------
68
49
-`GIT_TR2_PERF` (PERF)::
69
+=== The Performance Format Target
70
+
71
+The performance format target (PERF) is a column-based format to
72
+replace GIT_TRACE_PERFORMANCE and is suitable for development and
73
+testing, possibly to complement tools like gprof. This format is
74
+enabled with the `GIT_TR2_PERF` environment variable or the
75
+`trace2.perfTarget` system or global config setting.
76
+
77
+For example
78
51
- a column-based format to replace GIT_TRACE_PERFORMANCE suitable for
52
- development and testing, possibly to complement tools like gprof.
53
-+
79
------------
80
$ export GIT_TR2_PERF=~/log.perf
81
$ git version
82
git version 2.20.1.155.g426c96fcdb
83
------------
59
-+
84
+
85
+or
86
+
87
+------------
88
+$ git config --global trace2.perfTarget ~/log.perf
89
+$ git version
90
+git version 2.20.1.155.g426c96fcdb
91
+------------
92
+
93
+yields
94
+
95
------------
96
$ cat ~/log.perf
97
12:28:42.620675 common-main.c:38 | d0 | main | version | | | | | 2.20.1.155.g426c96fcdb
@@ -66,56 +101,46 @@ $ cat ~/log.perf
101
12:28:42.621259 trace2/tr2_tgt_perf.c:211 | d0 | main | atexit | | 0.001265 | | | code:0
102
------------
103
69
-`GIT_TR2_EVENT` (EVENT)::
104
+=== The Event Format Target
105
+
106
+The event format target is a JSON-based format of event data suitable
107
+for telemetry analysis. This format is enabled with the `GIT_TR2_EVENT`
108
+environment variable or the `trace2.eventTarget` system or global config
109
+setting.
110
+
111
+For example
112
71
- a JSON-based format of event data suitable for telemetry analysis.
72
-+
113
------------
114
$ export GIT_TR2_EVENT=~/log.event
115
$ git version
116
git version 2.20.1.155.g426c96fcdb
117
------------
78
-+
79
-------------
80
-$ cat ~/log.event
81
-{"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"}
82
-{"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"]}
83
-{"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"}
84
-{"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}
85
-{"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}
86
-------------
87
-
88
-== Enabling a Target
89
-
90
-A Trace2 Target is enabled when the corresponding environment variable
91
-(`GIT_TR2`, `GIT_TR2_PERF`, or `GIT_TR2_EVENT`) is set. The following
92
-values are recognized.
93
-
94
-`0`::
95
-`false`::
96
-
97
- Disables the target.
118
99
-`1`::
100
-`true`::
119
+or
120
102
- Enables the target and writes stream to `STDERR`.
103
-
104
-`[2-9]`::
121
+------------
122
+$ git config --global trace2.eventTarget ~/log.event
123
+$ git version
124
+git version 2.20.1.155.g426c96fcdb
125
+------------
126
106
- Enables the target and writes to the already opened file descriptor.
127
+yields
128
108
-`<absolute-pathname>`::
129
+------------
130
+$ cat ~/log.event
131
+{"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"}
132
+{"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"]}
133
+{"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"}
134
+{"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}
135
+{"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}
136
+------------
137
110
- Enables the target, opens and writes to the file in append mode.
138
+=== Enabling a Target
139
112
-`af_unix:[<socket_type>:]<absolute-pathname>`::
140
+To enable a target, set the corresponding environment variable or
141
+system or global config value to one of the following:
142
114
- Enables the target, opens and writes to a Unix Domain Socket
115
- (on platforms that support them).
116
-+
117
-Socket type can be either `stream` or `dgram`. If the socket type is
118
-omitted, Git will try both.
143
+include::../trace2-target-values.txt[]
144
145
== Trace2 API
146
@@ -243,15 +268,16 @@ significantly affects program performance or behavior, such as
268
Emits a "def_param" messages for "important" configuration
269
settings.
270
+
246
-The environment variable `GIT_TR2_CONFIG_PARAMS` can be set to a
271
+The environment variable `GIT_TR2_CONFIG_PARAMS` or the `trace2.configParams`
272
+config value can be set to a
273
list of patterns of important configuration settings, for example:
274
`core.*,remote.*.url`. This function will iterate over all config
275
settings and emit a "def_param" message for each match.
276
277
`void trace2_cmd_set_config(const char *key, const char *value)`::
278
253
- Emits a "def_param" message for a specific configuration
254
- setting IFF it matches the `GIT_TR2_CONFIG_PARAMS` pattern.
279
+ Emits a "def_param" message for a new or updated key/value
280
+ pair IF `key` is considered important.
281
+
282
This is used to hook into `git_config_set()` and catch any
283
configuration changes and update a value previously reported by
@@ -418,9 +444,6 @@ recursive tree walk.
444
445
=== NORMAL Format
446
421
-NORMAL format is enabled when the `GIT_TR2` environment variable is
422
-set.
423
-
447
Events are written as lines of the form:
448
449
------------
@@ -437,8 +460,8 @@ Events are written as lines of the form:
460
Note that this may contain embedded LF or CRLF characters that are
461
not escaped, so the event may spill across multiple lines.
462
440
-If `GIT_TR2_BRIEF` is true, the `time`, `filename`, and `line` fields
441
-are omitted.
463
+If `GIT_TR2_BRIEF` or `trace2.normalBrief` is true, the `time`, `filename`,
464
+and `line` fields are omitted.
465
466
This target is intended to be more of a summary (like GIT_TRACE) and
467
less detailed than the other targets. It ignores thread, region, and
@@ -446,9 +469,6 @@ data messages, for example.
469
470
=== PERF Format
471
449
-PERF format is enabled when the `GIT_TR2_PERF` environment variable
450
-is set.
451
-
472
Events are written as lines of the form:
473
474
------------
@@ -508,8 +528,8 @@ This field is in anticipation of in-proc submodules in the future.
528
15:33:33.532712 wt-status.c:2331 | d0 | main | region_leave | r1 | 0.127568 | 0.001504 | status | label:print
529
------------
530
511
-If `GIT_TR2_PERF_BRIEF` is true, the `time`, `file`, and `line`
512
-fields are omitted.
531
+If `GIT_TR2_PERF_BRIEF` or `trace2.perfBrief` is true, the `time`, `file`,
532
+and `line` fields are omitted.
533
534
------------
535
d0 | main | region_leave | r1 | 0.011717 | 0.009122 | index | label:preload
@@ -520,9 +540,6 @@ during development and is quite noisy.
540
541
=== EVENT Format
542
523
-EVENT format is enabled when the `GIT_TR2_EVENT` environment
524
-variable is set.
525
-
543
Each event is a JSON-object containing multiple key/value pairs
544
written as a single line and followed by a LF.
545
@@ -540,7 +557,7 @@ The following key/value pairs are common to all events:
557
------------
558
{
559
"event":"version",
543
- "sid":"20190408T191827.272759Z-H9b68c35f-P011764",
560
+ "sid":"20190408T191827.272759Z-H9b68c35f-P00003510",
561
"thread":"main",
562
"time":"2019-04-08T19:18:27.282761Z",
563
"file":"common-main.c",
@@ -576,9 +593,9 @@ The following key/value pairs are common to all events:
593
`"repo":<repo-id>`::
594
when present, is the integer repo-id as described previously.
595
579
-If `GIT_TR2_EVENT_BRIEF` is true, the `file` and `line` fields are omitted
580
-from all events and the `time` field is only present on the "start" and
581
-"atexit" events.
596
+If `GIT_TR2_EVENT_BRIEF` or `trace2.eventBrief` is true, the `file`
597
+and `line` fields are omitted from all events and the `time` field is
598
+only present on the "start" and "atexit" events.
599
600
==== Event-Specific Key/Value Pairs
601
@@ -889,7 +906,7 @@ visited.
906
The `category` field may be used in a future enhancement to
907
do category-based filtering.
908
+
892
-The `GIT_TR2_EVENT_NESTING` environment variable can be used to
909
+`GIT_TR2_EVENT_NESTING` or `trace2.eventNesting` can be used to
910
filter deeply nested regions and data events. It defaults to "2".
911
912
`"region_leave"`::
Documentation/trace2-target-values.txt
new
+10
@@ -0,0 +1,10 @@
1
+--
2
+* `0` or `false` - Disables the target.
3
+* `1` or `true` - Writes to `STDERR`.
4
+* `[2-9]` - Writes to the already opened file descriptor.
5
+* `<absolute-pathname>` - Writes to the file in append mode.
6
+* `af_unix:[<socket_type>:]<absolute-pathname>` - Write to a
7
+Unix DomainSocket (on platforms that support them). Socket
8
+type can be either `stream` or `dgram`; if omitted Git will
9
+try both.
10
+--