Commit | Line | Data |
---|---|---|
826d496d | 1 | /* |
b7384347 DG |
2 | * lttng.h |
3 | * | |
4 | * Linux Trace Toolkit Control Library Header File | |
5 | * | |
21cf9b6b | 6 | * Copyright (C) 2011 EfficiOS Inc. |
fac6795d | 7 | * |
ab5be9fa | 8 | * SPDX-License-Identifier: LGPL-2.1-only |
82a3637f | 9 | * |
fac6795d DG |
10 | */ |
11 | ||
73db5be4 DG |
12 | #ifndef LTTNG_H |
13 | #define LTTNG_H | |
fac6795d | 14 | |
048f01ef PP |
15 | #include <lttng/lttng-export.h> |
16 | ||
03b1319d DG |
17 | /* Error codes that can be returned by API calls */ |
18 | #include <lttng/lttng-error.h> | |
19 | ||
1239a312 | 20 | /* Include every LTTng ABI/API available. */ |
a58c490f | 21 | #include <lttng/action/action.h> |
ad63a966 | 22 | #include <lttng/action/list.h> |
a58c490f | 23 | #include <lttng/action/notify.h> |
27993cc2 | 24 | #include <lttng/action/path.h> |
7f4d5b07 | 25 | #include <lttng/action/rate-policy.h> |
bfb2ec6a | 26 | #include <lttng/action/rotate-session.h> |
757c48a2 | 27 | #include <lttng/action/snapshot-session.h> |
58397d0d | 28 | #include <lttng/action/start-session.h> |
931bdbaa | 29 | #include <lttng/action/stop-session.h> |
260625bb | 30 | #include <lttng/channel.h> |
685ad3fc | 31 | #include <lttng/clear-handle.h> |
347f2c91 | 32 | #include <lttng/clear.h> |
a58c490f | 33 | #include <lttng/condition/buffer-usage.h> |
260625bb JR |
34 | #include <lttng/condition/condition.h> |
35 | #include <lttng/condition/evaluation.h> | |
670a26e4 | 36 | #include <lttng/condition/event-rule-matches.h> |
e8360425 | 37 | #include <lttng/condition/session-consumed-size.h> |
c19092cd | 38 | #include <lttng/condition/session-rotation.h> |
685ad3fc | 39 | #include <lttng/constant.h> |
260625bb JR |
40 | #include <lttng/destruction-handle.h> |
41 | #include <lttng/domain.h> | |
42 | #include <lttng/endpoint.h> | |
b99a0cb3 | 43 | #include <lttng/error-query.h> |
48c47564 | 44 | #include <lttng/event-expr.h> |
d28fcdec | 45 | #include <lttng/event-field-value.h> |
7a3dcaf6 | 46 | #include <lttng/event-rule/event-rule.h> |
b47b01d8 | 47 | #include <lttng/event-rule/jul-logging.h> |
85522de5 | 48 | #include <lttng/event-rule/kernel-kprobe.h> |
4f7da553 | 49 | #include <lttng/event-rule/kernel-syscall.h> |
af0818ef | 50 | #include <lttng/event-rule/kernel-tracepoint.h> |
46fd07ac | 51 | #include <lttng/event-rule/kernel-uprobe.h> |
28f23191 JG |
52 | #include <lttng/event-rule/log4j-logging.h> |
53 | #include <lttng/event-rule/python-logging.h> | |
0a23a07d | 54 | #include <lttng/event-rule/user-tracepoint.h> |
347f2c91 | 55 | #include <lttng/event.h> |
260625bb JR |
56 | #include <lttng/handle.h> |
57 | #include <lttng/health.h> | |
685ad3fc | 58 | #include <lttng/kernel-probe.h> |
11927a78 | 59 | #include <lttng/kernel.h> |
11a49e7e JR |
60 | #include <lttng/load.h> |
61 | #include <lttng/location.h> | |
85b05318 | 62 | #include <lttng/log-level-rule.h> |
347f2c91 | 63 | #include <lttng/lttng-error.h> |
a58c490f JG |
64 | #include <lttng/notification/channel.h> |
65 | #include <lttng/notification/notification.h> | |
259c2674 | 66 | #include <lttng/rotation.h> |
260625bb JR |
67 | #include <lttng/save.h> |
68 | #include <lttng/session-descriptor.h> | |
69 | #include <lttng/session.h> | |
70 | #include <lttng/snapshot.h> | |
2d97a006 | 71 | #include <lttng/tracker.h> |
260625bb | 72 | #include <lttng/trigger/trigger.h> |
11a49e7e | 73 | #include <lttng/userspace-probe.h> |
1239a312 | 74 | |
5168918c DG |
75 | #ifdef __cplusplus |
76 | extern "C" { | |
77 | #endif | |
78 | ||
1239a312 | 79 | enum lttng_calibrate_type { |
28f23191 | 80 | LTTNG_CALIBRATE_FUNCTION = 0, |
54c90d10 | 81 | }; |
f3ed775e | 82 | |
c7e35b03 JR |
83 | /* Machine interface output type */ |
84 | enum lttng_mi_output_type { | |
28f23191 | 85 | LTTNG_MI_XML = 1 /* XML output */ |
c7e35b03 JR |
86 | }; |
87 | ||
28f23191 | 88 | #define LTTNG_CALIBRATE_PADDING1 16 |
d0254c7c MD |
89 | struct lttng_calibrate { |
90 | enum lttng_calibrate_type type; | |
8d326ab9 DG |
91 | |
92 | char padding[LTTNG_CALIBRATE_PADDING1]; | |
54c90d10 | 93 | }; |
d0254c7c | 94 | |
048f01ef PP |
95 | /*! |
96 | @brief | |
97 | Returns whether or not liblttng-ctl is able to connect to a | |
98 | listening session daemon. | |
99 | ||
100 | @ingroup api_gen | |
101 | ||
102 | How this function tries to | |
103 | \ref api-gen-sessiond-conn "connect to a session daemon" depends on the | |
104 | current Unix tracing group (initially \c tracing) of the library. Set | |
105 | the tracing group with lttng_set_tracing_group(). | |
106 | ||
107 | @returns | |
108 | @parblock | |
109 | One of: | |
110 | ||
111 | <dl> | |
112 | <dt>1</dt> | |
113 | <dd> | |
114 | liblttng-ctl is able to connect to a session daemon. | |
115 | ||
116 | <dt>0 | |
117 | <dd> | |
118 | liblttng-ctl isn't able to connect to a session daemon. | |
119 | ||
120 | <dt>Negative value | |
121 | <dd> | |
122 | Error: a negative #lttng_error_code enumerator. | |
123 | </dl> | |
124 | @endparblock | |
125 | ||
126 | @sa lttng_set_tracing_group() -- | |
127 | Sets the current Unix tracing group of liblttng-ctl. | |
128 | */ | |
4bd69c5f | 129 | LTTNG_EXPORT extern int lttng_session_daemon_alive(void); |
f3ed775e | 130 | |
048f01ef PP |
131 | /*! |
132 | @brief | |
133 | Sets the current Unix tracing group of liblttng-ctl to \lt_p{group}. | |
134 | ||
135 | @ingroup api_gen | |
136 | ||
137 | How the liblttng-ctl functions | |
138 | \ref api-gen-sessiond-conn "connect to a session daemon" depends on | |
139 | the current Unix tracing group (initially \c tracing) of the library. | |
140 | ||
141 | @param[in] group | |
142 | New Unix tracing group of liblttng-ctl. | |
143 | ||
144 | @returns | |
145 | 0 on success, or a \em negative #lttng_error_code enumerator | |
146 | otherwise. | |
147 | ||
148 | @lt_pre_not_null{group} | |
149 | @pre | |
150 | \lt_p{group} names an existing Unix group. | |
151 | */ | |
152 | LTTNG_EXPORT extern int lttng_set_tracing_group(const char *group); | |
f3ed775e | 153 | |
d9800920 | 154 | /* |
1e46a50f TD |
155 | * This call registers an "outside consumer" for a session and an lttng domain. |
156 | * No consumer will be spawned and all fds/commands will go through the socket | |
157 | * path given (socket_path). | |
d9800920 | 158 | * |
06662f07 DG |
159 | * NOTE that this is not recommended unless you absolutely know what you are |
160 | * doing. | |
161 | * | |
162 | * Return 0 on success else a negative LTTng error code. | |
d9800920 | 163 | */ |
4bd69c5f | 164 | LTTNG_EXPORT extern int lttng_register_consumer(struct lttng_handle *handle, |
28f23191 | 165 | const char *socket_path); |
d9800920 | 166 | |
048f01ef PP |
167 | /*! |
168 | @brief | |
169 | Makes the recording session named \lt_p{session_name} active, | |
170 | starting all the tracers for its | |
171 | \ref api-channel-channel "channels". | |
172 | ||
173 | @ingroup api_session | |
174 | ||
175 | @note | |
176 | An #LTTNG_ACTION_TYPE_START_SESSION trigger action can also activate | |
177 | (start) a recording session. | |
178 | ||
179 | @param[in] session_name | |
180 | Name of the recording session to activate/start. | |
181 | ||
182 | @returns | |
183 | 0 on success, or a \em negative #lttng_error_code enumerator | |
184 | otherwise. | |
185 | ||
186 | @lt_pre_conn | |
187 | @lt_pre_not_null{session_name} | |
188 | @lt_pre_sess_exists{session_name} | |
189 | @lt_pre_sess_inactive{session_name} | |
190 | ||
191 | @sa lttng_stop_tracing() -- | |
192 | Stops a recording session. | |
193 | @sa \lt_man{lttng-start,1} | |
194 | */ | |
4bd69c5f | 195 | LTTNG_EXPORT extern int lttng_start_tracing(const char *session_name); |
f3ed775e | 196 | |
048f01ef PP |
197 | /*! |
198 | @brief | |
199 | Makes the recording session named \lt_p{session_name} inactive, | |
200 | stopping all the tracers for its | |
201 | \ref api-channel-channel "channels", blocking until the operation | |
202 | completes. | |
203 | ||
204 | @ingroup api_session | |
205 | ||
206 | This function blocks until the trace data of the | |
207 | recording session named \lt_p{session_name} is valid. Use | |
208 | lttng_stop_tracing_no_wait() to avoid a blocking call. | |
209 | ||
210 | If LTTng \ref api_session_rotation "archived the current trace chunk" | |
211 | of the recording session named \lt_p{session_name} at least | |
212 | once during its lifetime, then this function renames the current trace | |
213 | chunk subdirectory. Although it's safe to | |
214 | read the content of this renamed subdirectory while the recording | |
215 | session remains inactive, it's \em not a trace chunk archive: you need to | |
216 | \link lttng_destroy_session_ext() destroy\endlink the recording session | |
217 | or a rotation needs to occur to archive it. | |
218 | ||
219 | @note | |
220 | An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also | |
221 | deactivate (stop) a recording session. | |
222 | ||
223 | @param[in] session_name | |
224 | Name of the recording session to deactivate/stop. | |
225 | ||
226 | @returns | |
227 | 0 on success, or a \em negative #lttng_error_code enumerator | |
228 | otherwise. | |
229 | ||
230 | @lt_pre_conn | |
231 | @lt_pre_not_null{session_name} | |
232 | @lt_pre_sess_exists{session_name} | |
233 | @lt_pre_sess_active{session_name} | |
234 | ||
235 | @sa lttng_stop_tracing_no_wait() -- | |
236 | Deactivates a recording session without waiting for the operation | |
237 | to complete. | |
238 | @sa lttng_start_tracing() -- | |
239 | Starts a recording session. | |
240 | @sa \lt_man{lttng-stop,1} | |
241 | */ | |
4bd69c5f | 242 | LTTNG_EXPORT extern int lttng_stop_tracing(const char *session_name); |
f3ed775e | 243 | |
048f01ef PP |
244 | /*! |
245 | @brief | |
246 | Makes the recording session named \lt_p{session_name} inactive, | |
247 | stopping all the tracers for its | |
248 | \ref api-channel-channel "channels" without waiting for the | |
249 | operation to complete. | |
250 | ||
251 | @ingroup api_session | |
252 | ||
253 | Unlike lttng_stop_tracing(), this function does \em not block until | |
254 | the operation is complete: it returns immediately. This | |
255 | means the traces(s) of the recording session might not be valid when | |
256 | this function returns, and there's no way to know when it/they become | |
257 | valid. | |
258 | ||
259 | @note | |
260 | An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also | |
261 | deactivate (stop) a recording session. | |
262 | ||
263 | @param[in] session_name | |
264 | Name of the recording session to deactivate/stop. | |
265 | ||
266 | @returns | |
267 | 0 on success, or a \em negative #lttng_error_code enumerator | |
268 | otherwise. | |
269 | ||
270 | @lt_pre_conn | |
271 | @lt_pre_not_null{session_name} | |
272 | @lt_pre_sess_exists{session_name} | |
273 | @lt_pre_sess_active{session_name} | |
274 | @pre | |
275 | No deactivation operation is in progress for the recording session | |
276 | named \lt_p{session_name}. | |
277 | ||
278 | @sa lttng_stop_tracing() -- | |
279 | Deactivates a recording session, blocking until the operation | |
280 | completes. | |
281 | @sa lttng_start_tracing() -- | |
282 | Starts a recording session. | |
283 | @sa \lt_man{lttng-stop,1} | |
284 | */ | |
4bd69c5f | 285 | LTTNG_EXPORT extern int lttng_stop_tracing_no_wait(const char *session_name); |
38ee087f | 286 | |
d0254c7c | 287 | /* |
b812e5ca PP |
288 | * Deprecated: As of LTTng 2.9, this function always returns |
289 | * -LTTNG_ERR_UND. | |
d0254c7c | 290 | */ |
48a40005 SM |
291 | #pragma GCC diagnostic push |
292 | #pragma GCC diagnostic ignored "-Wshadow" | |
4bd69c5f | 293 | LTTNG_EXPORT extern int lttng_calibrate(struct lttng_handle *handle, |
28f23191 | 294 | struct lttng_calibrate *calibrate); |
48a40005 | 295 | #pragma GCC diagnostic pop |
d0254c7c | 296 | |
00e2e675 | 297 | /* |
a4b92340 DG |
298 | * Set URL for a consumer for a session and domain. |
299 | * | |
300 | * Both data and control URL must be defined. If both URLs are the same, only | |
301 | * the control URL is used even for network streaming. | |
00e2e675 | 302 | * |
a4b92340 DG |
303 | * Default port are 5342 and 5343 respectively for control and data which uses |
304 | * the TCP protocol. | |
06662f07 DG |
305 | * |
306 | * URL format: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH] | |
307 | * | |
308 | * Possible protocols are: | |
309 | * > file://... | |
310 | * Local filesystem full path. | |
311 | * | |
312 | * > net[6]://... | |
313 | * This will use the default network transport layer which is TCP for both | |
314 | * control (PORT1) and data port (PORT2). | |
315 | * | |
316 | * > tcp[6]://... | |
317 | * TCP only streaming. For this one, both data and control URL must be given. | |
318 | * | |
319 | * Return 0 on success else a negative LTTng error code. | |
00e2e675 | 320 | */ |
28f23191 JG |
321 | LTTNG_EXPORT extern int |
322 | lttng_set_consumer_url(struct lttng_handle *handle, const char *control_url, const char *data_url); | |
00e2e675 | 323 | |
048f01ef PP |
324 | /*! |
325 | @brief | |
326 | Returns whether or not you may read the traces of the recording | |
327 | session named \lt_p{session_name}. | |
328 | ||
329 | @ingroup api_session | |
330 | ||
331 | It's not safe to read the traces of a recording session while | |
332 | LTTng is still consuming data from the tracers for its | |
333 | \ref api-channel-channel "channels". | |
334 | ||
335 | This function makes it possible to know when LTTng is done consuming | |
336 | trace data from tracers for the channels of the recording session | |
337 | named \lt_p{session_name}. | |
338 | ||
339 | @param[in] session_name | |
340 | Name of the recording session of which get whether or not | |
341 | you may read its traces. | |
342 | ||
343 | @returns | |
344 | @parblock | |
345 | One of: | |
346 | ||
347 | <dl> | |
348 | <dt>0 | |
349 | <dd> | |
350 | You may read the traces of the recording session named | |
351 | \lt_p{session_name}. | |
352 | ||
353 | This remains true as long as the recording session remains | |
354 | \link lttng_session::enabled inactive\endlink (stopped). | |
355 | ||
356 | <dt>1</dt> | |
357 | <dd> | |
358 | You may \em not read the traces of the recording session named | |
359 | \lt_p{session_name}. | |
360 | ||
361 | <dt>Negative value | |
362 | <dd> | |
363 | Error: a negative #lttng_error_code enumerator. | |
364 | </dl> | |
365 | @endparblock | |
366 | ||
367 | @lt_pre_conn | |
368 | @lt_pre_not_null{session_name} | |
369 | @lt_pre_sess_exists{session_name} | |
370 | @lt_pre_sess_inactive{session_name} | |
371 | */ | |
4bd69c5f | 372 | LTTNG_EXPORT extern int lttng_data_pending(const char *session_name); |
806e2684 | 373 | |
49cddecd KS |
374 | /* |
375 | * Gets the status of the kernel tracer. | |
376 | * | |
377 | * Sets the value of the argument, which must not be null. | |
378 | */ | |
11927a78 JG |
379 | LTTNG_EXPORT extern enum lttng_error_code |
380 | lttng_get_kernel_tracer_status(enum lttng_kernel_tracer_status *status); | |
49cddecd | 381 | |
048f01ef PP |
382 | /*! |
383 | @brief | |
384 | Regenerates the metadata streams of the recording session named | |
385 | \lt_p{session_name}. | |
386 | ||
387 | @ingroup api_session | |
388 | ||
389 | @deprecated | |
390 | Use lttng_regenerate_metadata(). | |
391 | ||
392 | @param[in] session_name | |
393 | Name of the recording session of which to regenerate the metadata | |
394 | streams. | |
395 | ||
396 | @returns | |
397 | 0 on success, or a \em negative #lttng_error_code enumerator | |
398 | otherwise. | |
399 | ||
400 | @lt_pre_conn | |
401 | @lt_pre_not_null{session_name} | |
402 | @lt_pre_sess_exists{session_name} | |
403 | */ | |
404 | /// @cond DEPRECATED | |
405 | LTTNG_DEPRECATED() | |
406 | /// @endcond | |
4bd69c5f | 407 | LTTNG_EXPORT extern int lttng_metadata_regenerate(const char *session_name); |
eded6438 | 408 | |
048f01ef PP |
409 | /*! |
410 | @brief | |
411 | Regenerates the metadata streams of the recording session named | |
412 | \lt_p{session_name}. | |
413 | ||
414 | @ingroup api_session | |
415 | ||
416 | Use this function to resample the offset between the monotonic clock and | |
417 | the wall time of the system, and then regenerate (overwrite) all the | |
418 | metadata stream files (local or remote) of the recording session | |
419 | named \lt_p{session_name}. | |
420 | ||
421 | More specifically, you may want to resample the wall time following a | |
422 | major <a href="https://en.wikipedia.org/wiki/Network_Time_Protocol">NTP</a> | |
423 | correction. As such, LTTng can trace a system booting with an incorrect | |
424 | wall time before its wall time is NTP-corrected. Regenerating the | |
425 | metadata of a recording session ensures that trace readers | |
426 | can accurately determine the event record timestamps relative to the | |
427 | Unix epoch. | |
428 | ||
429 | Note that if you plan to \ref api_session_rotation "rotate" the | |
430 | recording session named \lt_p{session_name}, this function only | |
431 | regenerates the metadata stream files of the \em current and \em next | |
432 | trace chunks. | |
433 | ||
434 | See the preconditions of this function which show important limitations. | |
435 | ||
436 | @param[in] session_name | |
437 | Name of the recording session of which to regenerate the metadata | |
438 | streams. | |
439 | ||
440 | @returns | |
441 | 0 on success, or a \em negative #lttng_error_code enumerator | |
442 | otherwise. | |
443 | ||
444 | @lt_pre_conn | |
445 | @lt_pre_not_null{session_name} | |
446 | @lt_pre_sess_exists{session_name} | |
447 | @pre | |
448 | The recording session named \lt_p{session_name} was \em not created | |
449 | in \ref api-session-live-mode "live mode". | |
450 | @pre | |
451 | All the \ref api-channel-channel "channels" of the recording session | |
452 | named \lt_p{session_name} use a | |
453 | \ref api-channel-per-user-buf "per-user buffering scheme". | |
454 | ||
455 | @sa lttng_regenerate_statedump() -- | |
456 | Regenerates the state dump event records of a recording session. | |
457 | @sa \lt_man{lttng-regenerate,1} | |
458 | */ | |
4bd69c5f | 459 | LTTNG_EXPORT extern int lttng_regenerate_metadata(const char *session_name); |
93ec662e | 460 | |
048f01ef PP |
461 | /*! |
462 | @brief | |
463 | Regenerates the state dump event records of the recording session | |
464 | named \lt_p{session_name}. | |
465 | ||
466 | @ingroup api_session | |
467 | ||
468 | Use this function to collect up-to-date state dump information and | |
469 | append corresponding event records to the | |
470 | \ref api-channel-channel "sub-buffers" of the recording session named | |
471 | \lt_p{session_name}. | |
472 | ||
473 | This is particularly useful if you created the recording session in | |
474 | \ref api-session-snapshot-mode "snapshot mode" | |
475 | or if LTTng \ref api_session_rotation "rotates" trace files for one of | |
476 | its \ref api-channel-channel "channels": in both cases, the state dump | |
477 | information may be lost. | |
478 | ||
479 | @param[in] session_name | |
480 | Name of the recording session of which to regenerate the | |
481 | state dump event records. | |
482 | ||
483 | @returns | |
484 | 0 on success, or a \em negative #lttng_error_code enumerator | |
485 | otherwise. | |
486 | ||
487 | @lt_pre_conn | |
488 | @lt_pre_not_null{session_name} | |
489 | @lt_pre_sess_exists{session_name} | |
490 | ||
491 | @sa lttng_regenerate_metadata() -- | |
492 | Regenerates the metadata streams of a recording session. | |
493 | @sa \lt_man{lttng-regenerate,1} | |
494 | */ | |
4bd69c5f | 495 | LTTNG_EXPORT extern int lttng_regenerate_statedump(const char *session_name); |
c2561365 | 496 | |
5168918c DG |
497 | #ifdef __cplusplus |
498 | } | |
499 | #endif | |
500 | ||
73db5be4 | 501 | #endif /* LTTNG_H */ |