]> git.ipfire.org Git - thirdparty/git.git/blame - trace2.h
reftable: read reftable files
[thirdparty/git.git] / trace2.h
CommitLineData
ee4512ed
JH
1#ifndef TRACE2_H
2#define TRACE2_H
3
6c51cb52
HW
4/**
5 * The Trace2 API can be used to print debug, performance, and telemetry
6 * information to stderr or a file. The Trace2 feature is inactive unless
7 * explicitly enabled by enabling one or more Trace2 Targets.
8 *
9 * The Trace2 API is intended to replace the existing (Trace1)
10 * printf-style tracing provided by the existing `GIT_TRACE` and
11 * `GIT_TRACE_PERFORMANCE` facilities. During initial implementation,
12 * Trace2 and Trace1 may operate in parallel.
13 *
14 * The Trace2 API defines a set of high-level messages with known fields,
15 * such as (`start`: `argv`) and (`exit`: {`exit-code`, `elapsed-time`}).
16 *
17 * Trace2 instrumentation throughout the Git code base sends Trace2
18 * messages to the enabled Trace2 Targets. Targets transform these
19 * messages content into purpose-specific formats and write events to
20 * their data streams. In this manner, the Trace2 API can drive
21 * many different types of analysis.
22 *
23 * Targets are defined using a VTable allowing easy extension to other
24 * formats in the future. This might be used to define a binary format,
25 * for example.
26 *
27 * Trace2 is controlled using `trace2.*` config values in the system and
28 * global config files and `GIT_TRACE2*` environment variables. Trace2 does
29 * not read from repo local or worktree config files or respect `-c`
30 * command line config settings.
31 *
32 * For more info about: trace2 targets, conventions for public functions and
33 * macros, trace2 target formats and examples on trace2 API usage refer to
34 * Documentation/technical/api-trace2.txt
35 *
36 */
37
ee4512ed
JH
38struct child_process;
39struct repository;
40struct json_writer;
41
42/*
43 * The public TRACE2 routines are grouped into the following groups:
44 *
45 * [] trace2_initialize -- initialization.
46 * [] trace2_cmd_* -- emit command/control messages.
47 * [] trace2_child* -- emit child start/stop messages.
48 * [] trace2_exec* -- emit exec start/stop messages.
49 * [] trace2_thread* -- emit thread start/stop messages.
50 * [] trace2_def* -- emit definition/parameter mesasges.
51 * [] trace2_region* -- emit region nesting messages.
52 * [] trace2_data* -- emit region/thread/repo data messages.
53 * [] trace2_printf* -- legacy trace[1] messages.
54 */
55
a0897249
JH
56/*
57 * Initialize the TRACE2 clock and do nothing else, in particular
58 * no mallocs, no system inspection, and no environment inspection.
59 *
60 * This should be called at the very top of main() to capture the
61 * process start time. This is intended to reduce chicken-n-egg
62 * bootstrap pressure.
63 *
64 * It is safe to call this more than once. This allows capturing
65 * absolute startup costs on Windows which uses a little trickery
66 * to do setup work before common-main.c:main() is called.
67 *
68 * The main trace2_initialize_fl() may be called a little later
69 * after more infrastructure is established.
70 */
71void trace2_initialize_clock(void);
72
ee4512ed
JH
73/*
74 * Initialize TRACE2 tracing facility if any of the builtin TRACE2
bce9db6d 75 * targets are enabled in the system config or the environment.
6c51cb52
HW
76 * This includes setting up the Trace2 thread local storage (TLS).
77 * Emits a 'version' message containing the version of git
78 * and the Trace2 protocol.
79 *
80 * This function should be called from `main()` as early as possible in
81 * the life of the process after essential process initialization.
ee4512ed
JH
82 *
83 * Cleanup/Termination is handled automatically by a registered
84 * atexit() routine.
85 */
86void trace2_initialize_fl(const char *file, int line);
87
88#define trace2_initialize() trace2_initialize_fl(__FILE__, __LINE__)
89
90/*
6c51cb52 91 * Return 1 if trace2 is enabled (at least one target is active).
ee4512ed
JH
92 */
93int trace2_is_enabled(void);
94
95/*
96 * Emit a 'start' event with the original (unmodified) argv.
97 */
98void trace2_cmd_start_fl(const char *file, int line, const char **argv);
99
100#define trace2_cmd_start(argv) trace2_cmd_start_fl(__FILE__, __LINE__, (argv))
101
102/*
103 * Emit an 'exit' event.
104 *
105 * Write the exit-code that will be passed to exit() or returned
106 * from main().
107 *
108 * Use this prior to actually calling exit().
109 * See "#define exit()" in git-compat-util.h
110 */
111int trace2_cmd_exit_fl(const char *file, int line, int code);
112
113#define trace2_cmd_exit(code) (trace2_cmd_exit_fl(__FILE__, __LINE__, (code)))
114
115/*
116 * Emit an 'error' event.
117 *
118 * Write an error message to the TRACE2 targets.
119 */
120void trace2_cmd_error_va_fl(const char *file, int line, const char *fmt,
121 va_list ap);
122
123#define trace2_cmd_error_va(fmt, ap) \
124 trace2_cmd_error_va_fl(__FILE__, __LINE__, (fmt), (ap))
125
126/*
127 * Emit a 'pathname' event with the canonical pathname of the current process
128 * This gives post-processors a simple field to identify the command without
129 * having to parse the argv. For example, to distinguish invocations from
130 * installed versus debug executables.
131 */
132void trace2_cmd_path_fl(const char *file, int line, const char *pathname);
133
134#define trace2_cmd_path(p) trace2_cmd_path_fl(__FILE__, __LINE__, (p))
135
2f732bf1
ES
136/*
137 * Emit an 'ancestry' event with the process name of the current process's
138 * parent process.
139 * This gives post-processors a way to determine what invoked the command and
140 * learn more about usage patterns.
141 */
142void trace2_cmd_ancestry_fl(const char *file, int line, const char **parent_names);
143
144#define trace2_cmd_ancestry(v) trace2_cmd_ancestry_fl(__FILE__, __LINE__, (v))
145
ee4512ed
JH
146/*
147 * Emit a 'cmd_name' event with the canonical name of the command.
148 * This gives post-processors a simple field to identify the command
149 * without having to parse the argv.
150 */
151void trace2_cmd_name_fl(const char *file, int line, const char *name);
152
153#define trace2_cmd_name(v) trace2_cmd_name_fl(__FILE__, __LINE__, (v))
154
155/*
156 * Emit a 'cmd_mode' event to further describe the command being run.
157 * For example, "checkout" can checkout a single file or can checkout a
158 * different branch. This gives post-processors a simple field to compare
159 * equivalent commands without having to parse the argv.
160 */
161void trace2_cmd_mode_fl(const char *file, int line, const char *mode);
162
163#define trace2_cmd_mode(sv) trace2_cmd_mode_fl(__FILE__, __LINE__, (sv))
164
165/*
6c51cb52
HW
166 * Emits an "alias" message containing the alias used and the argument
167 * expansion.
ee4512ed
JH
168 */
169void trace2_cmd_alias_fl(const char *file, int line, const char *alias,
170 const char **argv);
171
172#define trace2_cmd_alias(alias, argv) \
173 trace2_cmd_alias_fl(__FILE__, __LINE__, (alias), (argv))
174
175/*
6c51cb52 176 * Emit one or more 'def_param' events for "important" configuration
ee4512ed
JH
177 * settings.
178 *
bce9db6d
JH
179 * Use the TR2_SYSENV_CFG_PARAM setting to register a comma-separated
180 * list of patterns configured important. For example:
181 * git config --system trace2.configParams 'core.*,remote.*.url'
182 * or:
e4b75d6a 183 * GIT_TRACE2_CONFIG_PARAMS=core.*,remote.*.url"
ee4512ed
JH
184 *
185 * Note: this routine does a read-only iteration on the config data
186 * (using read_early_config()), so it must not be called until enough
187 * of the process environment has been established. This includes the
188 * location of the git and worktree directories, expansion of any "-c"
189 * and "-C" command line options, and etc.
190 */
191void trace2_cmd_list_config_fl(const char *file, int line);
192
193#define trace2_cmd_list_config() trace2_cmd_list_config_fl(__FILE__, __LINE__)
194
3d3adaad
JS
195/*
196 * Emit one or more 'def_param' events for "important" environment variables.
197 *
198 * Use the TR2_SYSENV_ENV_VARS setting to register a comma-separated list of
199 * environment variables considered important. For example:
200 * git config --system trace2.envVars 'GIT_HTTP_USER_AGENT,GIT_CONFIG'
201 * or:
202 * GIT_TRACE2_ENV_VARS="GIT_HTTP_USER_AGENT,GIT_CONFIG"
203 */
204void trace2_cmd_list_env_vars_fl(const char *file, int line);
205
206#define trace2_cmd_list_env_vars() trace2_cmd_list_env_vars_fl(__FILE__, __LINE__)
207
ee4512ed
JH
208/*
209 * Emit a "def_param" event for the given config key/value pair IF
6c51cb52 210 * we consider the key to be "important".
ee4512ed
JH
211 *
212 * Use this for new/updated config settings created/updated after
213 * trace2_cmd_list_config() is called.
214 */
215void trace2_cmd_set_config_fl(const char *file, int line, const char *key,
216 const char *value);
217
218#define trace2_cmd_set_config(k, v) \
219 trace2_cmd_set_config_fl(__FILE__, __LINE__, (k), (v))
220
6c51cb52
HW
221/**
222 * Emits a "child_start" message containing the "child-id",
223 * "child-argv", and "child-classification".
ee4512ed
JH
224 *
225 * Before calling optionally set "cmd->trace2_child_class" to a string
226 * describing the type of the child process. For example, "editor" or
227 * "pager".
6c51cb52
HW
228 *
229 * This function assigns a unique "child-id" to `cmd->trace2_child_id`.
230 * This field is used later during the "child_exit" message to associate
231 * it with the "child_start" message.
232 *
233 * This function should be called before spawning the child process.
ee4512ed
JH
234 */
235void trace2_child_start_fl(const char *file, int line,
236 struct child_process *cmd);
237
238#define trace2_child_start(cmd) trace2_child_start_fl(__FILE__, __LINE__, (cmd))
239
6c51cb52
HW
240/**
241 * Emits a "child_exit" message containing the "child-id",
242 * the child's elapsed time and exit-code.
243 *
244 * The reported elapsed time includes the process creation overhead and
245 * time spend waiting for it to exit, so it may be slightly longer than
246 * the time reported by the child itself.
247 *
248 * This function should be called after reaping the child process.
ee4512ed
JH
249 */
250void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd,
251 int child_exit_code);
252
253#define trace2_child_exit(cmd, code) \
254 trace2_child_exit_fl(__FILE__, __LINE__, (cmd), (code))
255
6c51cb52 256/**
ee4512ed
JH
257 * Emit an 'exec' event prior to calling one of exec(), execv(),
258 * execvp(), and etc. On Unix-derived systems, this will be the
259 * last event emitted for the current process, unless the exec
260 * fails. On Windows, exec() behaves like 'child_start' and a
261 * waitpid(), so additional events may be emitted.
262 *
6c51cb52
HW
263 * Returns a unique "exec-id". This value is used later
264 * if the exec() fails and a "exec-result" message is necessary.
ee4512ed
JH
265 */
266int trace2_exec_fl(const char *file, int line, const char *exe,
267 const char **argv);
268
269#define trace2_exec(exe, argv) trace2_exec_fl(__FILE__, __LINE__, (exe), (argv))
270
6c51cb52 271/**
ee4512ed
JH
272 * Emit an 'exec_result' when possible. On Unix-derived systems,
273 * this should be called after exec() returns (which only happens
274 * when there is an error starting the new process). On Windows,
275 * this should be called after the waitpid().
276 *
277 * The "exec_id" should be the value returned from trace2_exec().
278 */
279void trace2_exec_result_fl(const char *file, int line, int exec_id, int code);
280
281#define trace2_exec_result(id, code) \
282 trace2_exec_result_fl(__FILE__, __LINE__, (id), (code))
283
284/*
285 * Emit a 'thread_start' event. This must be called from inside the
286 * thread-proc to set up the trace2 TLS data for the thread.
287 *
288 * Thread names should be descriptive, like "preload_index".
289 * Thread names will be decorated with an instance number automatically.
290 */
291void trace2_thread_start_fl(const char *file, int line,
292 const char *thread_name);
293
294#define trace2_thread_start(thread_name) \
295 trace2_thread_start_fl(__FILE__, __LINE__, (thread_name))
296
297/*
298 * Emit a 'thread_exit' event. This must be called from inside the
299 * thread-proc to report thread-specific data and cleanup TLS data
300 * for the thread.
301 */
302void trace2_thread_exit_fl(const char *file, int line);
303
304#define trace2_thread_exit() trace2_thread_exit_fl(__FILE__, __LINE__)
305
306/*
6c51cb52 307 * Emits a "def_param" message containing a key/value pair.
ee4512ed 308 *
6c51cb52
HW
309 * This message is intended to report some global aspect of the current
310 * command, such as a configuration setting or command line switch that
311 * significantly affects program performance or behavior, such as
312 * `core.abbrev`, `status.showUntrackedFiles`, or `--no-ahead-behind`.
ee4512ed
JH
313 */
314void trace2_def_param_fl(const char *file, int line, const char *param,
315 const char *value);
316
317#define trace2_def_param(param, value) \
318 trace2_def_param_fl(__FILE__, __LINE__, (param), (value))
319
320/*
321 * Tell trace2 about a newly instantiated repo object and assign
322 * a trace2-repo-id to be used in subsequent activity events.
323 *
324 * Emits a 'worktree' event for this repo instance.
6c51cb52
HW
325 *
326 * Region and data messages may refer to this repo-id.
327 *
328 * The main/top-level repository will have repo-id value 1 (aka "r1").
329 *
330 * The repo-id field is in anticipation of future in-proc submodule
331 * repositories.
ee4512ed
JH
332 */
333void trace2_def_repo_fl(const char *file, int line, struct repository *repo);
334
335#define trace2_def_repo(repo) trace2_def_repo_fl(__FILE__, __LINE__, repo)
336
6c51cb52 337/**
ee4512ed
JH
338 * Emit a 'region_enter' event for <category>.<label> with optional
339 * repo-id and printf message.
340 *
6c51cb52
HW
341 * This function pushes a new region nesting stack level on the current
342 * thread and starts a clock for the new stack frame.
343 *
344 * The `category` field is an arbitrary category name used to classify
345 * regions by feature area, such as "status" or "index". At this time
346 * it is only just printed along with the rest of the message. It may
347 * be used in the future to filter messages.
348 *
349 * The `label` field is an arbitrary label used to describe the activity
350 * being started, such as "read_recursive" or "do_read_index".
351 *
352 * The `repo` field, if set, will be used to get the "repo-id", so that
353 * recursive oerations can be attributed to the correct repository.
ee4512ed
JH
354 */
355void trace2_region_enter_fl(const char *file, int line, const char *category,
ad006fe4 356 const char *label, const struct repository *repo, ...);
ee4512ed
JH
357
358#define trace2_region_enter(category, label, repo) \
359 trace2_region_enter_fl(__FILE__, __LINE__, (category), (label), (repo))
360
361void trace2_region_enter_printf_va_fl(const char *file, int line,
362 const char *category, const char *label,
363 const struct repository *repo,
364 const char *fmt, va_list ap);
365
366#define trace2_region_enter_printf_va(category, label, repo, fmt, ap) \
367 trace2_region_enter_printf_va_fl(__FILE__, __LINE__, (category), \
368 (label), (repo), (fmt), (ap))
369
370void trace2_region_enter_printf_fl(const char *file, int line,
371 const char *category, const char *label,
372 const struct repository *repo,
373 const char *fmt, ...);
374
375#ifdef HAVE_VARIADIC_MACROS
376#define trace2_region_enter_printf(category, label, repo, ...) \
377 trace2_region_enter_printf_fl(__FILE__, __LINE__, (category), (label), \
378 (repo), __VA_ARGS__)
379#else
380/* clang-format off */
381__attribute__((format (region_enter_printf, 4, 5)))
382void trace2_region_enter_printf(const char *category, const char *label,
383 const struct repository *repo, const char *fmt,
384 ...);
385/* clang-format on */
386#endif
387
6c51cb52 388/**
ee4512ed
JH
389 * Emit a 'region_leave' event for <category>.<label> with optional
390 * repo-id and printf message.
391 *
392 * Leave current nesting level and report the elapsed time spent
393 * in this nesting level.
6c51cb52
HW
394 *
395 * The `category`, `label`, and `repo` fields are the same as
396 * trace2_region_enter_fl. The `category` and `label` do not
397 * need to match the corresponding "region_enter" message,
398 * but it makes the data stream easier to understand.
ee4512ed
JH
399 */
400void trace2_region_leave_fl(const char *file, int line, const char *category,
ad006fe4 401 const char *label, const struct repository *repo, ...);
ee4512ed
JH
402
403#define trace2_region_leave(category, label, repo) \
404 trace2_region_leave_fl(__FILE__, __LINE__, (category), (label), (repo))
405
406void trace2_region_leave_printf_va_fl(const char *file, int line,
407 const char *category, const char *label,
408 const struct repository *repo,
409 const char *fmt, va_list ap);
410
411#define trace2_region_leave_printf_va(category, label, repo, fmt, ap) \
412 trace2_region_leave_printf_va_fl(__FILE__, __LINE__, (category), \
413 (label), (repo), (fmt), (ap))
414
415void trace2_region_leave_printf_fl(const char *file, int line,
416 const char *category, const char *label,
417 const struct repository *repo,
418 const char *fmt, ...);
419
420#ifdef HAVE_VARIADIC_MACROS
421#define trace2_region_leave_printf(category, label, repo, ...) \
422 trace2_region_leave_printf_fl(__FILE__, __LINE__, (category), (label), \
423 (repo), __VA_ARGS__)
424#else
425/* clang-format off */
426__attribute__((format (region_leave_printf, 4, 5)))
427void trace2_region_leave_printf(const char *category, const char *label,
428 const struct repository *repo, const char *fmt,
429 ...);
430/* clang-format on */
431#endif
432
6c51cb52 433/**
ee4512ed
JH
434 * Emit a key-value pair 'data' event of the form <category>.<key> = <value>.
435 * This event implicitly contains information about thread, nesting region,
436 * and optional repo-id.
6c51cb52
HW
437 * This could be used to print the number of files in a directory during
438 * a multi-threaded recursive tree walk.
ee4512ed
JH
439 *
440 * On event-based TRACE2 targets, this generates a 'data' event suitable
441 * for post-processing. On printf-based TRACE2 targets, this is converted
442 * into a fixed-format printf message.
443 */
444void trace2_data_string_fl(const char *file, int line, const char *category,
445 const struct repository *repo, const char *key,
446 const char *value);
447
448#define trace2_data_string(category, repo, key, value) \
449 trace2_data_string_fl(__FILE__, __LINE__, (category), (repo), (key), \
450 (value))
451
452void trace2_data_intmax_fl(const char *file, int line, const char *category,
453 const struct repository *repo, const char *key,
454 intmax_t value);
455
456#define trace2_data_intmax(category, repo, key, value) \
457 trace2_data_intmax_fl(__FILE__, __LINE__, (category), (repo), (key), \
458 (value))
459
460void trace2_data_json_fl(const char *file, int line, const char *category,
461 const struct repository *repo, const char *key,
462 const struct json_writer *jw);
463
464#define trace2_data_json(category, repo, key, value) \
465 trace2_data_json_fl(__FILE__, __LINE__, (category), (repo), (key), \
466 (value))
467
468/*
469 * Emit a 'printf' event.
470 *
471 * Write an arbitrary formatted message to the TRACE2 targets. These
472 * text messages should be considered as human-readable strings without
473 * any formatting guidelines. Post-processors may choose to ignore
474 * them.
475 */
476void trace2_printf_va_fl(const char *file, int line, const char *fmt,
477 va_list ap);
478
479#define trace2_printf_va(fmt, ap) \
480 trace2_printf_va_fl(__FILE__, __LINE__, (fmt), (ap))
481
482void trace2_printf_fl(const char *file, int line, const char *fmt, ...);
483
484#ifdef HAVE_VARIADIC_MACROS
485#define trace2_printf(...) trace2_printf_fl(__FILE__, __LINE__, __VA_ARGS__)
486#else
487/* clang-format off */
488__attribute__((format (printf, 1, 2)))
489void trace2_printf(const char *fmt, ...);
490/* clang-format on */
491#endif
492
353d3d77
JH
493/*
494 * Optional platform-specific code to dump information about the
495 * current and any parent process(es). This is intended to allow
496 * post-processors to know who spawned this git instance and anything
26c6f251 497 * else that the platform may be able to tell us about the current process.
353d3d77 498 */
26c6f251
JH
499
500enum trace2_process_info_reason {
501 TRACE2_PROCESS_INFO_STARTUP,
502 TRACE2_PROCESS_INFO_EXIT,
503};
504
26c6f251 505void trace2_collect_process_info(enum trace2_process_info_reason reason);
353d3d77 506
e97e1cf4
JS
507const char *trace2_session_id(void);
508
ee4512ed 509#endif /* TRACE2_H */