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>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d87846faa6c3ffad7cba97fe7348ef97e0112899..7e2a6f61f593921450c311b05269a3555baa97ad 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -422,6 +422,8 @@ include::config/submodule.txt[]
 
 include::config/tag.txt[]
 
 
 include::config/tag.txt[]
 

+include::config/trace2.txt[]
+

 include::config/transfer.txt[]
 
 include::config/uploadarchive.txt[]
 include::config/transfer.txt[]
 
 include::config/uploadarchive.txt[]

diff --git a/Documentation/config/trace2.txt b/Documentation/config/trace2.txt
new file mode 100644 (file)
index 0000000..a5f409c
--- /dev/null
+++ b/Documentation/config/trace2.txt
@@ -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.

diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
index 43adbf00eb9096c09ebb4a2ea16cfb0ff2fe7fbd..8b6a5e6d4b98564a337544a12230c5921343ad60 100644 (file)
--- a/Documentation/technical/api-trace2.txt
+++ b/Documentation/technical/api-trace2.txt
@@ -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.
 
 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.
 
 == 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
 ------------
 ------------
 $ 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
 ------------
 $ 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
 ------------
 
 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
 ------------
 ------------
 $ 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
 ------------
 $ 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
 ------------
 
 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
 ------------
 ------------
 $ export GIT_TR2_EVENT=~/log.event
 $ git version
 git version 2.20.1.155.g426c96fcdb
 ------------

-+
-------------
-$ 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}
-------------
-
-== 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.
-
-`0`::
-`false`::
-
-       Disables the target.

 
 

-`1`::
-`true`::
+or

 
 

-       Enables the target and writes stream to `STDERR`.
-
-`[2-9]`::
+------------
+$ git config --global trace2.eventTarget ~/log.event
+$ git version
+git version 2.20.1.155.g426c96fcdb
+------------

 
 

-       Enables the target and writes to the already opened file descriptor.
+yields

 
 

-`<absolute-pathname>`::
+------------
+$ 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}
+------------

 
 

-       Enables the target, opens and writes to the file in append mode.
+=== Enabling a Target

 
 

-`af_unix:[<socket_type>:]<absolute-pathname>`::
+To enable a target, set the corresponding environment variable or
+system or global config value to one of the following:

 
 

-       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
 
 
 == Trace2 API
 


@@ -243,15 +268,16 @@ significantly affects program performance or behavior, such as
        Emits a "def_param" messages for "important" configuration
        settings.
 +
        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)`::
 
 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
 +
 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
 

-NORMAL format is enabled when the `GIT_TR2` environment variable is
-set.
-

 Events are written as lines of the form:
 
 ------------
 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.
 
 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
 
 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
 

-PERF format is enabled when the `GIT_TR2_PERF` environment variable
-is set.
-

 Events are written as lines of the form:
 
 ------------
 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
 ------------
 
 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
 
 ------------
 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
 

-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.
 
 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",
 ------------
 {
        "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",
        "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.
 
 `"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
 
 
 ==== 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 `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"`::
 filter deeply nested regions and data events.  It defaults to "2".
 
 `"region_leave"`::

diff --git a/Documentation/trace2-target-values.txt b/Documentation/trace2-target-values.txt
new file mode 100644 (file)
index 0000000..27d3c64
--- /dev/null
+++ b/Documentation/trace2-target-values.txt
@@ -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.
+--