]>
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 | ||
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 | */ | |
29 | void 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 | */ | |
36 | int trace2_is_enabled(void); | |
37 | ||
38 | /* | |
39 | * Emit a 'start' event with the original (unmodified) argv. | |
40 | */ | |
41 | void 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 | */ | |
54 | int 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 | */ | |
63 | void 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 | */ | |
75 | void 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 | */ | |
84 | void 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 | */ | |
94 | void 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 | */ | |
101 | void 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 | */ | |
122 | void 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 | */ | |
133 | void 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 | */ | |
146 | void 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 | */ | |
154 | void 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 | */ | |
169 | int 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 | */ | |
182 | void 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 | */ | |
194 | void 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 | */ | |
205 | void 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 | */ | |
216 | void 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 | */ | |
228 | void 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 | */ | |
240 | void 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 | ||
246 | void 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 | ||
255 | void 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))) | |
267 | void 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 | */ | |
280 | void 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 | ||
286 | void 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 | ||
295 | void 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))) | |
307 | void 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 | */ | |
322 | void 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 | ||
330 | void 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 | ||
338 | void 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 | */ | |
354 | void 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 | ||
360 | void 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))) | |
367 | void 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) | |
378 | void 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 */ |