Git - api-trace2 Documentation (2024)

This event gives the version of the executable and the EVENT format. Itshould always be the first event in a trace session. The EVENT formatversion will be incremented if new event types are added, if existingfields are removed, or if there are significant changes ininterpretation of existing events or fields. Smaller changes, such asadding a new field to an existing event, will not require an incrementto the EVENT format version.

{"event":"version",..."evt":"3", # EVENT format version"exe":"2.20.1.155.g426c96fcdb" # git version}

This event is written to the git-trace2-discard sentinel file if thereare too many files in the target trace directory (see thetrace2.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 duringfinal shutdown. It should be the last event emitted by theprocess.

(The elapsed time reported here is greater than the time reported inthe "exit" event because it runs after all other atexit tasks havecompleted.)

{"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 usersignal. Depending on the platform, the signal event mayprevent 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 stringallows post-processors to group errors by type without worryingabout specific error arguments.

This event contains the discovered full path of the gitexecutable (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 earliergenerations of parents) of the current process, in an array ordered fromnearest parent to furthest great-grandparent. It may not be implementedon all platforms.

{"event":"cmd_ancestry",..."ancestry":["bash","tmux: server","systemd"]}

This event contains the command name for this git processand 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 thecommand. When a canonical name is not available, one ofthese 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. Thisevent 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 performancecharacteristics 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 bespawned.

{"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 thecorresponding child_exit event.

The "child_class" field is a rough classification, such as "editor","pager", "transport/*", and "hook". Unclassified children are classifiedwith "?".

This event is generated after the current process has returnedfrom the waitpid() and collected the exit information from thechild.

{"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 tothe current/spawning process, so the child’s PID is reported here asa hint for post-processing. (But it is only a hint because the childprocess may be a shell script which doesn’t have a session-id.)

Note that the t_rel field contains the observed run time in secondsfor the child process (starting before the fork/exec/spawn andstopping after the waitpid() and includes OS process creation overhead).So this time will be slightly larger than the atexit time reported bythe child process itself.

This event is generated after the current process has starteda 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 tothe current/spawning process, so the child’s PID is reported here asa hint for post-processing. (But it is only a hint because the childprocess may be a shell script which doesn’t have a session-id.)

This event is generated after the child is started in the backgroundand given a little time to boot up and start working. If the childstarts 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 fieldwill have the value "timeout".If the child starts but the parent is unable to probe it, the fieldwill have the value "error".

After the parent process emits this event, it will release all of itshandles to the child process and treat the child as a backgrounddaemon. 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 secondswhen the parent released the child process into the background.The child is assumed to be a long-running daemon process and mayoutlive the parent process. So the parent’s child event times shouldnot 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 controlreturns 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 isgenerated from within the new thread’s thread-proc (becauseit 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 generatedfrom 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 configsetting, 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 rootof the worktree.

{"event":"def_repo",..."repo":1,"worktree":"/Users/jeffhost/work/gfw"}

As stated earlier, the repo-id is currently always 1, so there willonly be one def_repo event. Later, if in-proc submodules aresupported, a def_repo event should be emitted for each submodulevisited.

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 todo category-based filtering.

GIT_TRACE2_EVENT_NESTING or trace2.eventNesting can be used tofilter 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-localkey/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 stringcontaining 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 wasrunning in the thread. This event is generated when a threadexits 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 wasrunning aggregated across all threads. This event is generatedwhen 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 thatrequested 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 valuereported here is the sum across all threads.

{"event":"counter",..."category":"my_category","name":"my_counter","count":23}