Merge branch 'ma/asciidoctor-more-fixes'
[git/git.git] / trace2.h
CommitLineData
ee4512ed
JH
1#ifndef TRACE2_H
2#define TRACE2_H
3
4struct child_process;
5struct repository;
6struct json_writer;
7
8/*
9 * The public TRACE2 routines are grouped into the following groups:
10 *
11 * [] trace2_initialize -- initialization.
12 * [] trace2_cmd_* -- emit command/control messages.
13 * [] trace2_child* -- emit child start/stop messages.
14 * [] trace2_exec* -- emit exec start/stop messages.
15 * [] trace2_thread* -- emit thread start/stop messages.
16 * [] trace2_def* -- emit definition/parameter mesasges.
17 * [] trace2_region* -- emit region nesting messages.
18 * [] trace2_data* -- emit region/thread/repo data messages.
19 * [] trace2_printf* -- legacy trace[1] messages.
20 */
21
a0897249
JH
22/*
23 * Initialize the TRACE2 clock and do nothing else, in particular
24 * no mallocs, no system inspection, and no environment inspection.
25 *
26 * This should be called at the very top of main() to capture the
27 * process start time. This is intended to reduce chicken-n-egg
28 * bootstrap pressure.
29 *
30 * It is safe to call this more than once. This allows capturing
31 * absolute startup costs on Windows which uses a little trickery
32 * to do setup work before common-main.c:main() is called.
33 *
34 * The main trace2_initialize_fl() may be called a little later
35 * after more infrastructure is established.
36 */
37void trace2_initialize_clock(void);
38
ee4512ed
JH
39/*
40 * Initialize TRACE2 tracing facility if any of the builtin TRACE2
bce9db6d
JH
41 * targets are enabled in the system config or the environment.
42 * Emits a 'version' event.
ee4512ed
JH
43 *
44 * Cleanup/Termination is handled automatically by a registered
45 * atexit() routine.
46 */
47void trace2_initialize_fl(const char *file, int line);
48
49#define trace2_initialize() trace2_initialize_fl(__FILE__, __LINE__)
50
51/*
52 * Return true if trace2 is enabled.
53 */
54int trace2_is_enabled(void);
55
56/*
57 * Emit a 'start' event with the original (unmodified) argv.
58 */
59void trace2_cmd_start_fl(const char *file, int line, const char **argv);
60
61#define trace2_cmd_start(argv) trace2_cmd_start_fl(__FILE__, __LINE__, (argv))
62
63/*
64 * Emit an 'exit' event.
65 *
66 * Write the exit-code that will be passed to exit() or returned
67 * from main().
68 *
69 * Use this prior to actually calling exit().
70 * See "#define exit()" in git-compat-util.h
71 */
72int trace2_cmd_exit_fl(const char *file, int line, int code);
73
74#define trace2_cmd_exit(code) (trace2_cmd_exit_fl(__FILE__, __LINE__, (code)))
75
76/*
77 * Emit an 'error' event.
78 *
79 * Write an error message to the TRACE2 targets.
80 */
81void trace2_cmd_error_va_fl(const char *file, int line, const char *fmt,
82 va_list ap);
83
84#define trace2_cmd_error_va(fmt, ap) \
85 trace2_cmd_error_va_fl(__FILE__, __LINE__, (fmt), (ap))
86
87/*
88 * Emit a 'pathname' event with the canonical pathname of the current process
89 * This gives post-processors a simple field to identify the command without
90 * having to parse the argv. For example, to distinguish invocations from
91 * installed versus debug executables.
92 */
93void trace2_cmd_path_fl(const char *file, int line, const char *pathname);
94
95#define trace2_cmd_path(p) trace2_cmd_path_fl(__FILE__, __LINE__, (p))
96
97/*
98 * Emit a 'cmd_name' event with the canonical name of the command.
99 * This gives post-processors a simple field to identify the command
100 * without having to parse the argv.
101 */
102void trace2_cmd_name_fl(const char *file, int line, const char *name);
103
104#define trace2_cmd_name(v) trace2_cmd_name_fl(__FILE__, __LINE__, (v))
105
106/*
107 * Emit a 'cmd_mode' event to further describe the command being run.
108 * For example, "checkout" can checkout a single file or can checkout a
109 * different branch. This gives post-processors a simple field to compare
110 * equivalent commands without having to parse the argv.
111 */
112void trace2_cmd_mode_fl(const char *file, int line, const char *mode);
113
114#define trace2_cmd_mode(sv) trace2_cmd_mode_fl(__FILE__, __LINE__, (sv))
115
116/*
117 * Emit an 'alias' expansion event.
118 */
119void trace2_cmd_alias_fl(const char *file, int line, const char *alias,
120 const char **argv);
121
122#define trace2_cmd_alias(alias, argv) \
123 trace2_cmd_alias_fl(__FILE__, __LINE__, (alias), (argv))
124
125/*
126 * Emit one or more 'def_param' events for "interesting" configuration
127 * settings.
128 *
bce9db6d
JH
129 * Use the TR2_SYSENV_CFG_PARAM setting to register a comma-separated
130 * list of patterns configured important. For example:
131 * git config --system trace2.configParams 'core.*,remote.*.url'
132 * or:
e4b75d6a 133 * GIT_TRACE2_CONFIG_PARAMS=core.*,remote.*.url"
ee4512ed
JH
134 *
135 * Note: this routine does a read-only iteration on the config data
136 * (using read_early_config()), so it must not be called until enough
137 * of the process environment has been established. This includes the
138 * location of the git and worktree directories, expansion of any "-c"
139 * and "-C" command line options, and etc.
140 */
141void trace2_cmd_list_config_fl(const char *file, int line);
142
143#define trace2_cmd_list_config() trace2_cmd_list_config_fl(__FILE__, __LINE__)
144
145/*
146 * Emit a "def_param" event for the given config key/value pair IF
147 * we consider the key to be "interesting".
148 *
149 * Use this for new/updated config settings created/updated after
150 * trace2_cmd_list_config() is called.
151 */
152void trace2_cmd_set_config_fl(const char *file, int line, const char *key,
153 const char *value);
154
155#define trace2_cmd_set_config(k, v) \
156 trace2_cmd_set_config_fl(__FILE__, __LINE__, (k), (v))
157
158/*
159 * Emit a 'child_start' event prior to spawning a child process.
160 *
161 * Before calling optionally set "cmd->trace2_child_class" to a string
162 * describing the type of the child process. For example, "editor" or
163 * "pager".
164 */
165void trace2_child_start_fl(const char *file, int line,
166 struct child_process *cmd);
167
168#define trace2_child_start(cmd) trace2_child_start_fl(__FILE__, __LINE__, (cmd))
169
170/*
171 * Emit a 'child_exit' event after the child process completes.
172 */
173void trace2_child_exit_fl(const char *file, int line, struct child_process *cmd,
174 int child_exit_code);
175
176#define trace2_child_exit(cmd, code) \
177 trace2_child_exit_fl(__FILE__, __LINE__, (cmd), (code))
178
179/*
180 * Emit an 'exec' event prior to calling one of exec(), execv(),
181 * execvp(), and etc. On Unix-derived systems, this will be the
182 * last event emitted for the current process, unless the exec
183 * fails. On Windows, exec() behaves like 'child_start' and a
184 * waitpid(), so additional events may be emitted.
185 *
186 * Returns the "exec_id".
187 */
188int trace2_exec_fl(const char *file, int line, const char *exe,
189 const char **argv);
190
191#define trace2_exec(exe, argv) trace2_exec_fl(__FILE__, __LINE__, (exe), (argv))
192
193/*
194 * Emit an 'exec_result' when possible. On Unix-derived systems,
195 * this should be called after exec() returns (which only happens
196 * when there is an error starting the new process). On Windows,
197 * this should be called after the waitpid().
198 *
199 * The "exec_id" should be the value returned from trace2_exec().
200 */
201void trace2_exec_result_fl(const char *file, int line, int exec_id, int code);
202
203#define trace2_exec_result(id, code) \
204 trace2_exec_result_fl(__FILE__, __LINE__, (id), (code))
205
206/*
207 * Emit a 'thread_start' event. This must be called from inside the
208 * thread-proc to set up the trace2 TLS data for the thread.
209 *
210 * Thread names should be descriptive, like "preload_index".
211 * Thread names will be decorated with an instance number automatically.
212 */
213void trace2_thread_start_fl(const char *file, int line,
214 const char *thread_name);
215
216#define trace2_thread_start(thread_name) \
217 trace2_thread_start_fl(__FILE__, __LINE__, (thread_name))
218
219/*
220 * Emit a 'thread_exit' event. This must be called from inside the
221 * thread-proc to report thread-specific data and cleanup TLS data
222 * for the thread.
223 */
224void trace2_thread_exit_fl(const char *file, int line);
225
226#define trace2_thread_exit() trace2_thread_exit_fl(__FILE__, __LINE__)
227
228/*
229 * Emit a 'param' event.
230 *
231 * Write a "<param> = <value>" pair describing some aspect of the
232 * run such as an important configuration setting or command line
233 * option that significantly changes command behavior.
234 */
235void trace2_def_param_fl(const char *file, int line, const char *param,
236 const char *value);
237
238#define trace2_def_param(param, value) \
239 trace2_def_param_fl(__FILE__, __LINE__, (param), (value))
240
241/*
242 * Tell trace2 about a newly instantiated repo object and assign
243 * a trace2-repo-id to be used in subsequent activity events.
244 *
245 * Emits a 'worktree' event for this repo instance.
246 */
247void trace2_def_repo_fl(const char *file, int line, struct repository *repo);
248
249#define trace2_def_repo(repo) trace2_def_repo_fl(__FILE__, __LINE__, repo)
250
251/*
252 * Emit a 'region_enter' event for <category>.<label> with optional
253 * repo-id and printf message.
254 *
255 * Enter a new nesting level on the current thread and remember the
256 * current time. This controls the indenting of all subsequent events
257 * on this thread.
258 */
259void trace2_region_enter_fl(const char *file, int line, const char *category,
ad006fe4 260 const char *label, const struct repository *repo, ...);
ee4512ed
JH
261
262#define trace2_region_enter(category, label, repo) \
263 trace2_region_enter_fl(__FILE__, __LINE__, (category), (label), (repo))
264
265void trace2_region_enter_printf_va_fl(const char *file, int line,
266 const char *category, const char *label,
267 const struct repository *repo,
268 const char *fmt, va_list ap);
269
270#define trace2_region_enter_printf_va(category, label, repo, fmt, ap) \
271 trace2_region_enter_printf_va_fl(__FILE__, __LINE__, (category), \
272 (label), (repo), (fmt), (ap))
273
274void trace2_region_enter_printf_fl(const char *file, int line,
275 const char *category, const char *label,
276 const struct repository *repo,
277 const char *fmt, ...);
278
279#ifdef HAVE_VARIADIC_MACROS
280#define trace2_region_enter_printf(category, label, repo, ...) \
281 trace2_region_enter_printf_fl(__FILE__, __LINE__, (category), (label), \
282 (repo), __VA_ARGS__)
283#else
284/* clang-format off */
285__attribute__((format (region_enter_printf, 4, 5)))
286void trace2_region_enter_printf(const char *category, const char *label,
287 const struct repository *repo, const char *fmt,
288 ...);
289/* clang-format on */
290#endif
291
292/*
293 * Emit a 'region_leave' event for <category>.<label> with optional
294 * repo-id and printf message.
295 *
296 * Leave current nesting level and report the elapsed time spent
297 * in this nesting level.
298 */
299void trace2_region_leave_fl(const char *file, int line, const char *category,
ad006fe4 300 const char *label, const struct repository *repo, ...);
ee4512ed
JH
301
302#define trace2_region_leave(category, label, repo) \
303 trace2_region_leave_fl(__FILE__, __LINE__, (category), (label), (repo))
304
305void trace2_region_leave_printf_va_fl(const char *file, int line,
306 const char *category, const char *label,
307 const struct repository *repo,
308 const char *fmt, va_list ap);
309
310#define trace2_region_leave_printf_va(category, label, repo, fmt, ap) \
311 trace2_region_leave_printf_va_fl(__FILE__, __LINE__, (category), \
312 (label), (repo), (fmt), (ap))
313
314void trace2_region_leave_printf_fl(const char *file, int line,
315 const char *category, const char *label,
316 const struct repository *repo,
317 const char *fmt, ...);
318
319#ifdef HAVE_VARIADIC_MACROS
320#define trace2_region_leave_printf(category, label, repo, ...) \
321 trace2_region_leave_printf_fl(__FILE__, __LINE__, (category), (label), \
322 (repo), __VA_ARGS__)
323#else
324/* clang-format off */
325__attribute__((format (region_leave_printf, 4, 5)))
326void trace2_region_leave_printf(const char *category, const char *label,
327 const struct repository *repo, const char *fmt,
328 ...);
329/* clang-format on */
330#endif
331
332/*
333 * Emit a key-value pair 'data' event of the form <category>.<key> = <value>.
334 * This event implicitly contains information about thread, nesting region,
335 * and optional repo-id.
336 *
337 * On event-based TRACE2 targets, this generates a 'data' event suitable
338 * for post-processing. On printf-based TRACE2 targets, this is converted
339 * into a fixed-format printf message.
340 */
341void trace2_data_string_fl(const char *file, int line, const char *category,
342 const struct repository *repo, const char *key,
343 const char *value);
344
345#define trace2_data_string(category, repo, key, value) \
346 trace2_data_string_fl(__FILE__, __LINE__, (category), (repo), (key), \
347 (value))
348
349void trace2_data_intmax_fl(const char *file, int line, const char *category,
350 const struct repository *repo, const char *key,
351 intmax_t value);
352
353#define trace2_data_intmax(category, repo, key, value) \
354 trace2_data_intmax_fl(__FILE__, __LINE__, (category), (repo), (key), \
355 (value))
356
357void trace2_data_json_fl(const char *file, int line, const char *category,
358 const struct repository *repo, const char *key,
359 const struct json_writer *jw);
360
361#define trace2_data_json(category, repo, key, value) \
362 trace2_data_json_fl(__FILE__, __LINE__, (category), (repo), (key), \
363 (value))
364
365/*
366 * Emit a 'printf' event.
367 *
368 * Write an arbitrary formatted message to the TRACE2 targets. These
369 * text messages should be considered as human-readable strings without
370 * any formatting guidelines. Post-processors may choose to ignore
371 * them.
372 */
373void trace2_printf_va_fl(const char *file, int line, const char *fmt,
374 va_list ap);
375
376#define trace2_printf_va(fmt, ap) \
377 trace2_printf_va_fl(__FILE__, __LINE__, (fmt), (ap))
378
379void trace2_printf_fl(const char *file, int line, const char *fmt, ...);
380
381#ifdef HAVE_VARIADIC_MACROS
382#define trace2_printf(...) trace2_printf_fl(__FILE__, __LINE__, __VA_ARGS__)
383#else
384/* clang-format off */
385__attribute__((format (printf, 1, 2)))
386void trace2_printf(const char *fmt, ...);
387/* clang-format on */
388#endif
389
353d3d77
JH
390/*
391 * Optional platform-specific code to dump information about the
392 * current and any parent process(es). This is intended to allow
393 * post-processors to know who spawned this git instance and anything
26c6f251 394 * else that the platform may be able to tell us about the current process.
353d3d77 395 */
26c6f251
JH
396
397enum trace2_process_info_reason {
398 TRACE2_PROCESS_INFO_STARTUP,
399 TRACE2_PROCESS_INFO_EXIT,
400};
401
353d3d77 402#if defined(GIT_WINDOWS_NATIVE)
26c6f251 403void trace2_collect_process_info(enum trace2_process_info_reason reason);
353d3d77 404#else
26c6f251
JH
405#define trace2_collect_process_info(reason) \
406 do { \
353d3d77
JH
407 } while (0)
408#endif
409
ee4512ed 410#endif /* TRACE2_H */