]>
Commit | Line | Data |
---|---|---|
ee4512ed JH |
1 | #ifndef TRACE2_H |
2 | #define TRACE2_H | |
3 | ||
4 | struct child_process; | |
5 | struct repository; | |
6 | struct 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 | */ | |
37 | void 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 | */ | |
47 | void 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 | */ | |
54 | int trace2_is_enabled(void); | |
55 | ||
56 | /* | |
57 | * Emit a 'start' event with the original (unmodified) argv. | |
58 | */ | |
59 | void 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 | */ | |
72 | int 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 | */ | |
81 | void 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 | */ | |
93 | void 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 | */ | |
102 | void 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 | */ | |
112 | void 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 | */ | |
119 | void 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 | */ | |
141 | void 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 | */ | |
152 | void 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 | */ | |
165 | void 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 | */ | |
173 | void 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 | */ | |
188 | int 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 | */ | |
201 | void 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 | */ | |
213 | void 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 | */ | |
224 | void 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 | */ | |
235 | void 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 | */ | |
247 | void 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 | */ | |
259 | void 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 | ||
265 | void 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 | ||
274 | void 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))) | |
286 | void 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 | */ | |
299 | void 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 | ||
305 | void 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 | ||
314 | void 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))) | |
326 | void 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 | */ | |
341 | void 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 | ||
349 | void 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 | ||
357 | void 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 | */ | |
373 | void 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 | ||
379 | void 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))) | |
386 | void 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 | |
397 | enum trace2_process_info_reason { | |
398 | TRACE2_PROCESS_INFO_STARTUP, | |
399 | TRACE2_PROCESS_INFO_EXIT, | |
400 | }; | |
401 | ||
353d3d77 | 402 | #if defined(GIT_WINDOWS_NATIVE) |
26c6f251 | 403 | void 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 */ |