4 Welcome to the <strong>\lt_api</strong> (liblttng-ctl) documentation!
7 <a href="https://lttng.org/"><em>Linux Trace Toolkit: next generation</em></a>
8 is an open-source software package used for correlated tracing of the
9 Linux kernel, user applications, and user libraries.
11 liblttng-ctl, which is part of the LTTng-tools project, makes it
12 possible to control <a href="https://lttng.org/">LTTng</a> tracing, but
14 \ref api_trigger "receive notifications when specific events occur".
18 The following diagram shows the components of LTTng:
20 @image html plumbing.png "Components of LTTng."
22 As you can see, liblttng-ctl is a bridge between a user application
23 and a session daemon (see \lt_man{lttng-sessiond,8} and
24 \ref api-gen-sessiond-conn "Session daemon connection").
26 The \lt_man{lttng,1} command-line tool which ships with LTTng-tools, for
27 example, uses liblttng-ctl to perform its commands.
30 <a href="https://lttng.org/docs/v\lt_version_maj_min/#doc-plumbing"><em>Components of LTTng</em></a>
31 section of the LTTng Documentation to learn more.
35 This API documentation has three main modules:
37 - The \ref api_session makes it possible to create, manipulate
38 (\ref api_session_snapshot "take a snapshot",
39 \ref api_session_rotation "rotate",
40 \ref api_session_clear "clear", and the rest), and destroy
41 <em>recording sessions</em>.
43 A recording session is a per-Unix user dialogue for everything related
46 A recording session owns \lt_obj_channels which
47 own \lt_obj_rers. Those objects constitute
48 the main configuration of a recording session.
50 - The \ref api_inst_pt makes it possible to get details about the
51 available LTTng tracepoints, Java/Python loggers, and Linux kernel
52 system calls without needing any \lt_obj_session.
54 - The \ref api_trigger makes it possible to create and register
57 A trigger associates a condition to one or more actions: when the
58 condition of a trigger is satisfied, LTTng attempts to execute its
61 This API is fully decoupled from the \ref api_session.
63 Amongst the interesting available trigger conditions and actions
65 \link #LTTNG_CONDITION_TYPE_EVENT_RULE_MATCHES <em>event rule matches</em>\endlink
67 \link #LTTNG_ACTION_TYPE_NOTIFY <em>notify</em>\endlink
68 action. With those, your application can receive an asynchronous
69 message (a notification) when a specified event rule matches
72 The three modules above often refer to the \ref api_gen which offers
73 common enumerations, macros, and functions.
75 See <a href="modules.html">API reference</a> for the complete table
78 <h2>Build with liblttng-ctl</h2>
80 To build an application with liblttng-ctl:
85 Include <code>%lttng/lttng.h</code>:
88 #include <lttng/lttng.h>
92 <a href="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</a>,
93 get the required C flags with:
96 $ pkg-config --cflags lttng-ctl
101 Link your application with <code>liblttng-ctl</code>:
104 $ cc my-app.o ... -llttng-ctl
107 With pkg-config, get the required linker options with:
110 $ pkg-config --libs lttng-ctl
114 @defgroup api_gen General API
116 The general \lt_api offers:
118 - \ref lttng_error_code "Error code enumerators" and lttng_strerror().
120 - \ref api-gen-sessiond-conn "Session daemon connection" functions:
122 - lttng_session_daemon_alive()
123 - lttng_set_tracing_group()
125 <h1>\anchor api-gen-sessiond-conn Session daemon connection</h1>
127 Many functions of the \lt_api require a connection to a listening LTTng
128 session daemon (see \lt_man{lttng-sessiond,8}) to control LTTng tracing.
130 liblttng-ctl connects to a session daemon through a Unix domain socket
131 when you call some of its public functions, \em not when it loads.
133 Each Unix user may have its own independent running session daemon.
134 However, liblttng-ctl must connect to the session daemon of the
135 \c root user (the root session daemon) to control Linux kernel tracing.
137 How liblttng-ctl chooses which session daemon to connect to is as
138 follows, considering \lt_var{U} is the Unix user of the process running
142 <dt>\lt_var{U} is \c root
143 <dd>Connect to the root session daemon.
145 <dt>\lt_var{U} is not \c root
148 <dt>If \lt_var{U} is part of the current liblttng-ctl Unix <em>tracing group</em>
150 Try to connect to the root session daemon.
152 If the root session daemon isn't running, connect to the
153 session daemon of \lt_var{U}.
155 <dt>If \lt_var{U} is not part of the tracing group
157 Connect to the session daemon of \lt_var{U}.
161 The Unix tracing group of the root session daemon is one of:
165 With the <code>\--group=<em>GROUP</em></code> option of the root
168 Exactly <code><em>GROUP</em></code>.
170 In that case, you must call lttng_set_tracing_group(), passing
171 exactly <code><em>GROUP</em></code>, \em before you call a
172 liblttng-ctl function which needs to connect to a session daemon.
175 Without the <code>\--group</code> option of the root
178 Exactly \c tracing (also the default Unix tracing group of
179 liblttng-ctl, therefore you don't need to call
180 lttng_set_tracing_group()).
183 Check that your application can successfully connect to a session daemon
184 with lttng_session_daemon_alive().
186 LTTng-instrumented user applications automatically register to both the
187 root and user session daemons. This makes it possible for both session
188 daemons to list the available instrumented applications and their
189 \ref api_inst_pt "instrumentation points".
191 @defgroup api_session Recording session API
193 A <strong><em>recording session</em></strong> is a stateful dialogue
194 between an application and a session daemon for everything related to
197 Everything that you do when you control LTTng tracers to record events
198 happens within a recording session. In particular, a recording session:
200 - Has its own name, unique for a given session daemon.
202 - Has its own set of trace files, if any.
204 - Has its own state of
205 \link lttng_session::enabled activity\endlink (started or stopped).
207 An active recording session is an implicit
208 \lt_obj_rer condition.
210 - Has its own \ref api-session-modes "mode"
211 (local, network streaming, snapshot, or live).
213 - Has its own \lt_obj_channels to which are attached
214 their own recording event rules.
216 - Has its own \ref api_pais "process attribute inclusion sets".
218 Those attributes and objects are completely isolated between different
221 A recording session is like an
222 <a href="https://en.wikipedia.org/wiki/Automated_teller_machine">ATM</a>
223 session: the operations you do on the
224 banking system through the ATM don't alter the data of other users of
225 the same system. In the case of the ATM, a session lasts as long as your
226 bank card is inside. In the case of LTTng, a recording session lasts
227 from a call to lttng_create_session_ext() to the completion of its
228 destruction operation (which you can initiate with
229 lttng_destroy_session_ext()).
231 A recording session belongs to a session daemon (see
232 \lt_man{lttng-sessiond,8} and
233 \ref api-gen-sessiond-conn "Session daemon connection"). For a given
234 session daemon, each Unix user has its own, private recording sessions.
235 Note, however, that the \c root Unix user may operate on or destroy
236 another user's recording session.
238 @image html many-sessions.png "Each Unix user has its own, private recording sessions."
240 @sa The <em>RECORDING SESSION</em> section of \lt_man{lttng-concepts,7}.
244 The recording session operations are:
253 -# Create a \lt_obj_session_descr
254 with one of the dedicated creation functions depending on the
255 \ref api-session-modes "recording session mode".
257 -# Call lttng_create_session_ext(), passing the recording session
258 descriptor of step 1.
260 -# When you're done with the recording session descriptor, destroy
261 it with lttng_session_descriptor_destroy().
263 @sa \lt_man{lttng-create,1}
267 -# Call lttng_destroy_session_ext(), passing the name of the
268 recording session to destroy.
270 This function initiates a destruction operation, returning
273 This function can set a pointer to a
274 \ref api_session_destr_handle "destruction handle"
275 (#lttng_destruction_handle) so that you can wait for the
276 completion of the operation. Without such a handle, you can't
277 know when the destruction operation completes and whether or
278 not it does successfully.
280 -# <strong>If you have a destruction handle from
281 step 1</strong>:
283 -# Call lttng_destruction_handle_wait_for_completion() to wait
284 for the completion of the destruction operation.
286 -# Call lttng_destruction_handle_get_result() to get whether or
287 not the destruction operation successfully completed.
290 lttng_destruction_handle_get_rotation_state() and
291 lttng_destruction_handle_get_archive_location() at this
294 -# Destroy the destruction handle with
295 lttng_destruction_handle_destroy().
297 @sa \lt_man{lttng-destroy,1}
299 <td>Basic property access
303 - The members of #lttng_session
304 - lttng_session_descriptor_get_session_name()
305 - lttng_session_get_creation_time()
306 - lttng_set_session_shm_path()
307 - lttng_data_pending()
309 <td>\lt_obj_c_domain access
311 -# Call lttng_list_domains(), passing the name of the recording
312 session of which to get the tracing domains.
314 This function sets a pointer to an array of
315 \link #lttng_domain tracing domain summaries\endlink
316 and returns the number of entries.
318 -# Access the properties of each tracing domain summary through
321 -# When you're done with the array of tracing domain summaries,
322 free it with <code>free()</code>.
324 <td>\lt_obj_c_channel access
326 -# Create a \link #lttng_handle recording session handle\endlink
327 with lttng_create_handle() to specify the name of the
328 recording session and the summary of the
329 \lt_obj_domain of the channels to access.
331 -# Call lttng_list_channels(), passing the recording session
332 handle of step 1.
334 This function sets a pointer to an array of
335 \link #lttng_channel channel summaries\endlink
336 and returns the number of entries.
338 -# Destroy the recording session handle of step 1 with
339 lttng_destroy_handle().
341 -# Access the \ref api-channel-channel-props "properties" of each
342 channel summary through structure members or using dedicated
345 -# When you're done with the array of channel summaries,
346 free it with <code>free()</code>.
352 - lttng_start_tracing()
353 - lttng_stop_tracing()
354 - lttng_stop_tracing_no_wait()
356 The #LTTNG_ACTION_TYPE_START_SESSION and
357 #LTTNG_ACTION_TYPE_STOP_SESSION trigger actions can also
358 activate and deactivate a recording session.
362 -# Call lttng_list_sessions().
364 This function sets a pointer to an array of
365 \link #lttng_session recording session summaries\endlink
366 and returns the number of entries.
368 -# Access the properties of each recording session summary through
369 structure members or using dedicated getters.
371 -# When you're done with the array of recording session summaries,
372 free it with <code>free()</code>.
374 @sa \lt_man{lttng-list,1}
376 <td>Process attribute inclusion set access
377 <td>See \ref api_pais
380 <td>See \ref api_session_clear
382 <td>Snapshot recording
384 See \ref api_session_snapshot
386 The #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger action can also
387 take a recording session snapshot.
391 See \ref api_session_rotation
393 The #LTTNG_ACTION_TYPE_ROTATE_SESSION trigger action can also
394 rotate a recording session.
396 <td>Saving and loading
397 <td>See \ref api_session_save_load
399 <td>Trace data regeneration
403 - lttng_regenerate_metadata()
404 - lttng_regenerate_statedump()
406 @sa \lt_man{lttng-regenerate,1}
409 <h1>\anchor api-session-modes Recording session modes</h1>
411 LTTng offers four <strong><em>recording session modes</em></strong>:
417 <th>Descriptor creation function(s)
419 <td>\anchor api-session-local-mode Local
421 Write the trace data to the local file system, or do not write any
424 - lttng_session_descriptor_create()
425 - lttng_session_descriptor_local_create()
427 <td>\anchor api-session-net-mode Network streaming
429 Send the trace data over the network to a listening relay daemon
430 (see \lt_man{lttng-relayd,8}).
431 <td>lttng_session_descriptor_network_create()
433 <td>\anchor api-session-snapshot-mode Snapshot
435 Only write the trace data to the local file system or send it to a
436 listening relay daemon when LTTng
437 takes a \ref api_session_snapshot "snapshot".
439 LTTng takes a snapshot of such a recording session when:
441 - You call lttng_snapshot_record().
443 - LTTng executes an #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger
447 \ref api-channel-er-loss-mode "event record loss mode" of all
448 the channels of such a recording session to be
449 \"\ref api-channel-overwrite-mode "overwrite"\".
451 - lttng_session_descriptor_snapshot_create()
452 - lttng_session_descriptor_snapshot_local_create()
453 - lttng_session_descriptor_snapshot_network_create()
455 <td>\anchor api-session-live-mode Live
457 Send the trace data over the network to a listening relay daemon
460 An LTTng live reader (for example,
461 <a href="https://babeltrace.org/">Babeltrace 2</a>) can
462 connect to the same relay daemon to receive trace data while the
463 recording session is active.
465 lttng_session_descriptor_live_network_create()
468 @sa The <em>Recording session modes</em> section of
469 \lt_man{lttng-concepts,7}.
471 <h1>\anchor api-session-url Output URL format</h1>
473 Some functions of the \lt_api require an <strong><em>output
476 An output URL is a C string which specifies where to send trace
477 data and, when LTTng connects to a relay daemon (see
478 \lt_man{lttng-relayd,8}), control commands.
480 There are three available output URL formats:
488 <td>\anchor api-session-local-url Local
490 Send trace data to the local file system, without connecting to a
495 - lttng_create_session() (deprecated)
496 - lttng_create_session_snapshot() (deprecated)
497 - lttng_snapshot_output_set_local_path()
498 - lttng_save_session_attr_set_output_url()
499 - lttng_load_session_attr_set_input_url()
500 - lttng_load_session_attr_set_override_url()
502 <code>file://<em>TRACEDIR</em></code>
505 <dt><code><em>TRACEDIR</em></code>
507 Absolute path to the directory containing the trace data on
508 the local file system.
511 <td>\anchor api-session-one-port-url Remote: single port
513 Send trace data and/or control commands to a specific relay daemon
514 with a specific TCP port.
518 - lttng_session_descriptor_network_create()
519 - lttng_session_descriptor_snapshot_network_create()
520 - lttng_session_descriptor_live_network_create()
521 - lttng_snapshot_output_set_network_urls()
522 - lttng_snapshot_output_set_ctrl_url()
523 - lttng_snapshot_output_set_data_url()
524 - lttng_load_session_attr_set_override_ctrl_url()
525 - lttng_load_session_attr_set_override_data_url()
527 <code><em>PROTO</em>://<em>HOST</em></code>[<code>:<em>PORT</em></code>][<code>/<em>TRACEDIR</em></code>]
530 <dt><code><em>PROTO</em></code>
532 Network protocol, amongst:
545 Same as <code>net</code>.
549 Same as <code>net6</code>.
552 <dt><code><em>HOST</em></code>
554 Hostname or IP address.
556 An IPv6 address must be enclosed in square brackets (<code>[</code>
557 and <code>]</code>); see
558 <a href="https://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>.
560 <dt><code><em>PORT</em></code>
564 If it's missing, the default control and data ports are
565 respectively \lt_def_net_ctrl_port and
566 \lt_def_net_data_port.
568 <dt><code><em>TRACEDIR</em></code>
570 Path of the directory containing the trace data on the remote
573 This path is relative to the base output directory of the
574 LTTng relay daemon (see the <em>Output directory</em>
575 section of \lt_man{lttng-relayd,8}).
578 <td>\anchor api-session-two-port-url Remote: control and data ports
580 Send trace data and control commands to a specific relay daemon
581 with specific TCP ports.
583 This form is usually a shorthand for two
584 \ref api-session-one-port-url "single-port output URLs" with
589 - lttng_create_session_snapshot() (deprecated)
590 - lttng_create_session_live() (deprecated)
591 - lttng_session_descriptor_network_create()
592 - lttng_session_descriptor_snapshot_network_create()
593 - lttng_session_descriptor_live_network_create()
594 - lttng_snapshot_output_set_network_url()
595 - lttng_snapshot_output_set_network_urls()
596 - lttng_snapshot_output_set_ctrl_url()
597 - lttng_load_session_attr_set_override_url()
598 - lttng_load_session_attr_set_override_ctrl_url()
600 <code><em>PROTO</em>://<em>HOST</em>:<em>CTRLPORT</em>:<em>DATAPORT</em></code>[<code>/<em>TRACEDIR</em></code>]
603 <dt><code><em>PROTO</em></code>
605 Network protocol, amongst:
618 Same as <code>net</code>.
622 Same as <code>net6</code>.
625 <dt><code><em>HOST</em></code>
627 Hostname or IP address.
629 An IPv6 address must be enclosed in square brackets (<code>[</code>
630 and <code>]</code>); see
631 <a href="https://www.ietf.org/rfc/rfc2732.txt">RFC 2732</a>.
633 <dt><code><em>CTRLPORT</em></code>
637 <dt><code><em>DATAPORT</em></code>
641 <dt><code><em>TRACEDIR</em></code>
643 Path of the directory containing the trace data on the remote
646 This path is relative to the base output directory of the
647 LTTng relay daemon (see the <code>\--output</code> option of
648 \lt_man{lttng-relayd,8}).
652 @defgroup api_session_descr Recording session descriptor API
655 A <strong><em>recording session descriptor</em></strong> describes the
656 properties of a \lt_obj_session to be (not created
659 To create a recording session from a recording session descriptor:
661 -# Create a recording session descriptor
662 with one of the dedicated creation functions, depending on the
663 \ref api-session-modes "recording session mode":
666 <dt>\ref api-session-local-mode "Local mode"
670 - lttng_session_descriptor_create()
671 - lttng_session_descriptor_local_create()
673 <dt>\ref api-session-net-mode "Network streaming mode"
675 lttng_session_descriptor_network_create()
677 <dt>\ref api-session-snapshot-mode "Snapshot mode"
681 - lttng_session_descriptor_snapshot_create()
682 - lttng_session_descriptor_snapshot_local_create()
683 - lttng_session_descriptor_snapshot_network_create()
685 <dt>\ref api-session-live-mode "Live mode"
687 lttng_session_descriptor_live_network_create()
690 -# Call lttng_create_session_ext(), passing the recording session
691 descriptor of step 1.
693 After a successful call to this function, you can call
694 lttng_session_descriptor_get_session_name() to get the name of the
695 created recording session (set when creating the descriptor or
696 automatically generated).
698 -# When you're done with the recording session descriptor, destroy
699 it with lttng_session_descriptor_destroy().
701 @defgroup api_session_destr_handle Recording session destruction handle API
704 A <strong><em>recording session destruction handle</em></strong>
705 represents a \lt_obj_session destruction operation.
707 The main purposes of a recording session destruction handle is to:
709 - Wait for the completion of the recording session
710 destruction operation with
711 lttng_destruction_handle_wait_for_completion() and get whether or not
712 it was successful with lttng_destruction_handle_get_result().
714 - Get the state of any
715 \ref api_session_rotation "recording session rotation"
716 which the recording session destruction operation caused
717 with lttng_destruction_handle_get_rotation_state(), and the location
718 of its trace chunk archive with
719 lttng_destruction_handle_get_archive_location().
721 To destroy a recording session:
723 -# Call lttng_destroy_session_ext(), passing the name of the recording
726 This function initiates a destruction operation, returning
729 This function can set a pointer to a
730 \link #lttng_destruction_handle destruction handle\endlink so that
731 you can wait for the completion of the operation. Without such a
732 handle, you can't know when the destruction operation completes and
733 whether or not it does successfully.
735 -# Call lttng_destruction_handle_wait_for_completion() to wait
736 for the completion of the destruction operation.
738 -# Call lttng_destruction_handle_get_result() to get whether or
739 not the destruction operation successfully completed.
741 -# <strong>If LTTng performed at least one
742 \ref api_session_rotation "rotation" of the destroyed recording
743 session</strong>, call lttng_destruction_handle_get_rotation_state()
744 to know whether or not the last rotation was successful and
745 lttng_destruction_handle_get_archive_location() to get the location
746 of its trace chunk archive.
748 -# Destroy the destruction handle with
749 lttng_destruction_handle_destroy().
751 @defgroup api_channel Domain and channel API
754 <h1>\anchor api-channel-domain Tracing domain</h1>
756 A <strong><em>tracing domain</em></strong> identifies a type of LTTng
759 A tracing domain has its own properties and features.
761 There are currently five available tracing domains:
769 <td>#LTTNG_DOMAIN_KERNEL
772 <td>#LTTNG_DOMAIN_UST
774 <td><a href="https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html"><code>java.util.logging</code></a> (JUL)
775 <td>#LTTNG_DOMAIN_JUL
777 <td><a href="https://logging.apache.org/log4j/1.2/">Apache log4j</a>
778 <td>#LTTNG_DOMAIN_LOG4J
780 <td><a href="https://docs.python.org/3/library/logging.html">Python logging</a>
781 <td>#LTTNG_DOMAIN_PYTHON
784 A \lt_obj_channel is always part of a tracing domain.
786 Many liblttng-ctl functions require a tracing domain type (sometimes
788 \link #lttng_handle recording session handle\endlink)
789 to target specific tracers or to avoid ambiguity. For example, because
790 the Linux kernel and user space tracing domains support named
791 tracepoints as \ref api_inst_pt "instrumentation points", you need to
792 specify a tracing domain when you create a
793 \lt_obj_rer with lttng_enable_event_with_exclusions() because both
794 tracing domains could have LTTng tracepoints sharing the same name.
796 @sa The <em>TRACING DOMAIN</em> section of \lt_man{lttng-concepts,7}.
798 <h1>\anchor api-channel-channel Channel</h1>
800 A <strong><em>channel</em></strong> is an object which is responsible
801 for a set of ring buffers.
803 Each ring buffer is divided into multiple <em>sub-buffers</em>. When a
804 \lt_obj_rer matches an event, LTTng can record it to one or more
805 sub-buffers of one or more channels.
807 A channel is always associated to a \lt_obj_domain.
808 The \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink,
809 \link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink, and
810 \link #LTTNG_DOMAIN_PYTHON Python\endlink tracing
811 domains each have a default channel which you can't configure.
813 Note that the some functions, like lttng_enable_event_with_exclusions(),
814 can automatically create a default channel with sane defaults when no
815 channel exists for the provided \lt_obj_domain.
817 A channel owns \lt_obj_rers.
819 @image html concepts.png "A recording session contains channels that are members of tracing domains and contain recording event rules."
821 You can't destroy a channel.
825 The channel operations are:
834 -# Call lttng_channel_create() with a \lt_obj_domain summary to
835 create an initial channel summary.
837 This function calls lttng_channel_set_default_attr() to set
838 the properties of the created channel summary to default values
839 depending on the tracing domain summary.
841 -# Set the properties of the channel summary of step 1
842 through direct members or with dedicated setters.
844 See the property table below.
846 -# Create a \link #lttng_handle recording session handle\endlink
847 structure to specify the name of the recording session and the
848 tracing domain of the channel to create.
850 -# Call lttng_enable_channel() with the recording session handle
851 of step 3 and the channel summary of step 1
852 o create the channel.
854 -# Destroy the recording session handle with
855 lttng_destroy_handle() and the channel summary with
856 lttng_channel_destroy().
858 @sa \lt_man{lttng-enable-channel,1}
860 <td>Basic property access
862 See the \ref api-channel-channel-props "property table" below.
864 <td>\lt_obj_c_rer access
866 -# Create a \link #lttng_handle recording session handle\endlink
867 with lttng_create_handle() to specify the name of the
868 recording session and the summary of the
869 \lt_obj_domain of the channel of which to get the recording
870 event rule descriptors.
872 -# Call lttng_list_events(), passing the recording session
873 handle of step 1 and a channel name.
875 This function sets a pointer to an array of
876 \link #lttng_event recording event rule descriptors\endlink
877 and returns the number of entries.
879 -# Destroy the recording session handle of step 1 with
880 lttng_destroy_handle().
882 -# Access the properties of each
883 recording event rule descriptor through structure members or
884 using dedicated getters.
886 -# When you're done with the array of recording event rule
887 descriptors, free it with <code>free()</code>.
889 <td>Event record context field adding
891 -# Initialize a #lttng_event_context structure, setting
892 its properties to describe the context field to be added.
894 -# Create a \link #lttng_handle recording session handle\endlink
895 structure to specify the name of the recording session and the
896 tracing domain of the channel to create.
898 -# Call lttng_add_context() with the recording session handle
899 of step 2 and the context field descriptor of step 1,
900 optionally passing the name of the channel to target.
902 -# Destroy the recording session handle with
903 lttng_destroy_handle().
905 @sa \lt_man{lttng-add-context,1}
909 Use lttng_enable_channel().
911 @sa \lt_man{lttng-enable-channel,1}
915 Use lttng_disable_channel().
917 @sa \lt_man{lttng-disable-channel,1}
923 - lttng_channel_get_discarded_event_count()
924 - lttng_channel_get_lost_packet_count()
927 <h2>\anchor api-channel-channel-props Properties</h2>
929 The properties of a channel are:
939 See \ref api-channel-buf-scheme "Buffering scheme".
941 The lttng_domain::buf_type member for the containing tracing
944 All the channels of a given tracing domain share the same
947 <td>Event record loss mode
949 See \ref api-channel-er-loss-mode "Event record loss mode".
951 The lttng_channel_attr::overwrite member.
955 See \ref api-channel-sub-buf-size-count "Sub-buffer size and count".
957 The lttng_channel_attr::subbuf_size member.
961 See \ref api-channel-sub-buf-size-count "Sub-buffer size and count".
963 The lttng_channel_attr::num_subbuf member.
965 <td>Maximum trace file size
967 See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count".
969 The lttng_channel_attr::tracefile_size member.
971 <td>Maximum trace file count
973 See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count".
975 The lttng_channel_attr::tracefile_count member.
977 <td>Read timer period
979 See \ref api-channel-read-timer "Read timer".
981 The lttng_channel_attr::read_timer_interval member.
983 <td>Switch timer period
985 See \ref api-channel-switch-timer "Switch timer".
987 The lttng_channel_attr::switch_timer_interval member.
989 <td>Live timer period
991 See \ref api-channel-live-timer "Live timer".
993 The \lt_p{live_timer_period} parameter of
994 lttng_session_descriptor_live_network_create() when you create
995 the descriptor of a \ref api-session-live-mode "live" recording
996 session to contain the channel.
998 <td>Monitor timer period
1000 See \ref api-channel-monitor-timer "Monitor timer".
1002 - lttng_channel_get_monitor_timer_interval()
1003 - lttng_channel_set_monitor_timer_interval()
1005 <td>Output type (Linux kernel channel)
1007 Whether to use <code>mmap()</code> or <code>splice()</code>.
1009 The lttng_channel_attr::output member.
1011 <td>\anchor api-channel-blocking-timeout Blocking timeout (user space channel)
1013 How long to block (if ever) at the instrumentation point site when
1014 a sub-buffer is not available for applications executed with the
1015 \c LTTNG_UST_ALLOW_BLOCKING environment variable set.
1017 - lttng_channel_get_blocking_timeout()
1018 - lttng_channel_set_blocking_timeout()
1021 All the properties above are immutable once a channel exists.
1023 @sa The <em>CHANNEL AND RING BUFFER</em> section of
1024 \lt_man{lttng-concepts,7}.
1026 <h3>\anchor api-channel-buf-scheme Buffering scheme</h3>
1028 A channel has at least one ring buffer per CPU. LTTng always records an
1029 event to the ring buffer dedicated to the CPU which emits it.
1031 The <strong><em>buffering scheme</em></strong> of a
1032 \link #LTTNG_DOMAIN_UST user space\endlink
1033 channel determines what has its own set of per-CPU
1034 ring buffers, considering \lt_var{U} is the Unix user of the process
1035 running liblttng-ctl:
1039 \anchor api-channel-per-user-buf
1040 \link #LTTNG_BUFFER_PER_UID Per-user buffering\endlink
1042 Allocate one set of ring buffers (one per CPU) shared by all the
1043 instrumented processes of:
1046 <dt>If \lt_var{U} is <code>root</code>
1050 @image html per-user-buffering-root.png
1056 @image html per-user-buffering.png
1060 \anchor api-channel-per-proc-buf
1061 \link #LTTNG_BUFFER_PER_PID Per-process buffering\endlink
1063 Allocate one set of ring buffers (one per CPU) for each
1064 instrumented process of:
1067 <dt>If \lt_var{U} is <code>root</code>
1071 @image html per-process-buffering-root.png
1077 @image html per-process-buffering.png
1081 The per-process buffering scheme tends to consume more memory than the
1082 per-user option because systems generally have more instrumented
1083 processes than Unix users running instrumented processes. However, the
1084 per-process buffering scheme ensures that one process having a high
1085 event throughput won't fill all the shared sub-buffers of the same Unix
1088 The buffering scheme of a Linux kernel (#LTTNG_DOMAIN_KERNEL) channel is
1089 always to allocate a single set of ring buffers for the whole system
1090 (#LTTNG_BUFFER_GLOBAL). This scheme is similar to the
1091 \ref api-channel-per-user-buf "per-user" one, but with a single, global
1092 user "running" the kernel.
1094 To set the buffering scheme of a channel when you create it:
1096 - Set the lttng_domain::buf_type member of the structure which you pass
1097 within the #lttng_handle structure to lttng_enable_channel().
1099 Note that, for a given \lt_obj_session, \em all
1100 the channels of a given \lt_obj_domain must share the same buffering
1103 @sa The <em>Buffering scheme</em> section of \lt_man{lttng-concepts,7}.
1105 <h3>\anchor api-channel-er-loss-mode Event record loss mode</h3>
1107 When LTTng emits an event, LTTng can record it to a specific, available
1108 sub-buffer within the ring buffers of specific channels. When there's no
1109 space left in a sub-buffer, the tracer marks it as consumable and
1110 another, available sub-buffer starts receiving the following event
1111 records. An LTTng consumer daemon eventually consumes the marked
1112 sub-buffer, which returns to the available state.
1114 In an ideal world, sub-buffers are consumed faster than they are filled.
1115 In the real world, however, all sub-buffers can be full at some point,
1116 leaving no space to record the following events.
1118 By default, LTTng-modules and LTTng-UST are <em>non-blocking</em>
1119 tracers: when there's no available sub-buffer to record an event, it's
1120 acceptable to lose event records when the alternative would be to cause
1121 substantial delays in the execution of the instrumented application.
1122 LTTng privileges performance over integrity; it aims at perturbing the
1123 instrumented application as little as possible in order to make the
1124 detection of subtle race conditions and rare interrupt cascades
1127 Since LTTng 2.10, the LTTng user space tracer, LTTng-UST, supports
1128 a <em>blocking mode</em>: see lttng_channel_get_blocking_timeout() and
1129 lttng_channel_set_blocking_timeout().
1131 When it comes to losing event records because there's no available
1132 sub-buffer, or because the blocking timeout of the channel is reached,
1133 the <strong><em>event record loss mode</em></strong> of the channel
1134 determines what to do. The available event record loss modes are:
1137 <dt>\anchor api-channel-discard-mode Discard mode
1139 Drop the newest event records until a sub-buffer becomes available.
1141 This is the only available mode when you specify a blocking timeout
1142 with lttng_channel_set_blocking_timeout().
1144 With this mode, LTTng increments a count of discarded event records
1145 when it discards an event record and saves this count to the trace.
1146 A trace reader can use the saved discarded event record count of the
1147 trace to decide whether or not to perform some analysis even if
1148 trace data is known to be missing.
1150 Get the number of discarded event records of a channel with
1151 lttng_channel_get_discarded_event_count().
1153 <dt>\anchor api-channel-overwrite-mode Overwrite mode
1155 Clear the sub-buffer containing the oldest event records and start
1156 writing the newest event records there.
1158 This mode is sometimes called <em>flight recorder mode</em> because
1160 <a href="https://en.wikipedia.org/wiki/Flight_recorder">flight recorder</a>:
1161 always keep a fixed amount of the latest data. It's also
1162 similar to the roll mode of an oscilloscope.
1164 Since LTTng 2.8, with this mode, LTTng writes to a given
1165 sub-buffer its sequence number within its data stream. With a
1166 \ref api-session-local-mode "local",
1167 \ref api-session-net-mode "network streaming", or
1168 \ref api-session-live-mode "live" recording session, a trace
1169 reader can use such sequence numbers to report discarded packets. A
1170 trace reader can use the saved discarded sub-buffer (packet) count
1171 of the trace to decide whether or not to perform some analysis even
1172 if trace data is known to be missing.
1174 Get the number of discarded packets (sub-buffers) of a channel with
1175 lttng_channel_get_lost_packet_count().
1177 With this mode, LTTng doesn't write to the trace the exact number of
1178 lost event records in the lost sub-buffers.
1181 Which mechanism you should choose depends on your context: prioritize
1182 the newest or the oldest event records in the ring buffer?
1184 Beware that, in overwrite mode, the tracer abandons a <em>whole
1185 sub-buffer</em> as soon as a there's no space left for a new event
1186 record, whereas in discard mode, the tracer only discards the event
1187 record that doesn't fit.
1189 To set the event record loss mode of a channel when you create it:
1191 - Set the lttng_channel_attr::overwrite member of the lttng_channel::attr
1192 member of the structure you pass to lttng_enable_channel().
1194 There are a few ways to decrease your probability of losing event
1196 \ref api-channel-sub-buf-size-count "Sub-buffer size and count" section
1197 shows how to fine-tune the sub-buffer size and count of a channel to
1198 virtually stop losing event records, though at the cost of greater
1201 @sa The <em>Event record loss mode</em> section of
1202 \lt_man{lttng-concepts,7}.
1204 <h3>\anchor api-channel-sub-buf-size-count Sub-buffer size and count</h3>
1206 A channel has one or more ring buffer for each CPU of the target system.
1208 See \ref api-channel-buf-scheme "Buffering scheme" to learn how many
1209 ring buffers of a given channel are dedicated to each CPU depending on
1210 its buffering scheme.
1212 To set the size of each sub-buffer the ring buffers of a channel have
1215 - Set the lttng_channel_attr::subbuf_size member of the
1216 lttng_channel::attr member of the structure you pass to
1217 lttng_enable_channel().
1219 To set the number of sub-buffers each ring buffer of a channel has
1222 - Set the lttng_channel_attr::num_subbuf member of the
1223 lttng_channel::attr member of the structure you pass to
1224 lttng_enable_channel().
1226 Note that LTTng switching the current sub-buffer of a ring buffer
1227 (marking a full one as consumable and switching to an available one for
1228 LTTng to record the next events) introduces noticeable CPU overhead.
1229 Knowing this, the following list presents a few practical situations
1230 along with how to configure the sub-buffer size and count for them:
1233 <dt>High event throughput
1235 In general, prefer large sub-buffers to lower the risk of losing
1238 Having larger sub-buffers also ensures a lower sub-buffer
1239 \ref api-channel-switch-timer "switching frequency".
1241 The sub-buffer count is only meaningful if you create the channel in
1242 \ref api-channel-overwrite-mode "overwrite mode": in this case, if
1243 LTTng overwrites a sub-buffer, then the other sub-buffers are left
1246 <dt>Low event throughput
1248 In general, prefer smaller sub-buffers since the risk of losing
1249 event records is low.
1251 Because LTTng emits events less frequently, the sub-buffer switching
1252 frequency should remain low and therefore the overhead of the tracer
1253 shouldn't be a problem.
1255 <dt>Low memory system
1257 If your target system has a low memory limit, prefer fewer first,
1258 then smaller sub-buffers.
1260 Even if the system is limited in memory, you want to keep the
1261 sub-buffers as large as possible to avoid a high sub-buffer
1262 switching frequency.
1265 Note that LTTng uses <a href="https://diamon.org/ctf/">CTF</a> as its
1266 trace format, which means event record data is very compact. For
1267 example, the average LTTng kernel event record weights about
1268 32 bytes. Therefore, a sub-buffer size of 1 MiB is considered
1271 The previous scenarios highlight the major trade-off between a few large
1272 sub-buffers and more, smaller sub-buffers: sub-buffer switching
1273 frequency vs. how many event records are lost in
1274 \ref api-channel-overwrite-mode "overwrite mode".
1275 Assuming a constant event throughput and using the overwrite mode, the
1276 two following configurations have the same ring buffer total size:
1279 <dt>Two sub-buffers of 4 MiB each
1281 Expect a very low sub-buffer switching frequency, but if LTTng ever
1282 needs to overwrite a sub-buffer, half of the event records so far
1283 (4 MiB) are definitely lost.
1285 <dt>Eight sub-buffers of 1 MiB each
1287 Expect four times the tracer overhead of the configuration above,
1288 but if LTTng needs to overwrite a sub-buffer, only the eighth of
1289 event records so far (1 MiB) are definitely lost.
1292 In \ref api-channel-discard-mode "discard mode", the sub-buffer count
1293 parameter is pointless: use two sub-buffers and set their size according
1294 to your requirements.
1296 @sa The <em>Sub-buffer size and count</em> section of
1297 \lt_man{lttng-concepts,7}.
1299 <h3>\anchor api-channel-max-trace-file-size-count Maximum trace file size and count</h3>
1301 By default, trace files can grow as large as needed.
1303 To set the maximum size of each trace file that LTTng writes from the
1304 ring buffers of a channel when you create it:
1306 - Set the lttng_channel_attr::tracefile_size member of the
1307 lttng_channel::attr member of the structure you pass to
1308 lttng_enable_channel().
1310 When the size of a trace file reaches the fixed maximum size of the
1311 channel, LTTng creates another file to contain the next event records.
1312 LTTng appends a file count to each trace file name in this case.
1314 If you set the trace file size attribute when you create a channel, the
1315 maximum number of trace files that LTTng creates is <em>unlimited</em>
1318 To limit the size of each trace file that LTTng writes from the
1319 ring buffers of a channel when you create it:
1321 - Set the lttng_channel_attr::tracefile_count member of the
1322 lttng_channel::attr member of the structure you pass to
1323 lttng_enable_channel().
1325 When the number of trace files reaches the fixed maximum count of the
1326 channel, LTTng overwrites the oldest trace file. This mechanism is
1327 called <em>trace file rotation</em>.
1331 Even if you don't limit the trace file count, always assume that
1332 LTTng manages all the trace files of the recording session.
1334 In other words, there's no safe way to know if LTTng still holds a
1335 given trace file open with the trace file rotation feature.
1337 The only way to obtain an unmanaged, self-contained LTTng trace
1338 before you \link lttng_destroy_session_ext() destroy the
1339 recording session\endlink is with the
1340 \ref api_session_rotation "recording session rotation" feature,
1341 which is available since LTTng 2.11.
1344 @sa The <em>Maximum trace file size and count</em> section of
1345 \lt_man{lttng-concepts,7}.
1347 <h3>\anchor api-channel-timers Timers</h3>
1349 Each channel can have up to four optional
1350 <strong><em>timers</em></strong>:
1353 <dt>\anchor api-channel-switch-timer Switch timer
1355 When this timer expires, a sub-buffer switch happens: for each ring
1356 buffer of the channel, LTTng marks the current sub-buffer as
1357 consumable and switches to an available one to record the next
1360 A switch timer is useful to ensure that LTTng consumes and commits
1361 trace data to trace files or to a distant relay daemon
1362 (see \lt_man{lttng-relayd,8}) periodically in case of a low event
1365 Such a timer is also convenient when you use
1366 \ref api-channel-sub-buf-size-count "large sub-buffers"
1367 to cope with a sporadic high event throughput, even if the
1368 throughput is otherwise low.
1370 To set the period of the switch timer of a channel when you create
1373 - Set the lttng_channel_attr::switch_timer_interval member of the
1374 lttng_channel::attr member of the structure you pass to
1375 lttng_enable_channel().
1377 A channel only has a switch timer when its
1378 recording session is \em not in
1379 \ref api-session-live-mode "live mode". lttng_enable_channel()
1380 ignores the lttng_channel_attr::switch_timer_interval member with a
1381 live recording session. For a live recording session, the
1382 \ref api-channel-live-timer "live timer" plays the role of the
1385 <dt>\anchor api-channel-live-timer Live timer
1387 Like the \ref api-channel-switch-timer "switch timer", but for a
1388 channel which belongs to a
1389 \ref api-session-live-mode "live" recording session.
1391 If this timer expires but there's no sub-buffer to consume, LTTng
1392 sends a message with a timestamp to the connected relay daemon (see
1393 \lt_man{lttng-relayd,8}) so that its live readers can progress.
1395 To set the period of the live timer of a channel when you create
1396 its recording session:
1398 - Set the \lt_p{live_timer_period} parameter when you call
1399 lttng_session_descriptor_live_network_create() to create a
1400 live recording session descriptor to pass to
1401 lttng_create_session_ext().
1404 All the channels of a live recording session share the same
1407 <dt>\anchor api-channel-read-timer Read timer
1409 When this timer expires, LTTng checks for full, consumable
1412 By default, the LTTng tracers use an asynchronous message mechanism
1413 to signal a full sub-buffer so that a consumer daemon can consume
1416 When such messages must be avoided, for example in real-time
1417 applications, use this timer instead.
1419 To set the period of the read timer of a channel when you create
1422 - Set the lttng_channel_attr::read_timer_interval member of the
1423 lttng_channel::attr member of the structure you pass to
1424 lttng_enable_channel().
1426 <dt>\anchor api-channel-monitor-timer Monitor timer
1428 When this timer expires, the consumer daemon samples some channel
1429 statistics to evaluate the following trigger conditions:
1431 -# The consumed buffer size of a given recording session becomes
1432 greater than some value.
1434 -# The buffer usage of a given channel becomes greater than some
1437 -# The buffer usage of a given channel becomes less than some value.
1439 If you disable the monitor timer of a channel \lt_var{C}:
1441 - The consumed buffer size value of the recording session
1442 of \lt_var{C} could be wrong for trigger condition
1443 type 1: the consumed buffer size of \lt_var{C} won't be
1444 part of the grand total.
1446 - The buffer usage trigger conditions (types 2 and 3)
1447 for \lt_var{C} will never be satisfied.
1449 See \ref api_trigger to learn more about triggers.
1451 To set the period of the monitor timer of a channel when you create
1454 - Call lttng_channel_set_monitor_timer_interval() with the
1455 #lttng_channel structure you pass to lttng_enable_channel().
1458 @sa The <em>Timers</em> section of \lt_man{lttng-concepts,7}.
1460 @defgroup api_rer Recording event rule API
1461 @ingroup api_channel
1465 An <em>instrumentation point</em> is a point, within a piece of
1466 software, which, when executed, creates an LTTng <em>event</em>.
1467 See \ref api_inst_pt to learn how to list the available instrumentation
1470 An <em>event rule</em> is a set of \ref api-rer-conds "conditions" to
1471 match a set of events.
1473 A <strong><em>recording event rule</em></strong> is a specific type of
1474 event rule of which the action is to serialize and write the matched
1475 event as an <em>event record</em> to a sub-buffer of its attached
1478 An event record has a \ref api-rer-er-name "name" and fields.
1480 When LTTng creates an event \lt_var{E}, a recording event
1481 rule \lt_var{ER} is said to <em>match</em> \lt_var{E}
1482 when \lt_var{E} satisfies \em all the conditions
1483 of \lt_var{ER}. This concept is similar to a regular expression
1484 which matches a set of strings.
1486 When a recording event rule matches an event, LTTng \em emits the event,
1487 therefore attempting to record it.
1491 The event creation and emission processes are \em documentation
1492 concepts to help understand the journey from an instrumentation
1493 point to an event record.
1495 The actual creation of an event can be costly because LTTng needs to
1496 evaluate the arguments of the instrumentation point.
1498 In practice, LTTng implements various optimizations for the
1499 \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink and
1500 \link #LTTNG_DOMAIN_UST user space\endlink \lt_obj_domains
1501 to avoid actually creating an event when the tracer knows, thanks to
1502 properties which are independent from the event payload and current
1503 \link #lttng_event_context_type context\endlink, that it would never
1504 emit such an event. Those properties are:
1506 - The \ref api-rer-conds-inst-pt-type "instrumentation point type".
1508 - The \ref api-rer-conds-event-name "instrumentation point name" (or
1511 - The \ref api-rer-conds-ll "instrumentation point log level".
1513 - The \link lttng_event::enabled status\endlink (enabled or
1514 disabled) of the rule itself.
1516 - The \link lttng_channel::enabled status\endlink (enabled or
1517 disabled) of the \lt_obj_channel containing the rule.
1519 - The \link lttng_session::enabled activity\endlink (started or
1520 stopped) of the \lt_obj_session containing the rule.
1522 - Whether or not the process for which LTTng would create the event
1523 is \ref api_pais "allowed to record events".
1525 In other words: if, for a given instrumentation point \lt_var{IP},
1526 the LTTng tracer knows that it would never emit an event,
1527 executing \lt_var{IP} represents a simple boolean variable check
1528 and, for a \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink
1529 \lt_obj_rer, a few current process attribute checks.
1532 You always attach a recording event rule to a
1533 \lt_obj_channel, which belongs to
1534 a \lt_obj_session, when you
1535 \link lttng_enable_event_with_exclusions() create it\endlink.
1536 A channel owns recording event rules.
1538 When multiple matching recording event rules are attached to the same
1539 channel, LTTng attempts to serialize and record the matched event
1542 @image html event-rule.png "Logical path from an instrumentation point to an event record."
1544 As of LTTng-tools \lt_version_maj_min, you cannot remove a
1545 recording event rule: it exists as long as its \lt_obj_session exists.
1549 The recording event rule operations are:
1558 -# Call lttng_event_create() to create an initial
1559 \link #lttng_event recording event rule descriptor\endlink.
1561 -# Set the properties of the recording event rule descriptor of
1562 step 1 through direct members or with dedicated setters.
1564 See the property table below.
1566 -# Create a \link #lttng_handle recording session handle\endlink
1567 structure to specify the name of the recording session and the
1568 tracing domain of the recording event rule to create.
1570 -# Call lttng_enable_event_with_exclusions() with the recording
1571 session handle of step 3, the recording event rule
1572 descriptor of step 1, the name of a
1573 \lt_obj_channel to which to attach the
1574 created recording event rule, and, depending on the selected
1575 function, other properties to create the rule.
1577 -# Destroy the recording session handle with
1578 lttng_destroy_handle() and the recording event rule descriptor
1579 with lttng_event_destroy().
1581 @sa \lt_man{lttng-enable-event,1}
1587 - The members of #lttng_event
1588 - lttng_event_get_userspace_probe_location()
1589 - lttng_event_set_userspace_probe_location()
1590 - lttng_event_get_filter_expression()
1591 - lttng_event_get_exclusion_name_count()
1592 - lttng_event_get_exclusion_name()
1594 @sa \ref api-rer-conds "Recording event rule conditions".
1598 With an #lttng_event instance which comes from
1599 lttng_list_events(), use lttng_enable_event().
1601 Otherwise, use lttng_enable_event_with_exclusions().
1603 @sa \lt_man{lttng-enable-event,1}
1607 Use lttng_disable_event() or lttng_disable_event_ext().
1609 @sa \lt_man{lttng-disable-event,1}
1612 <h1>\anchor api-rer-conds Recording event rule conditions</h1>
1614 For LTTng to emit and record an event \lt_var{E}, \lt_var{E}
1615 must satisfy \em all the conditions of a recording event
1616 rule \lt_var{ER}, that is:
1619 <dt>Explicit conditions
1621 You set the following conditions when you
1622 \link lttng_enable_event_with_exclusions() create\endlink
1623 \lt_var{ER} from some
1624 \link #lttng_event recording event rule descriptor\endlink
1625 \c event_rule (#lttng_event).
1633 \anchor api-rer-conds-inst-pt-type
1634 \ref api-rer-conds-inst-pt-type "Instrumentation point type"
1636 \lt_var{E} satisfies the instrumentation point type condition
1637 of \lt_var{ER} if the instrumentation point from which LTTng
1638 creates \lt_var{E} is, depending on the
1639 \lt_obj_domain which contains \lt_var{ER}:
1642 <dt>#LTTNG_DOMAIN_KERNEL
1645 \link lttng_event::type <code>event_rule.type</code>\endlink:
1648 <dt>#LTTNG_EVENT_TRACEPOINT
1650 An LTTng kernel tracepoint, that is, a statically
1651 defined point in the source code of the kernel image
1652 or of a kernel module with LTTng kernel tracer macros.
1654 @sa lttng_list_tracepoints()
1656 <dt>#LTTNG_EVENT_SYSCALL
1658 The entry and exit of a Linux kernel system call.
1660 @sa lttng_list_syscalls()
1662 <dt>#LTTNG_EVENT_PROBE
1665 <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>,
1666 that is, a single probe dynamically placed in the
1667 compiled kernel code.
1669 \link lttng_event::lttng_event_attr_u::probe
1670 <code>event_rule.attr.probe</code>\endlink
1671 indicates the kprobe location,
1672 while \link lttng_event::name
1673 <code>event_rule.name</code>\endlink
1674 is the name of the created kprobe instrumentation
1675 point (future event name).
1677 The payload of a Linux kprobe event is empty.
1679 <dt>#LTTNG_EVENT_FUNCTION
1682 <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>,
1683 that is, two probes dynamically placed at the entry
1684 and exit of a function in the compiled kernel code.
1686 \link lttng_event::lttng_event_attr_u::probe
1687 <code>event_rule.attr.probe</code>\endlink
1688 indicates the kretprobe location,
1689 while \link lttng_event::name
1690 <code>event_rule.name</code>\endlink
1691 is the name of the created kretprobe instrumentation
1692 point (future event name).
1694 The payload of a Linux kretprobe event is empty.
1696 <dt>#LTTNG_EVENT_USERSPACE_PROBE
1699 <a href="https://lwn.net/Articles/499190/">uprobe</a>,
1700 that is, a single probe dynamically placed at the
1701 entry of a compiled user space application/library
1702 function through the kernel.
1704 Set and get the location of the uprobe with
1705 lttng_event_set_userspace_probe_location() and
1706 lttng_event_get_userspace_probe_location().
1708 \link lttng_event::name <code>event_rule.name</code>\endlink
1709 is the name of the created uprobe instrumentation
1710 point (future event name).
1712 The payload of a Linux uprobe event is empty.
1715 <dt>#LTTNG_DOMAIN_UST
1717 An LTTng user space tracepoint, that is, a statically
1718 defined point in the source code of a C/C++
1719 application/library with LTTng user space tracer macros.
1721 \link lttng_event::type <code>event_rule.type</code>\endlink
1722 must be #LTTNG_EVENT_TRACEPOINT.
1724 @sa lttng_list_tracepoints()
1726 <dt>#LTTNG_DOMAIN_JUL
1727 <dt>#LTTNG_DOMAIN_LOG4J
1728 <dt>#LTTNG_DOMAIN_PYTHON
1730 A Java/Python logging statement.
1732 \link lttng_event::type <code>event_rule.type</code>\endlink
1733 must be #LTTNG_EVENT_TRACEPOINT.
1735 @sa lttng_list_tracepoints()
1739 \anchor api-rer-conds-event-name
1740 \ref api-rer-conds-event-name "Event name"
1742 An event \lt_var{E} satisfies the event name condition
1743 of \lt_var{ER} if the two following statements are
1746 - \link lttng_event::name <code>event_rule.name</code>\endlink
1747 matches, depending on
1748 \link lttng_event::type <code>event_rule.type</code>\endlink
1749 (see \ref api-rer-conds-inst-pt-type "Instrumentation point type"
1753 <dt>#LTTNG_EVENT_TRACEPOINT
1755 The full name of the LTTng tracepoint or Java/Python
1756 logger from which LTTng creates \lt_var{E}.
1758 Note that the full name of a
1759 \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
1760 <code><em>PROVIDER</em>:<em>NAME</em></code>, where
1761 <code><em>PROVIDER</em></code> is the tracepoint
1762 provider name and <code><em>NAME</em></code> is the
1765 <dt>#LTTNG_EVENT_SYSCALL
1767 The name of the system call, without any
1768 <code>sys_</code> prefix, from which LTTng
1769 creates \lt_var{E}.
1772 @sa \ref api-rer-er-name "Event record name".
1774 - If the \lt_obj_domain
1775 containing \lt_var{ER} is #LTTNG_DOMAIN_UST:
1776 none of the event name exclusion patterns of
1777 \c event_rule matches the full name of the user
1778 space tracepoint from which LTTng creates \lt_var{E}.
1780 Set the event name exclusion patterns of
1781 \c event_rule when you call
1782 lttng_enable_event_with_exclusions().
1784 Get the event name exclusion patterns of
1785 a recording event rule descriptor with
1786 lttng_event_get_exclusion_name_count() and
1787 lttng_event_get_exclusion_name().
1789 This condition is only meaningful when
1790 \link lttng_event::type <code>event_rule.type</code>\endlink
1791 is #LTTNG_EVENT_TRACEPOINT or
1792 #LTTNG_EVENT_SYSCALL: it's always satisfied for the other
1793 \ref api-rer-conds-inst-pt-type "instrumentation point types".
1796 \link lttng_event::name <code>event_rule.name</code>\endlink
1797 and the event name exclusion patterns of
1798 \c event_rule are <em>globbing patterns</em>: the
1799 <code>*</code> character means "match anything". To match a
1800 literal <code>*</code> character, use <code>\\*</code>.
1803 \anchor api-rer-conds-ll
1804 \ref api-rer-conds-ll "Instrumentation point log level"
1806 An event \lt_var{E} satisfies the instrumentation point
1807 log level condition of \lt_var{ER} if, depending on
1808 \link lttng_event::loglevel_type <code>event_rule.loglevel_type</code>\endlink,
1809 the log level of the LTTng user space tracepoint or
1810 logging statement from which LTTng creates \lt_var{E}
1814 <dt>#LTTNG_EVENT_LOGLEVEL_ALL
1816 Anything (the condition is always satisfied).
1818 <dt>#LTTNG_EVENT_LOGLEVEL_RANGE
1820 At least as severe as
1821 \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink.
1823 <dt>#LTTNG_EVENT_LOGLEVEL_SINGLE
1826 \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink.
1829 This condition is only meaningful when the \lt_obj_domain
1830 containing \lt_var{ER} is \em not #LTTNG_DOMAIN_KERNEL:
1831 it's always satisfied for #LTTNG_DOMAIN_KERNEL.
1834 \anchor api-rer-conds-filter
1835 \ref api-rer-conds-filter "Event payload and context filter"
1837 An event \lt_var{E} satisfies the event payload and
1838 context filter condition of \lt_var{ER} if
1839 \c event_rule has no filter expression or if its filter
1840 expression \lt_var{EXPR} evaluates to \b true
1841 when LTTng creates \lt_var{E}.
1843 This condition is only meaningful when:
1845 - The \lt_obj_domain containing \lt_var{ER} is
1846 #LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST: it's always
1847 satisfied for the other tracing domains.
1849 - \link lttng_event::type <code>event_rule.type</code>\endlink
1850 is #LTTNG_EVENT_TRACEPOINT or #LTTNG_EVENT_SYSCALL:
1851 it's always satisfied for the other
1852 \ref api-rer-conds-inst-pt-type "instrumentation point types".
1854 Set the event payload and context filter expression of
1855 \c event_rule when you call
1856 lttng_enable_event_with_exclusions().
1858 Get the event payload and context filter expression of
1859 a recording event rule descriptor with
1860 lttng_event_get_filter_expression().
1862 \lt_var{EXPR} can contain references to the payload fields
1863 of \lt_var{E} and to the current
1864 \link #lttng_event_context_type context\endlink fields.
1866 The expected syntax of \lt_var{EXPR} is similar to the syntax
1867 of a C language conditional expression (an expression
1868 which an \c if statement can evaluate), but there are a few
1871 - A <code><em>NAME</em></code> expression identifies an event
1872 payload field named <code><em>NAME</em></code> (a
1875 Use the C language dot and square bracket notations to
1876 access nested structure and array/sequence fields. You can
1877 only use a constant, positive integer number within square
1878 brackets. If the index is out of bounds, \lt_var{EXPR} is
1881 The value of an enumeration field is an integer.
1883 When a field expression doesn't exist, \lt_var{EXPR} is
1886 Examples: <code>my_field</code>, <code>target_cpu</code>,
1887 <code>seq[7]</code>, <code>msg.user[1].data[2][17]</code>.
1889 - A <code>$ctx.<em>TYPE</em></code> expression identifies the
1890 statically-known context field having the type
1891 <code><em>TYPE</em></code> (a C identifier).
1893 When a field expression doesn't exist, \lt_var{EXPR} is \b
1896 Examples: <code>$ctx.prio</code>,
1897 <code>$ctx.preemptible</code>,
1898 <code>$ctx.perf:cpu:stalled-cycles-frontend</code>.
1900 - A <code>$app.<em>PROVIDER</em>:<em>TYPE</em></code>
1901 expression identifies the application-specific context field
1902 having the type <code><em>TYPE</em></code> (a
1903 C identifier) from the provider
1904 <code><em>PROVIDER</em></code> (a C identifier).
1906 When a field expression doesn't exist, \lt_var{EXPR} is \b
1909 Example: <code>$app.server:cur_user</code>.
1911 - Compare strings, either string fields or string literals
1912 (double-quoted), with the <code>==</code> and
1913 <code>!=</code> operators.
1915 When comparing to a string literal, the <code>*</code>
1916 character means "match anything". To match a literal
1917 <code>*</code> character, use <code>\\*</code>.
1919 Examples: <code>my_field == "user34"</code>,
1920 <code>my_field == my_other_field</code>,
1921 <code>my_field == "192.168.*"</code>.
1924 <a href="https://en.wikipedia.org/wiki/Order_of_operations">precedence table</a>
1925 of the operators which are supported in
1926 \lt_var{EXPR} is as follows. In this table, the highest
1927 precedence is 1:
1957 <td><code><<</code>
1958 <td>Bitwise left shift
1962 <td><code>>></code>
1963 <td>Bitwise right shift
1967 <td><code>&</code>
1982 <td><code><</code>
1987 <td><code><=</code>
1988 <td>Less than or equal to
1992 <td><code>></code>
1997 <td><code>>=</code>
1998 <td>Greater than or equal to
2012 <td><code>&&</code>
2022 Parentheses are supported to bypass the default order.
2025 Unlike the C language, the bitwise AND and OR
2026 operators (<code>&</code> and <code>|</code>) in
2027 \lt_var{EXPR} take precedence over relational
2028 operators (<code><<</code>, <code><=</code>,
2029 <code>></code>, <code>>=</code>, <code>==</code>,
2030 and <code>!=</code>). This means the expression
2031 <code>2 & 2 == 2</code>
2032 is \b true while the equivalent C expression
2035 The arithmetic operators are :not: supported.
2037 LTTng first casts all integer constants and fields to signed
2038 64-bit integers. The representation of negative integers is
2039 two's complement. This means that, for example, the signed
2040 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff
2041 (still -1) once casted.
2043 Before a bitwise operator is applied, LTTng casts all its
2044 operands to unsigned 64-bit integers, and then casts the
2045 result back to a signed 64-bit integer. For the bitwise NOT
2046 operator, it's the equivalent of this C expression:
2049 (int64_t) ~((uint64_t) val)
2052 For the binary bitwise operators, it's the equivalent of those
2056 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
2057 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
2058 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
2059 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
2060 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
2063 If the right-hand side of a bitwise shift operator
2064 (<code><<</code> and <code>>></code>) is not in
2065 the [0, 63] range, then \lt_var{EXPR} is \b false.
2068 See the \ref api_pais to allow or disallow processes to
2069 record LTTng events based on their attributes
2070 instead of using equivalent statically-known context
2071 fields in \lt_var{EXPR} like <code>$ctx.pid</code>.
2072 The former method is much more efficient.
2074 \lt_var{EXPR} examples:
2077 msg_id == 23 && size >= 2048
2081 $ctx.procname == "lttng*" && (!flag || poel < 34)
2085 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
2089 $ctx.cpu_id == 2 && filename != "*.log"
2093 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
2097 <dt>Implicit conditions
2099 - \lt_var{ER} itself is \link lttng_event::enabled enabled\endlink.
2101 A recording event rule is enabled on
2102 \link lttng_enable_event_with_exclusions() creation\endlink.
2104 @sa lttng_enable_event() --
2105 Creates or enables a recording event rule.
2106 @sa lttng_disable_event_ext() --
2107 Disables a recording event rule.
2109 - The \lt_obj_channel which contains \lt_var{ER} is
2110 \link lttng_channel::enabled enabled\endlink.
2112 A channel is enabled on
2113 \link lttng_enable_channel() creation\endlink.
2115 @sa lttng_enable_channel() --
2116 Creates or enables a channel.
2117 @sa lttng_disable_channel() --
2120 - The \lt_obj_session which contains \lt_var{ER} is
2121 \link lttng_session::enabled active\endlink (started).
2123 A recording session is inactive (stopped) on
2124 \link lttng_create_session_ext() creation\endlink.
2126 @sa lttng_start_tracing() --
2127 Starts a recording session.
2128 @sa lttng_stop_tracing() --
2129 Stops a recording session.
2131 - The process for which LTTng creates \lt_var{E} is
2132 \ref api_pais "allowed to record events".
2134 All processes are allowed to record events on recording session
2135 \link lttng_create_session_ext() creation\endlink.
2138 <h1>\anchor api-rer-er-name Event record name</h1>
2140 When LTTng records an event \lt_var{E}, the resulting event record
2141 has a name which depends on the
2142 \ref api-rer-conds-inst-pt-type "instrumentation point type condition"
2143 of the recording event rule \lt_var{ER} which matched \lt_var{E}
2144 as well as on the \lt_obj_domain which contains \lt_var{ER}:
2149 <th>Instrumentation point type
2150 <th>Event record name
2152 <td>#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST
2153 <td>#LTTNG_EVENT_TRACEPOINT
2155 Full name of the tracepoint from which LTTng creates \lt_var{E}.
2157 Note that the full name of a
2158 \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
2159 <code><em>PROVIDER</em>:<em>NAME</em></code>, where
2160 <code><em>PROVIDER</em></code> is the tracepoint provider name and
2161 <code><em>NAME</em></code> is the tracepoint name.
2163 <td>#LTTNG_DOMAIN_JUL
2164 <td>#LTTNG_EVENT_TRACEPOINT
2166 <code>lttng_jul:event</code>
2168 Such an event record has a string field <code>logger_name</code>
2169 which contains the name of the <code>java.util.logging</code>
2170 logger from which LTTng creates \lt_var{E}.
2172 <td>#LTTNG_DOMAIN_LOG4J
2173 <td>#LTTNG_EVENT_TRACEPOINT
2175 <code>lttng_log4j:event</code>
2177 Such an event record has a string field <code>logger_name</code>
2178 which contains the name of the Apache log4j logger from which
2179 LTTng creates \lt_var{E}.
2181 <td>#LTTNG_DOMAIN_PYTHON
2182 <td>#LTTNG_EVENT_TRACEPOINT
2184 <code>lttng_python:event</code>
2186 Such an event record has a string field <code>logger_name</code>
2187 which contains the name of the Python logger from which LTTng
2188 creates \lt_var{E}.
2190 <td>#LTTNG_DOMAIN_KERNEL
2191 <td>#LTTNG_EVENT_SYSCALL
2198 <code>syscall_entry_<em>NAME</em></code>, where
2199 <code><em>NAME</em></code> is the name of the system call from
2200 which LTTng creates \lt_var{E}, without any
2201 <code>sys_</code> prefix.
2205 <code>syscall_exit_<em>NAME</em></code>, where
2206 <code><em>NAME</em></code> is the name of the system call from
2207 which LTTng creates \lt_var{E}, without any
2208 <code>sys_</code> prefix.
2211 <td>#LTTNG_DOMAIN_KERNEL
2212 <td>#LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE
2214 The lttng_event::name member of the
2215 descriptor you used to create \lt_var{ER} with
2216 lttng_enable_event_with_exclusions().
2218 <td>#LTTNG_DOMAIN_KERNEL
2219 <td>#LTTNG_EVENT_FUNCTION
2225 <dd><code><em>NAME</em>_entry</code>
2228 <dd><code><em>NAME</em>_exit</code>
2231 where <code><em>NAME</em></code> is the lttng_event::name member
2232 of the descriptor you used to create
2233 \lt_var{ER} with lttng_enable_event_with_exclusions().
2236 @defgroup api_pais Process attribute inclusion set API
2237 @ingroup api_session
2241 @defgroup api_session_clear Recording session clearing API
2242 @ingroup api_session
2244 This API makes it possible to clear a \lt_obj_session, that is, to
2245 delete the contents of its tracing buffers and/or of all its
2246 \ref api-session-local-mode "local" and
2247 \ref api-session-net-mode "streamed" trace data.
2249 To clear a recording session:
2251 -# Call lttng_clear_session(), passing the name of the recording session
2254 This function initiates a clearing operation, returning immediately.
2256 This function can set a pointer to a
2257 \link #lttng_clear_handle clearing handle\endlink
2258 so that you can wait for the completion of the
2259 operation. Without such a handle, you can't know when the clearing
2260 operation completes and whether or not it does successfully.
2262 -# <strong>If you have a clearing handle from step 1</strong>:
2264 -# Call lttng_clear_handle_wait_for_completion() to wait for the
2265 completion of the clearing operation.
2267 -# Call lttng_clear_handle_get_result() to get whether or not the
2268 clearing operation successfully completed.
2270 -# Destroy the clearing handle with lttng_clear_handle_destroy().
2272 @sa \lt_man{lttng-clear,1}
2274 @defgroup api_session_snapshot Recording session snapshot API
2275 @ingroup api_session
2279 @defgroup api_session_rotation Recording session rotation API
2280 @ingroup api_session
2284 @defgroup api_session_save_load Recording session saving and loading API
2285 @ingroup api_session
2289 @defgroup api_inst_pt Instrumentation point listing API
2291 The lttng_list_tracepoints() and lttng_list_syscalls() functions set a
2292 pointer to an array of
2293 <strong><em>\ref api-rer-inst-pt-descr "instrumentation point descriptors"</em></strong>.
2295 With those two functions, you can get details about the available
2296 LTTng tracepoints, Java/Python loggers, and Linux kernel system calls,
2298 \ref api-gen-sessiond-conn "connect to a session daemon".
2299 You can then use the discovered information to create corresponding
2300 \lt_obj_rers so that you can record the events
2301 which LTTng creates from instrumentation points.
2303 See \ref api_rer to learn more about instrumentation points, events,
2304 event records, and recording event rules.
2306 @defgroup api_trigger Trigger API
2310 @defgroup api_trigger_cond Trigger condition API
2311 @ingroup api_trigger
2315 @defgroup api_trigger_cond_er_matches "Event rule matches" trigger condition API
2316 @ingroup api_trigger_cond
2320 @defgroup api_er Event rule API
2321 @ingroup api_trigger_cond_er_matches
2325 @defgroup api_ll_rule Log level rule API
2330 @defgroup api_ev_expr Event expression API
2331 @ingroup api_trigger_cond_er_matches
2335 @defgroup api_ev_field_val Event field value API
2336 @ingroup api_trigger_cond_er_matches
2340 @defgroup api_trigger_action Trigger action API
2341 @ingroup api_trigger
2345 @defgroup api_notif Notification API
2346 @ingroup api_trigger_action
2350 @defgroup api_error Error query API