freshlybakedca.ke
Git fork
1#ifndef TRACE2_H
2#define TRACE2_H
3
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.adoc
35 *
36 */
37
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 * [] trace2_timer* -- stopwatch timers (messages are deferred).
55 * [] trace2_counter* -- global counters (messages are deferred).
56 */
57
58/*
59 * Initialize the TRACE2 clock and do nothing else, in particular
60 * no mallocs, no system inspection, and no environment inspection.
61 *
62 * This should be called at the very top of main() to capture the
63 * process start time. This is intended to reduce chicken-n-egg
64 * bootstrap pressure.
65 *
66 * It is safe to call this more than once. This allows capturing
67 * absolute startup costs on Windows which uses a little trickery
68 * to do setup work before common-main.c:main() is called.
69 *
70 * The main trace2_initialize_fl() may be called a little later
71 * after more infrastructure is established.
72 */
73void trace2_initialize_clock(void);
74
75/*
76 * Initialize TRACE2 tracing facility if any of the builtin TRACE2
77 * targets are enabled in the system config or the environment.
78 * This emits a 'version' message containing the version of git
79 * and the Trace2 protocol.
80 *
81 * This function should be called from `main()` as early as possible in
82 * the life of the process after essential process initialization.
83 *
84 * Cleanup/Termination is handled automatically by a registered
85 * atexit() routine.
86 */
87void trace2_initialize_fl(const char *file, int line);
88
89#define trace2_initialize() trace2_initialize_fl(__FILE__, __LINE__)
90
91/*
92 * Return 1 if trace2 is enabled (at least one target is active).
93 */
94int trace2_is_enabled(void);
95
96/*
97 * Emit a 'start' event with the original (unmodified) argv.
98 */
99void trace2_cmd_start_fl(const char *file, int line, const char **argv);
100
101#define trace2_cmd_start(argv) trace2_cmd_start_fl(__FILE__, __LINE__, (argv))
102
103/*
104 * Emit an 'exit' event.
105 */
106void trace2_cmd_exit_fl(const char *file, int line, int code);
107
108#define trace2_cmd_exit(code) (trace2_cmd_exit_fl(__FILE__, __LINE__, (code)))
109
110/*
111 * Emit an 'error' event.
112 *
113 * Write an error message to the TRACE2 targets.
114 */
115void trace2_cmd_error_va_fl(const char *file, int line, const char *fmt,
116 va_list ap);
117
118#define trace2_cmd_error_va(fmt, ap) \
119 trace2_cmd_error_va_fl(__FILE__, __LINE__, (fmt), (ap))
120
121/*
122 * Emit a 'pathname' event with the canonical pathname of the current process
123 * This gives post-processors a simple field to identify the command without
124 * having to parse the argv. For example, to distinguish invocations from
125 * installed versus debug executables.
126 */
127void trace2_cmd_path_fl(const char *file, int line, const char *pathname);
128
129#define trace2_cmd_path(p) trace2_cmd_path_fl(__FILE__, __LINE__, (p))
130
131/*
132 * Emit an 'ancestry' event with the process name of the current process's
133 * parent process.
134 * This gives post-processors a way to determine what invoked the command and
135 * learn more about usage patterns.
136 */
137void trace2_cmd_ancestry_fl(const char *file, int line, const char **parent_names);
138
139#define trace2_cmd_ancestry(v) trace2_cmd_ancestry_fl(__FILE__, __LINE__, (v))
140
141/*
142 * Emit a 'cmd_name' event with the canonical name of the command.
143 * This gives post-processors a simple field to identify the command
144 * without having to parse the argv.
145 */
146void trace2_cmd_name_fl(const char *file, int line, const char *name);
147
148#define trace2_cmd_name(v) trace2_cmd_name_fl(__FILE__, __LINE__, (v))
149
150/*
151 * Emit a 'cmd_mode' event to further describe the command being run.
152 * For example, "checkout" can checkout a single file or can checkout a
153 * different branch. This gives post-processors a simple field to compare
154 * equivalent commands without having to parse the argv.
155 */
156void trace2_cmd_mode_fl(const char *file, int line, const char *mode);
157
158#define trace2_cmd_mode(sv) trace2_cmd_mode_fl(__FILE__, __LINE__, (sv))
159
160/*
161 * Emits an "alias" message containing the alias used and the argument
162 * expansion.
163 */
164void trace2_cmd_alias_fl(const char *file, int line, const char *alias,
165 const char **argv);
166
167#define trace2_cmd_alias(alias, argv) \
168 trace2_cmd_alias_fl(__FILE__, __LINE__, (alias), (argv))
169
170/*
171 * Emit one or more 'def_param' events for "important" configuration
172 * settings.
173 *
174 * Use the TR2_SYSENV_CFG_PARAM setting to register a comma-separated
175 * list of patterns configured important. For example:
176 * git config --system trace2.configParams 'core.*,remote.*.url'
177 * or:
178 * GIT_TRACE2_CONFIG_PARAMS=core.*,remote.*.url"
179 *
180 * Note: this routine does a read-only iteration on the config data
181 * (using read_early_config()), so it must not be called until enough
182 * of the process environment has been established. This includes the
183 * location of the git and worktree directories, expansion of any "-c"
184 * and "-C" command line options, and etc.
185 */
186void trace2_cmd_list_config_fl(const char *file, int line);
187
188#define trace2_cmd_list_config() trace2_cmd_list_config_fl(__FILE__, __LINE__)
189
190/*
191 * Emit one or more 'def_param' events for "important" environment variables.
192 *
193 * Use the TR2_SYSENV_ENV_VARS setting to register a comma-separated list of
194 * environment variables considered important. For example:
195 * git config --system trace2.envVars 'GIT_HTTP_USER_AGENT,GIT_CONFIG'
196 * or:
197 * GIT_TRACE2_ENV_VARS="GIT_HTTP_USER_AGENT,GIT_CONFIG"
198 */
199void trace2_cmd_list_env_vars_fl(const char *file, int line);
200
201#define trace2_cmd_list_env_vars() trace2_cmd_list_env_vars_fl(__FILE__, __LINE__)
202
203/*
204 * Emit a "def_param" event for the given config key/value pair IF
205 * we consider the key to be "important".
206 *
207 * Use this for new/updated config settings created/updated after
208 * trace2_cmd_list_config() is called.
209 */
210void trace2_cmd_set_config_fl(const char *file, int line, const char *key,
211 const char *value);
212
213#define trace2_cmd_set_config(k, v) \
214 trace2_cmd_set_config_fl(__FILE__, __LINE__, (k), (v))
215
216/**
217 * Emits a "child_start" message containing the "child-id",
218 * "child-argv", and "child-classification".
219 *
220 * Before calling optionally set "cmd->trace2_child_class" to a string
221 * describing the type of the child process. For example, "editor" or
222 * "pager".
223 *
224 * This function assigns a unique "child-id" to `cmd->trace2_child_id`.
225 * This field is used later during the "child_exit" message to associate
226 * it with the "child_start" message.
227 *
228 * This function should be called before spawning the child process.
229 */
230void trace2_child_start_fl(const char *file, int line,
231 struct child_process *cmd);
232
233#define trace2_child_start(cmd) trace2_child_start_fl(__FILE__, __LINE__, (cmd))
234
235/**
236 * Emits a "child_exit" message containing the "child-id",
237 * the child's elapsed time and exit-code.
238 *
239 * The reported elapsed time includes the process creation overhead and
240 * time spend waiting for it to exit, so it may be slightly longer than
241 * the time reported by the child itself.
242 *
243 * This function should be called after reaping the child process.
244 */
245void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd,
246 int child_exit_code);
247
248#define trace2_child_exit(cmd, code) \
249 trace2_child_exit_fl(__FILE__, __LINE__, (cmd), (code))
250
251/**
252 * Emits a "child_ready" message containing the "child-id" and a flag
253 * indicating whether the child was considered "ready" when we
254 * released it.
255 *
256 * This function should be called after starting a daemon process in
257 * the background (and after giving it sufficient time to boot
258 * up) to indicate that we no longer control or own it.
259 *
260 * The "ready" argument should contain one of { "ready", "timeout",
261 * "error" } to indicate the state of the running daemon when we
262 * released it.
263 *
264 * If the daemon process fails to start or it exits or is terminated
265 * while we are still waiting for it, the caller should emit a
266 * regular "child_exit" to report the normal process exit information.
267 *
268 */
269void trace2_child_ready_fl(const char *file, int line,
270 struct child_process *cmd,
271 const char *ready);
272
273#define trace2_child_ready(cmd, ready) \
274 trace2_child_ready_fl(__FILE__, __LINE__, (cmd), (ready))
275
276/**
277 * Emit an 'exec' event prior to calling one of exec(), execv(),
278 * execvp(), and etc. On Unix-derived systems, this will be the
279 * last event emitted for the current process, unless the exec
280 * fails. On Windows, exec() behaves like 'child_start' and a
281 * waitpid(), so additional events may be emitted.
282 *
283 * Returns a unique "exec-id". This value is used later
284 * if the exec() fails and a "exec-result" message is necessary.
285 */
286int trace2_exec_fl(const char *file, int line, const char *exe,
287 const char **argv);
288
289#define trace2_exec(exe, argv) trace2_exec_fl(__FILE__, __LINE__, (exe), (argv))
290
291/**
292 * Emit an 'exec_result' when possible. On Unix-derived systems,
293 * this should be called after exec() returns (which only happens
294 * when there is an error starting the new process). On Windows,
295 * this should be called after the waitpid().
296 *
297 * The "exec_id" should be the value returned from trace2_exec().
298 */
299void trace2_exec_result_fl(const char *file, int line, int exec_id, int code);
300
301#define trace2_exec_result(id, code) \
302 trace2_exec_result_fl(__FILE__, __LINE__, (id), (code))
303
304/*
305 * Emit a 'thread_start' event. This must be called from inside the
306 * thread-proc to allow the thread to create its own thread-local
307 * storage.
308 *
309 * The thread base name should be descriptive, like "preload_index" or
310 * taken from the thread-proc function. A unique thread name will be
311 * created from the given base name and the thread id automatically.
312 */
313void trace2_thread_start_fl(const char *file, int line,
314 const char *thread_base_name);
315
316#define trace2_thread_start(thread_base_name) \
317 trace2_thread_start_fl(__FILE__, __LINE__, (thread_base_name))
318
319/*
320 * Emit a 'thread_exit' event. This must be called from inside the
321 * thread-proc so that the thread can access and clean up its
322 * thread-local storage.
323 */
324void trace2_thread_exit_fl(const char *file, int line);
325
326#define trace2_thread_exit() trace2_thread_exit_fl(__FILE__, __LINE__)
327
328struct key_value_info;
329/*
330 * Emits a "def_param" message containing a key/value pair.
331 *
332 * This message is intended to report some global aspect of the current
333 * command, such as a configuration setting or command line switch that
334 * significantly affects program performance or behavior, such as
335 * `core.abbrev`, `status.showUntrackedFiles`, or `--no-ahead-behind`.
336 */
337void trace2_def_param_fl(const char *file, int line, const char *param,
338 const char *value, const struct key_value_info *kvi);
339
340#define trace2_def_param(param, value, kvi) \
341 trace2_def_param_fl(__FILE__, __LINE__, (param), (value), (kvi))
342
343/*
344 * Tell trace2 about a newly instantiated repo object and assign
345 * a trace2-repo-id to be used in subsequent activity events.
346 *
347 * Emits a 'worktree' event for this repo instance.
348 *
349 * Region and data messages may refer to this repo-id.
350 *
351 * The main/top-level repository will have repo-id value 1 (aka "r1").
352 *
353 * The repo-id field is in anticipation of future in-proc submodule
354 * repositories.
355 */
356void trace2_def_repo_fl(const char *file, int line, struct repository *repo);
357
358#define trace2_def_repo(repo) trace2_def_repo_fl(__FILE__, __LINE__, repo)
359
360/**
361 * Emit a 'region_enter' event for <category>.<label> with optional
362 * repo-id and printf message.
363 *
364 * This function pushes a new region nesting stack level on the current
365 * thread and starts a clock for the new stack frame.
366 *
367 * The `category` field is an arbitrary category name used to classify
368 * regions by feature area, such as "status" or "index". At this time
369 * it is only just printed along with the rest of the message. It may
370 * be used in the future to filter messages.
371 *
372 * The `label` field is an arbitrary label used to describe the activity
373 * being started, such as "read_recursive" or "do_read_index".
374 *
375 * The `repo` field, if set, will be used to get the "repo-id", so that
376 * recursive operations can be attributed to the correct repository.
377 */
378void trace2_region_enter_fl(const char *file, int line, const char *category,
379 const char *label, const struct repository *repo, ...);
380
381#define trace2_region_enter(category, label, repo) \
382 trace2_region_enter_fl(__FILE__, __LINE__, (category), (label), (repo))
383
384void trace2_region_enter_printf_va_fl(const char *file, int line,
385 const char *category, const char *label,
386 const struct repository *repo,
387 const char *fmt, va_list ap);
388
389#define trace2_region_enter_printf_va(category, label, repo, fmt, ap) \
390 trace2_region_enter_printf_va_fl(__FILE__, __LINE__, (category), \
391 (label), (repo), (fmt), (ap))
392
393__attribute__((format (printf, 6, 7)))
394void trace2_region_enter_printf_fl(const char *file, int line,
395 const char *category, const char *label,
396 const struct repository *repo,
397 const char *fmt, ...);
398
399#define trace2_region_enter_printf(category, label, repo, ...) \
400 trace2_region_enter_printf_fl(__FILE__, __LINE__, (category), (label), \
401 (repo), __VA_ARGS__)
402
403/**
404 * Emit a 'region_leave' event for <category>.<label> with optional
405 * repo-id and printf message.
406 *
407 * Leave current nesting level and report the elapsed time spent
408 * in this nesting level.
409 *
410 * The `category`, `label`, and `repo` fields are the same as
411 * trace2_region_enter_fl. The `category` and `label` do not
412 * need to match the corresponding "region_enter" message,
413 * but it makes the data stream easier to understand.
414 */
415void trace2_region_leave_fl(const char *file, int line, const char *category,
416 const char *label, const struct repository *repo, ...);
417
418#define trace2_region_leave(category, label, repo) \
419 trace2_region_leave_fl(__FILE__, __LINE__, (category), (label), (repo))
420
421void trace2_region_leave_printf_va_fl(const char *file, int line,
422 const char *category, const char *label,
423 const struct repository *repo,
424 const char *fmt, va_list ap);
425
426#define trace2_region_leave_printf_va(category, label, repo, fmt, ap) \
427 trace2_region_leave_printf_va_fl(__FILE__, __LINE__, (category), \
428 (label), (repo), (fmt), (ap))
429
430void trace2_region_leave_printf_fl(const char *file, int line,
431 const char *category, const char *label,
432 const struct repository *repo,
433 const char *fmt, ...);
434
435#define trace2_region_leave_printf(category, label, repo, ...) \
436 trace2_region_leave_printf_fl(__FILE__, __LINE__, (category), (label), \
437 (repo), __VA_ARGS__)
438
439/**
440 * Emit a key-value pair 'data' event of the form <category>.<key> = <value>.
441 * This event implicitly contains information about thread, nesting region,
442 * and optional repo-id.
443 * This could be used to print the number of files in a directory during
444 * a multi-threaded recursive tree walk.
445 *
446 * On event-based TRACE2 targets, this generates a 'data' event suitable
447 * for post-processing. On printf-based TRACE2 targets, this is converted
448 * into a fixed-format printf message.
449 */
450void trace2_data_string_fl(const char *file, int line, const char *category,
451 const struct repository *repo, const char *key,
452 const char *value);
453
454#define trace2_data_string(category, repo, key, value) \
455 trace2_data_string_fl(__FILE__, __LINE__, (category), (repo), (key), \
456 (value))
457
458void trace2_data_intmax_fl(const char *file, int line, const char *category,
459 const struct repository *repo, const char *key,
460 intmax_t value);
461
462#define trace2_data_intmax(category, repo, key, value) \
463 trace2_data_intmax_fl(__FILE__, __LINE__, (category), (repo), (key), \
464 (value))
465
466void trace2_data_json_fl(const char *file, int line, const char *category,
467 const struct repository *repo, const char *key,
468 const struct json_writer *jw);
469
470#define trace2_data_json(category, repo, key, value) \
471 trace2_data_json_fl(__FILE__, __LINE__, (category), (repo), (key), \
472 (value))
473
474/*
475 * Emit a 'printf' event.
476 *
477 * Write an arbitrary formatted message to the TRACE2 targets. These
478 * text messages should be considered as human-readable strings without
479 * any formatting guidelines. Post-processors may choose to ignore
480 * them.
481 */
482void trace2_printf_va_fl(const char *file, int line, const char *fmt,
483 va_list ap);
484
485#define trace2_printf_va(fmt, ap) \
486 trace2_printf_va_fl(__FILE__, __LINE__, (fmt), (ap))
487
488void trace2_printf_fl(const char *file, int line, const char *fmt, ...);
489
490#define trace2_printf(...) trace2_printf_fl(__FILE__, __LINE__, __VA_ARGS__)
491
492/*
493 * Define the set of stopwatch timers.
494 *
495 * We can add more at any time, but they must be defined at compile
496 * time (to avoid the need to dynamically allocate and synchronize
497 * them between different threads).
498 *
499 * These must start at 0 and be contiguous (because we use them
500 * elsewhere as array indexes).
501 *
502 * Any values added to this enum must also be added to the
503 * `tr2_timer_metadata[]` in `trace2/tr2_tmr.c`.
504 */
505enum trace2_timer_id {
506 /*
507 * Define two timers for testing. See `t/helper/test-trace2.c`.
508 * These can be used for ad hoc testing, but should not be used
509 * for permanent analysis code.
510 */
511 TRACE2_TIMER_ID_TEST1 = 0, /* emits summary event only */
512 TRACE2_TIMER_ID_TEST2, /* emits summary and thread events */
513
514 /* Add additional timer definitions before here. */
515 TRACE2_NUMBER_OF_TIMERS
516};
517
518/*
519 * Start/Stop the indicated stopwatch timer in the current thread.
520 *
521 * The time spent by the current thread between the _start and _stop
522 * calls will be added to the thread's partial sum for this timer.
523 *
524 * Timer events are emitted at thread and program exit.
525 *
526 * Note: Since the stopwatch API routines do not generate individual
527 * events, they do not take (file, line) arguments. Similarly, the
528 * category and timer name values are defined at compile-time in the
529 * timer definitions array, so they are not needed here in the API.
530 */
531void trace2_timer_start(enum trace2_timer_id tid);
532void trace2_timer_stop(enum trace2_timer_id tid);
533
534/*
535 * Define the set of global counters.
536 *
537 * We can add more at any time, but they must be defined at compile
538 * time (to avoid the need to dynamically allocate and synchronize
539 * them between different threads).
540 *
541 * These must start at 0 and be contiguous (because we use them
542 * elsewhere as array indexes).
543 *
544 * Any values added to this enum be also be added to the
545 * `tr2_counter_metadata[]` in `trace2/tr2_ctr.c`.
546 */
547enum trace2_counter_id {
548 /*
549 * Define two counters for testing. See `t/helper/test-trace2.c`.
550 * These can be used for ad hoc testing, but should not be used
551 * for permanent analysis code.
552 */
553 TRACE2_COUNTER_ID_TEST1 = 0, /* emits summary event only */
554 TRACE2_COUNTER_ID_TEST2, /* emits summary and thread events */
555
556 TRACE2_COUNTER_ID_PACKED_REFS_JUMPS, /* counts number of jumps */
557 TRACE2_COUNTER_ID_REFTABLE_RESEEKS, /* counts number of re-seeks */
558
559 /* counts number of fsyncs */
560 TRACE2_COUNTER_ID_FSYNC_WRITEOUT_ONLY,
561 TRACE2_COUNTER_ID_FSYNC_HARDWARE_FLUSH,
562
563 /* Add additional counter definitions before here. */
564 TRACE2_NUMBER_OF_COUNTERS
565};
566
567/*
568 * Increase the named global counter by value.
569 *
570 * Note that this adds `value` to the current thread's partial sum for
571 * this counter (without locking) and that the complete sum is not
572 * available until all threads have exited, so it does not return the
573 * new value of the counter.
574 */
575void trace2_counter_add(enum trace2_counter_id cid, uint64_t value);
576
577/*
578 * Optional platform-specific code to dump information about the
579 * current and any parent process(es). This is intended to allow
580 * post-processors to know who spawned this git instance and anything
581 * else that the platform may be able to tell us about the current process.
582 */
583
584enum trace2_process_info_reason {
585 TRACE2_PROCESS_INFO_STARTUP,
586 TRACE2_PROCESS_INFO_EXIT,
587};
588
589void trace2_collect_process_info(enum trace2_process_info_reason reason);
590
591const char *trace2_session_id(void);
592
593#endif /* TRACE2_H */