diff options
Diffstat (limited to 'Documentation/technical/api-trace2.txt')
| -rw-r--r-- | Documentation/technical/api-trace2.txt | 45 |
1 files changed, 31 insertions, 14 deletions
diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index 71eb081fed..17490b528c 100644 --- 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 @@ -179,7 +178,7 @@ describe the simplified forms. == Public API -All Trace2 API functions send a messsage to all of the active +All Trace2 API functions send a message to all of the active Trace2 Targets. This section describes the set of available messages. @@ -378,7 +377,7 @@ of `pthread_create()`. and the thread elapsed time. + This function must be called by the thread-proc before it returns -(so that the coorect TLS data is used and cleaned up. It should +(so that the correct TLS data is used and cleaned up). It should not be called by the caller of `pthread_join()`. === Region and Data Messages @@ -407,7 +406,7 @@ The `label` field is an arbitrary label used to describe the activity being started, such as "read_recursive" or "do_read_index". + The `repo` field, if set, will be used to get the "repo-id", so that -recursive oerations can be attributed to the correct repository. +recursive operations can be attributed to the correct repository. `void trace2_region_leave(const char *category, const char *label, const struct repository *repo)`:: @@ -422,7 +421,7 @@ This function pops the region nesting stack on the current thread and reports the elapsed time of the stack frame. + The `category`, `label`, and `repo` fields are the same as above. -The `category` and `label` do not need to match the correpsonding +The `category` and `label` do not need to match the corresponding "region_enter" message, but it makes the data stream easier to understand. @@ -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(). + @@ -799,7 +816,7 @@ with "?". Note that the session-id of the child process is not available to the current/spawning process, so the child's PID is reported here as a hint for post-processing. (But it is only a hint because the child -proces may be a shell script which doesn't have a session-id.) +process may be a shell script which doesn't have a session-id.) + Note that the `t_rel` field contains the observed run time in seconds for the child process (starting before the fork/exec/spawn and @@ -1159,7 +1176,7 @@ d0 | main | atexit | | 0.028809 | | + Regions may be nested. This causes messages to be indented in the PERF target, for example. -Elapsed times are relative to the start of the correpsonding nesting +Elapsed times are relative to the start of the corresponding nesting level as expected. For example, if we add region message to: + ---------------- @@ -1354,7 +1371,7 @@ d0 | main | atexit | | 0.030027 | | In this example, the preload region took 0.009122 seconds. The 7 threads took between 0.006069 and 0.008947 seconds to work on their portion of the index. Thread "th01" worked on 508 items at offset 0. Thread "th02" -worked on 508 items at offset 2032. Thread "th04" worked on 508 itemts +worked on 508 items at offset 2032. Thread "th04" worked on 508 items at offset 508. + This example also shows that thread names are assigned in a racy manner |