Merge branch 'en/merge-recursive-directory-rename-fixes'

[thirdparty/git.git] / Documentation / technical / api-trace2.txt

diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
index 71eb081fed25a7314a822087056a6c5b9a72d944..a045dbe422ff000fa29216028a1cfc7c4b071515 100644 (file)
--- a/Documentation/technical/api-trace2.txt
+++ b/Documentation/technical/api-trace2.txt
@@ -128,7 +128,7 @@ yields
 
 ------------
 $ 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":"version","sid":"sid":"20190408T191610.507018Z-H9b68c35f-P000059a8","thread":"main","time":"2019-01-16T17:28:42.620713Z","file":"common-main.c","line":38,"evt":"2","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}
@@ -142,10 +142,9 @@ system or global config value to one of the following:
 
 include::../trace2-target-values.txt[]
 
-If the target already exists and is a directory, the traces will be
-written to files (one per process) underneath the given directory. They
-will be named according to the last component of the SID (optionally
-followed by a counter to avoid filename collisions).
+When trace files are written to a target directory, they will be named according
+to the last component of the SID (optionally followed by a counter to avoid
+filename collisions).
 
 == Trace2 API
 
@@ -605,17 +604,35 @@ only present on the "start" and "atexit" events.
 ==== Event-Specific Key/Value Pairs
 
 `"version"`::
-       This event gives the version of the executable and the EVENT format.
+       This event gives the version of the executable and the EVENT format. It
+       should always be the first event in a trace session. The EVENT format
+       version will be incremented if new event types are added, if existing
+       fields are removed, or if there are significant changes in
+       interpretation of existing events or fields. Smaller changes, such as
+       adding a new field to an existing event, will not require an increment
+       to the EVENT format version.
 +
 ------------
 {
        "event":"version",
        ...
-       "evt":"1",                     # EVENT format version
+       "evt":"2",                     # EVENT format version
        "exe":"2.20.1.155.g426c96fcdb" # git version
 }
 ------------
 
+`"discard"`::
+       This event is written to the git-trace2-discard sentinel file if there
+       are too many files in the target trace directory (see the
+       trace2.maxFiles config option).
++
+------------
+{
+       "event":"discard",
+       ...
+}
+------------
+
 `"start"`::
        This event contains the complete argv received by main().
 +