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