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