4 * Linux Trace Toolkit Control Library Header File
6 * Copyright (C) 2011 EfficiOS Inc.
8 * SPDX-License-Identifier: LGPL-2.1-only
15 #include <lttng/lttng-export.h>
17 /* Error codes that can be returned by API calls */
18 #include <lttng/lttng-error.h>
20 /* Include every LTTng ABI/API available. */
21 #include <lttng/action/action.h>
22 #include <lttng/action/list.h>
23 #include <lttng/action/notify.h>
24 #include <lttng/action/path.h>
25 #include <lttng/action/rate-policy.h>
26 #include <lttng/action/rotate-session.h>
27 #include <lttng/action/snapshot-session.h>
28 #include <lttng/action/start-session.h>
29 #include <lttng/action/stop-session.h>
30 #include <lttng/channel.h>
31 #include <lttng/clear-handle.h>
32 #include <lttng/clear.h>
33 #include <lttng/condition/buffer-usage.h>
34 #include <lttng/condition/condition.h>
35 #include <lttng/condition/evaluation.h>
36 #include <lttng/condition/event-rule-matches.h>
37 #include <lttng/condition/session-consumed-size.h>
38 #include <lttng/condition/session-rotation.h>
39 #include <lttng/constant.h>
40 #include <lttng/destruction-handle.h>
41 #include <lttng/domain.h>
42 #include <lttng/endpoint.h>
43 #include <lttng/error-query.h>
44 #include <lttng/event-expr.h>
45 #include <lttng/event-field-value.h>
46 #include <lttng/event-rule/event-rule.h>
47 #include <lttng/event-rule/jul-logging.h>
48 #include <lttng/event-rule/kernel-kprobe.h>
49 #include <lttng/event-rule/kernel-syscall.h>
50 #include <lttng/event-rule/kernel-tracepoint.h>
51 #include <lttng/event-rule/kernel-uprobe.h>
52 #include <lttng/event-rule/log4j-logging.h>
53 #include <lttng/event-rule/python-logging.h>
54 #include <lttng/event-rule/user-tracepoint.h>
55 #include <lttng/event.h>
56 #include <lttng/handle.h>
57 #include <lttng/health.h>
58 #include <lttng/kernel-probe.h>
59 #include <lttng/kernel.h>
60 #include <lttng/load.h>
61 #include <lttng/location.h>
62 #include <lttng/log-level-rule.h>
63 #include <lttng/lttng-error.h>
64 #include <lttng/notification/channel.h>
65 #include <lttng/notification/notification.h>
66 #include <lttng/rotation.h>
67 #include <lttng/save.h>
68 #include <lttng/session-descriptor.h>
69 #include <lttng/session.h>
70 #include <lttng/snapshot.h>
71 #include <lttng/tracker.h>
72 #include <lttng/trigger/trigger.h>
73 #include <lttng/userspace-probe.h>
79 enum lttng_calibrate_type
{
80 LTTNG_CALIBRATE_FUNCTION
= 0,
83 /* Machine interface output type */
84 enum lttng_mi_output_type
{
85 LTTNG_MI_XML
= 1 /* XML output */
88 #define LTTNG_CALIBRATE_PADDING1 16
89 struct lttng_calibrate
{
90 enum lttng_calibrate_type type
;
92 char padding
[LTTNG_CALIBRATE_PADDING1
];
97 Returns whether or not liblttng-ctl is able to connect to a
98 listening session daemon.
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().
114 liblttng-ctl is able to connect to a session daemon.
118 liblttng-ctl isn't able to connect to a session daemon.
122 Error: a negative #lttng_error_code enumerator.
126 @sa lttng_set_tracing_group() --
127 Sets the current Unix tracing group of liblttng-ctl.
129 LTTNG_EXPORT
extern int lttng_session_daemon_alive(void);
133 Sets the current Unix tracing group of liblttng-ctl to \lt_p{group}.
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.
142 New Unix tracing group of liblttng-ctl.
145 0 on success, or a \em negative #lttng_error_code enumerator
148 @lt_pre_not_null{group}
150 \lt_p{group} names an existing Unix group.
152 LTTNG_EXPORT
extern int lttng_set_tracing_group(const char *group
);
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).
159 * NOTE that this is not recommended unless you absolutely know what you are
162 * Return 0 on success else a negative LTTng error code.
164 LTTNG_EXPORT
extern int lttng_register_consumer(struct lttng_handle
*handle
,
165 const char *socket_path
);
169 Makes the recording session named \lt_p{session_name} active,
170 starting all the tracers for its
171 \ref api-channel-channel "channels".
176 An #LTTNG_ACTION_TYPE_START_SESSION trigger action can also activate
177 (start) a recording session.
179 @param[in] session_name
180 Name of the recording session to activate/start.
183 0 on success, or a \em negative #lttng_error_code enumerator
187 @lt_pre_not_null{session_name}
188 @lt_pre_sess_exists{session_name}
189 @lt_pre_sess_inactive{session_name}
191 @sa lttng_stop_tracing() --
192 Stops a recording session.
193 @sa \lt_man{lttng-start,1}
195 LTTNG_EXPORT
extern int lttng_start_tracing(const char *session_name
);
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
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.
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.
220 An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
221 deactivate (stop) a recording session.
223 @param[in] session_name
224 Name of the recording session to deactivate/stop.
227 0 on success, or a \em negative #lttng_error_code enumerator
231 @lt_pre_not_null{session_name}
232 @lt_pre_sess_exists{session_name}
233 @lt_pre_sess_active{session_name}
235 @sa lttng_stop_tracing_no_wait() --
236 Deactivates a recording session without waiting for the operation
238 @sa lttng_start_tracing() --
239 Starts a recording session.
240 @sa \lt_man{lttng-stop,1}
242 LTTNG_EXPORT
extern int lttng_stop_tracing(const char *session_name
);
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.
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
260 An #LTTNG_ACTION_TYPE_STOP_SESSION trigger action can also
261 deactivate (stop) a recording session.
263 @param[in] session_name
264 Name of the recording session to deactivate/stop.
267 0 on success, or a \em negative #lttng_error_code enumerator
271 @lt_pre_not_null{session_name}
272 @lt_pre_sess_exists{session_name}
273 @lt_pre_sess_active{session_name}
275 No deactivation operation is in progress for the recording session
276 named \lt_p{session_name}.
278 @sa lttng_stop_tracing() --
279 Deactivates a recording session, blocking until the operation
281 @sa lttng_start_tracing() --
282 Starts a recording session.
283 @sa \lt_man{lttng-stop,1}
285 LTTNG_EXPORT
extern int lttng_stop_tracing_no_wait(const char *session_name
);
288 * Deprecated: As of LTTng 2.9, this function always returns
291 #pragma GCC diagnostic push
292 #pragma GCC diagnostic ignored "-Wshadow"
293 LTTNG_EXPORT
extern int lttng_calibrate(struct lttng_handle
*handle
,
294 struct lttng_calibrate
*calibrate
);
295 #pragma GCC diagnostic pop
298 * Set URL for a consumer for a session and domain.
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.
303 * Default port are 5342 and 5343 respectively for control and data which uses
306 * URL format: proto://[HOST|IP][:PORT1[:PORT2]][/TRACE_PATH]
308 * Possible protocols are:
310 * Local filesystem full path.
313 * This will use the default network transport layer which is TCP for both
314 * control (PORT1) and data port (PORT2).
317 * TCP only streaming. For this one, both data and control URL must be given.
319 * Return 0 on success else a negative LTTng error code.
321 LTTNG_EXPORT
extern int
322 lttng_set_consumer_url(struct lttng_handle
*handle
, const char *control_url
, const char *data_url
);
326 Returns whether or not you may read the traces of the recording
327 session named \lt_p{session_name}.
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".
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}.
339 @param[in] session_name
340 Name of the recording session of which get whether or not
341 you may read its traces.
350 You may read the traces of the recording session named
353 This remains true as long as the recording session remains
354 \link lttng_session::enabled inactive\endlink (stopped).
358 You may \em not read the traces of the recording session named
363 Error: a negative #lttng_error_code enumerator.
368 @lt_pre_not_null{session_name}
369 @lt_pre_sess_exists{session_name}
370 @lt_pre_sess_inactive{session_name}
372 LTTNG_EXPORT
extern int lttng_data_pending(const char *session_name
);
375 * Gets the status of the kernel tracer.
377 * Sets the value of the argument, which must not be null.
379 LTTNG_EXPORT
extern enum lttng_error_code
380 lttng_get_kernel_tracer_status(enum lttng_kernel_tracer_status
*status
);
384 Regenerates the metadata streams of the recording session named
390 Use lttng_regenerate_metadata().
392 @param[in] session_name
393 Name of the recording session of which to regenerate the metadata
397 0 on success, or a \em negative #lttng_error_code enumerator
401 @lt_pre_not_null{session_name}
402 @lt_pre_sess_exists{session_name}
407 LTTNG_EXPORT
extern int lttng_metadata_regenerate(const char *session_name
);
411 Regenerates the metadata streams of the recording session named
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}.
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
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
434 See the preconditions of this function which show important limitations.
436 @param[in] session_name
437 Name of the recording session of which to regenerate the metadata
441 0 on success, or a \em negative #lttng_error_code enumerator
445 @lt_pre_not_null{session_name}
446 @lt_pre_sess_exists{session_name}
448 The recording session named \lt_p{session_name} was \em not created
449 in \ref api-session-live-mode "live mode".
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".
455 @sa lttng_regenerate_statedump() --
456 Regenerates the state dump event records of a recording session.
457 @sa \lt_man{lttng-regenerate,1}
459 LTTNG_EXPORT
extern int lttng_regenerate_metadata(const char *session_name
);
463 Regenerates the state dump event records of the recording session
464 named \lt_p{session_name}.
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
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.
479 @param[in] session_name
480 Name of the recording session of which to regenerate the
481 state dump event records.
484 0 on success, or a \em negative #lttng_error_code enumerator
488 @lt_pre_not_null{session_name}
489 @lt_pre_sess_exists{session_name}
491 @sa lttng_regenerate_metadata() --
492 Regenerates the metadata streams of a recording session.
493 @sa \lt_man{lttng-regenerate,1}
495 LTTNG_EXPORT
extern int lttng_regenerate_statedump(const char *session_name
);