Git - api-trace2 Documentation (original) (raw)
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":"4", # EVENT format version "exe":"2.20.1.155.g426c96fcdb" # git version }
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":"too_many_files", ... }
This event contains the complete argv received by main().
{ "event":"start", ... "t_abs":0.001227, # elapsed time in seconds "argv":["git","version"] }
This event is emitted when git calls exit().
{ "event":"exit", ... "t_abs":0.001227, # elapsed time in seconds "code":0 # exit code }
This event is emitted by the Trace2 atexit routine during final shutdown. It should be the last event emitted by the process.
(The elapsed time reported here is greater than the time reported in the "exit" event because it runs after all other atexit tasks have completed.)
{ "event":"atexit", ... "t_abs":0.001227, # elapsed time in seconds "code":0 # exit code }
This event is emitted when the program is terminated by a user signal. Depending on the platform, the signal event may prevent the "atexit" event from being generated.
{ "event":"signal", ... "t_abs":0.001227, # elapsed time in seconds "signo":13 # SIGTERM, SIGINT, etc. }
This event is emitted when one of the BUG(), bug(), error(),die(), warning(), or usage() functions are called.
{ "event":"error", ... "msg":"invalid option: --cahced", # formatted error message "fmt":"invalid option: %s" # error format string }
The error event may be emitted more than once. The format string allows post-processors to group errors by type without worrying about specific error arguments.
This event contains the discovered full path of the git executable (on platforms that are configured to resolve it).
{ "event":"cmd_path", ... "path":"C:/work/gfw/git.exe" }
This event contains the text command name for the parent (and earlier generations of parents) of the current process, in an array ordered from nearest parent to furthest great-grandparent. It may not be implemented on all platforms.
{ "event":"cmd_ancestry", ... "ancestry":["bash","tmux: server","systemd"] }
This event contains the command name for this git process and the hierarchy of commands from parent git processes.
{ "event":"cmd_name", ... "name":"pack-objects", "hierarchy":"push/pack-objects" }
Normally, the "name" field contains the canonical name of the command. When a canonical name is not available, one of these special values are used:
"query" # "git --html-path" "run_dashed" # when "git foo" tries to run "git-foo" "run_shell_alias" # alias expansion to a shell command "run_git_alias" # alias expansion to a git command "usage" # usage error
This event, when present, describes the command variant. This event may be emitted more than once.
{ "event":"cmd_mode", ... "name":"branch" }
The "name" field is an arbitrary string to describe the command mode. For example, checkout can checkout a branch or an individual file. And these variations typically have different performance characteristics that are not comparable.
This event is present when an alias is expanded.
{ "event":"alias", ... "alias":"l", # registered alias "argv":["log","--graph"] # alias expansion }
This event describes a child process that is about to be spawned.
{ "event":"child_start", ... "child_id":2, "child_class":"?", "use_shell":false, "argv":["git","rev-list","--objects","--stdin","--not","--all","--quiet"]
"hook_name":"<hook_name>" # present when child_class is "hook"
"cd":"<path>" # present when cd is required}
The "child_id" field can be used to match this child_start with the corresponding child_exit event.
The "child_class" field is a rough classification, such as "editor", "pager", "transport/*", and "hook". Unclassified children are classified with "?".
This event is generated after the current process has returned from the waitpid() and collected the exit information from the child.
{ "event":"child_exit", ... "child_id":2, "pid":14708, # child PID "code":0, # child exit-code "t_rel":0.110605 # observed run-time of child process }
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 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 stopping after the waitpid() and includes OS process creation overhead). So this time will be slightly larger than the atexit time reported by the child process itself.
This event is generated after the current process has started a background process and released all handles to it.
{ "event":"child_ready", ... "child_id":2, "pid":14708, # child PID "ready":"ready", # child ready state "t_rel":0.110605 # observed run-time of child process }
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 process may be a shell script which doesn’t have a session-id.)
This event is generated after the child is started in the background and given a little time to boot up and start working. If the child starts up normally while the parent is still waiting, the "ready" field will have the value "ready". If the child is too slow to start and the parent times out, the field will have the value "timeout". If the child starts but the parent is unable to probe it, the field will have the value "error".
After the parent process emits this event, it will release all of its handles to the child process and treat the child as a background daemon. So even if the child does eventually finish booting up, the parent will not emit an updated event.
Note that the t_rel field contains the observed run time in seconds when the parent released the child process into the background. The child is assumed to be a long-running daemon process and may outlive the parent process. So the parent’s child event times should not be compared to the child’s atexit times.
This event is generated before git attempts to exec()another command rather than starting a child process.
{ "event":"exec", ... "exec_id":0, "exe":"git", "argv":["foo", "bar"] }
The "exec_id" field is a command-unique id and is only useful if theexec() fails and a corresponding exec_result event is generated.
This event is generated if the exec() fails and control returns to the current git command.
{ "event":"exec_result", ... "exec_id":0, "code":1 # error code (errno) from exec() }
This event is generated when a thread is started. It is generated from within the new thread’s thread-proc (because it needs to access data in the thread’s thread-local storage).
{ "event":"thread_start", ... "thread":"th02:preload_thread" # thread name }
This event is generated when a thread exits. It is generated from within the thread’s thread-proc.
{ "event":"thread_exit", ... "thread":"th02:preload_thread", # thread name "t_rel":0.007328 # thread elapsed time }
This event is generated to log a global parameter, such as a config setting, command-line flag, or environment variable.
{ "event":"def_param", ... "scope":"global", "param":"core.abbrev", "value":"7" }
This event defines a repo-id and associates it with the root of the worktree.
{ "event":"def_repo", ... "repo":1, "worktree":"/Users/jeffhost/work/gfw" }
As stated earlier, the repo-id is currently always 1, so there will only be one def_repo event. Later, if in-proc submodules are supported, a def_repo event should be emitted for each submodule visited.
This event is generated when entering a region.
{ "event":"region_enter", ... "repo":1, # optional "nesting":1, # current region stack depth "category":"index", # optional "label":"do_read_index", # optional "msg":".git/index" # optional }
The category field may be used in a future enhancement to do category-based filtering.
GIT_TRACE2_EVENT_NESTING or trace2.eventNesting can be used to filter deeply nested regions and data events. It defaults to "2".
This event is generated when leaving a region.
{ "event":"region_leave", ... "repo":1, # optional "t_rel":0.002876, # time spent in region in seconds "nesting":1, # region stack depth "category":"index", # optional "label":"do_read_index", # optional "msg":".git/index" # optional }
This event is generated to log a thread- and region-local key/value pair.
{ "event":"data", ... "repo":1, # optional "t_abs":0.024107, # absolute elapsed time "t_rel":0.001031, # elapsed time in region/thread "nesting":2, # region stack depth "category":"index", "key":"read/cache_nr", "value":"3552" }
The "value" field may be an integer or a string.
This event is generated to log a pre-formatted JSON string containing structured data.
{ "event":"data_json", ... "repo":1, # optional "t_abs":0.015905, "t_rel":0.015905, "nesting":1, "category":"process", "key":"windows/ancestry", "value":["bash.exe","bash.exe"] }
This event logs the amount of time that a stopwatch timer was running in the thread. This event is generated when a thread exits for timers that requested per-thread events.
{ "event":"th_timer", ... "category":"my_category", "name":"my_timer", "intervals":5, # number of time it was started/stopped "t_total":0.052741, # total time in seconds it was running "t_min":0.010061, # shortest interval "t_max":0.011648 # longest interval }
This event logs the amount of time that a stopwatch timer was running aggregated across all threads. This event is generated when the process exits.
{ "event":"timer", ... "category":"my_category", "name":"my_timer", "intervals":5, # number of time it was started/stopped "t_total":0.052741, # total time in seconds it was running "t_min":0.010061, # shortest interval "t_max":0.011648 # longest interval }
This event logs the value of a counter variable in a thread. This event is generated when a thread exits for counters that requested per-thread events.
{ "event":"th_counter", ... "category":"my_category", "name":"my_counter", "count":23 }
This event logs the value of a counter variable across all threads. This event is generated when the process exits. The total value reported here is the sum across all threads.
{ "event":"counter", ... "category":"my_category", "name":"my_counter", "count":23 }
This event logs a human-readable message with no particular formatting guidelines.
{ "event":"printf", ... "t_abs":0.015905, # elapsed time in seconds "msg":"Hello world" # optional }