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.x/">Apache Log4j 1.x</a>
778 <td>#LTTNG_DOMAIN_LOG4J
780 <td><a href="https://logging.apache.org/log4j/2.x/">Apache Log4j 2</a>
781 <td>#LTTNG_DOMAIN_LOG4J2
783 <td><a href="https://docs.python.org/3/library/logging.html">Python logging</a>
784 <td>#LTTNG_DOMAIN_PYTHON
787 A \lt_obj_channel is always part of a tracing domain.
789 Many liblttng-ctl functions require a tracing domain type (sometimes
791 \link #lttng_handle recording session handle\endlink)
792 to target specific tracers or to avoid ambiguity. For example, because
793 the Linux kernel and user space tracing domains support named
794 tracepoints as \ref api_inst_pt "instrumentation points", you need to
795 specify a tracing domain when you create a
796 \lt_obj_rer with lttng_enable_event_with_exclusions() because both
797 tracing domains could have LTTng tracepoints sharing the same name.
799 @sa The <em>TRACING DOMAIN</em> section of \lt_man{lttng-concepts,7}.
801 <h1>\anchor api-channel-channel Channel</h1>
803 A <strong><em>channel</em></strong> is an object which is responsible
804 for a set of ring buffers.
806 Each ring buffer is divided into multiple <em>sub-buffers</em>. When a
807 \lt_obj_rer matches an event, LTTng can record it to one or more
808 sub-buffers of one or more channels.
810 A channel is always associated to a \lt_obj_domain.
811 The \link #LTTNG_DOMAIN_JUL <code>java.util.logging</code>\endlink,
812 \link #LTTNG_DOMAIN_LOG4J Apache Log4j 1.x\endlink,
813 \link #LTTNG_DOMAIN_LOG4J2 Apache Log4j 2\endlink, and
814 \link #LTTNG_DOMAIN_PYTHON Python\endlink tracing
815 domains each have a default channel which you can't configure.
817 Note that the some functions, like lttng_enable_event_with_exclusions(),
818 can automatically create a default channel with sane defaults when no
819 channel exists for the provided \lt_obj_domain.
821 A channel owns \lt_obj_rers.
823 @image html concepts.png "A recording session contains channels that are members of tracing domains and contain recording event rules."
825 You can't destroy a channel.
829 The channel operations are:
838 -# Call lttng_channel_create() with a \lt_obj_domain summary to
839 create an initial channel summary.
841 This function calls lttng_channel_set_default_attr() to set
842 the properties of the created channel summary to default values
843 depending on the tracing domain summary.
845 -# Set the properties of the channel summary of step 1
846 through direct members or with dedicated setters.
848 See the property table below.
850 -# Create a \link #lttng_handle recording session handle\endlink
851 structure to specify the name of the recording session and the
852 tracing domain of the channel to create.
854 -# Call lttng_enable_channel() with the recording session handle
855 of step 3 and the channel summary of step 1
856 o create the channel.
858 -# Destroy the recording session handle with
859 lttng_destroy_handle() and the channel summary with
860 lttng_channel_destroy().
862 @sa \lt_man{lttng-enable-channel,1}
864 <td>Basic property access
866 See the \ref api-channel-channel-props "property table" below.
868 <td>\lt_obj_c_rer access
870 -# Create a \link #lttng_handle recording session handle\endlink
871 with lttng_create_handle() to specify the name of the
872 recording session and the summary of the
873 \lt_obj_domain of the channel of which to get the recording
874 event rule descriptors.
876 -# Call lttng_list_events(), passing the recording session
877 handle of step 1 and a channel name.
879 This function sets a pointer to an array of
880 \link #lttng_event recording event rule descriptors\endlink
881 and returns the number of entries.
883 -# Destroy the recording session handle of step 1 with
884 lttng_destroy_handle().
886 -# Access the properties of each
887 recording event rule descriptor through structure members or
888 using dedicated getters.
890 -# When you're done with the array of recording event rule
891 descriptors, free it with <code>free()</code>.
893 <td>Event record context field adding
895 -# Initialize a #lttng_event_context structure, setting
896 its properties to describe the context field to be added.
898 -# Create a \link #lttng_handle recording session handle\endlink
899 structure to specify the name of the recording session and the
900 tracing domain of the channel to create.
902 -# Call lttng_add_context() with the recording session handle
903 of step 2 and the context field descriptor of step 1,
904 optionally passing the name of the channel to target.
906 -# Destroy the recording session handle with
907 lttng_destroy_handle().
909 @sa \lt_man{lttng-add-context,1}
913 Use lttng_enable_channel().
915 @sa \lt_man{lttng-enable-channel,1}
919 Use lttng_disable_channel().
921 @sa \lt_man{lttng-disable-channel,1}
927 - lttng_channel_get_discarded_event_count()
928 - lttng_channel_get_lost_packet_count()
931 <h2>\anchor api-channel-channel-props Properties</h2>
933 The properties of a channel are:
943 See \ref api-channel-buf-scheme "Buffering scheme".
945 The lttng_domain::buf_type member for the containing tracing
948 All the channels of a given tracing domain share the same
951 <td>Event record loss mode
953 See \ref api-channel-er-loss-mode "Event record loss mode".
955 The lttng_channel_attr::overwrite member.
959 See \ref api-channel-sub-buf-size-count "Sub-buffer size and count".
961 The lttng_channel_attr::subbuf_size member.
965 See \ref api-channel-sub-buf-size-count "Sub-buffer size and count".
967 The lttng_channel_attr::num_subbuf member.
969 <td>Maximum trace file size
971 See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count".
973 The lttng_channel_attr::tracefile_size member.
975 <td>Maximum trace file count
977 See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count".
979 The lttng_channel_attr::tracefile_count member.
981 <td>Read timer period
983 See \ref api-channel-read-timer "Read timer".
985 The lttng_channel_attr::read_timer_interval member.
987 <td>Switch timer period
989 See \ref api-channel-switch-timer "Switch timer".
991 The lttng_channel_attr::switch_timer_interval member.
993 <td>Live timer period
995 See \ref api-channel-live-timer "Live timer".
997 The \lt_p{live_timer_period} parameter of
998 lttng_session_descriptor_live_network_create() when you create
999 the descriptor of a \ref api-session-live-mode "live" recording
1000 session to contain the channel.
1002 <td>Monitor timer period
1004 See \ref api-channel-monitor-timer "Monitor timer".
1006 - lttng_channel_get_monitor_timer_interval()
1007 - lttng_channel_set_monitor_timer_interval()
1009 <td>Output type (Linux kernel channel)
1011 Whether to use <code>mmap()</code> or <code>splice()</code>.
1013 The lttng_channel_attr::output member.
1015 <td>\anchor api-channel-blocking-timeout Blocking timeout (user space channel)
1017 How long to block (if ever) at the instrumentation point site when
1018 a sub-buffer is not available for applications executed with the
1019 \c LTTNG_UST_ALLOW_BLOCKING environment variable set.
1021 - lttng_channel_get_blocking_timeout()
1022 - lttng_channel_set_blocking_timeout()
1025 All the properties above are immutable once a channel exists.
1027 @sa The <em>CHANNEL AND RING BUFFER</em> section of
1028 \lt_man{lttng-concepts,7}.
1030 <h3>\anchor api-channel-buf-scheme Buffering scheme</h3>
1032 A channel has at least one ring buffer per CPU. LTTng always records an
1033 event to the ring buffer dedicated to the CPU which emits it.
1035 The <strong><em>buffering scheme</em></strong> of a
1036 \link #LTTNG_DOMAIN_UST user space\endlink
1037 channel determines what has its own set of per-CPU
1038 ring buffers, considering \lt_var{U} is the Unix user of the process
1039 running liblttng-ctl:
1043 \anchor api-channel-per-user-buf
1044 \link #LTTNG_BUFFER_PER_UID Per-user buffering\endlink
1046 Allocate one set of ring buffers (one per CPU) shared by all the
1047 instrumented processes of:
1050 <dt>If \lt_var{U} is <code>root</code>
1054 @image html per-user-buffering-root.png
1060 @image html per-user-buffering.png
1064 \anchor api-channel-per-proc-buf
1065 \link #LTTNG_BUFFER_PER_PID Per-process buffering\endlink
1067 Allocate one set of ring buffers (one per CPU) for each
1068 instrumented process of:
1071 <dt>If \lt_var{U} is <code>root</code>
1075 @image html per-process-buffering-root.png
1081 @image html per-process-buffering.png
1085 The per-process buffering scheme tends to consume more memory than the
1086 per-user option because systems generally have more instrumented
1087 processes than Unix users running instrumented processes. However, the
1088 per-process buffering scheme ensures that one process having a high
1089 event throughput won't fill all the shared sub-buffers of the same Unix
1092 The buffering scheme of a Linux kernel (#LTTNG_DOMAIN_KERNEL) channel is
1093 always to allocate a single set of ring buffers for the whole system
1094 (#LTTNG_BUFFER_GLOBAL). This scheme is similar to the
1095 \ref api-channel-per-user-buf "per-user" one, but with a single, global
1096 user "running" the kernel.
1098 To set the buffering scheme of a channel when you create it:
1100 - Set the lttng_domain::buf_type member of the structure which you pass
1101 within the #lttng_handle structure to lttng_enable_channel().
1103 Note that, for a given \lt_obj_session, \em all
1104 the channels of a given \lt_obj_domain must share the same buffering
1107 @sa The <em>Buffering scheme</em> section of \lt_man{lttng-concepts,7}.
1109 <h3>\anchor api-channel-er-loss-mode Event record loss mode</h3>
1111 When LTTng emits an event, LTTng can record it to a specific, available
1112 sub-buffer within the ring buffers of specific channels. When there's no
1113 space left in a sub-buffer, the tracer marks it as consumable and
1114 another, available sub-buffer starts receiving the following event
1115 records. An LTTng consumer daemon eventually consumes the marked
1116 sub-buffer, which returns to the available state.
1118 In an ideal world, sub-buffers are consumed faster than they are filled.
1119 In the real world, however, all sub-buffers can be full at some point,
1120 leaving no space to record the following events.
1122 By default, LTTng-modules and LTTng-UST are <em>non-blocking</em>
1123 tracers: when there's no available sub-buffer to record an event, it's
1124 acceptable to lose event records when the alternative would be to cause
1125 substantial delays in the execution of the instrumented application.
1126 LTTng privileges performance over integrity; it aims at perturbing the
1127 instrumented application as little as possible in order to make the
1128 detection of subtle race conditions and rare interrupt cascades
1131 Since LTTng 2.10, the LTTng user space tracer, LTTng-UST, supports
1132 a <em>blocking mode</em>: see lttng_channel_get_blocking_timeout() and
1133 lttng_channel_set_blocking_timeout().
1135 When it comes to losing event records because there's no available
1136 sub-buffer, or because the blocking timeout of the channel is reached,
1137 the <strong><em>event record loss mode</em></strong> of the channel
1138 determines what to do. The available event record loss modes are:
1141 <dt>\anchor api-channel-discard-mode Discard mode
1143 Drop the newest event records until a sub-buffer becomes available.
1145 This is the only available mode when you specify a blocking timeout
1146 with lttng_channel_set_blocking_timeout().
1148 With this mode, LTTng increments a count of discarded event records
1149 when it discards an event record and saves this count to the trace.
1150 A trace reader can use the saved discarded event record count of the
1151 trace to decide whether or not to perform some analysis even if
1152 trace data is known to be missing.
1154 Get the number of discarded event records of a channel with
1155 lttng_channel_get_discarded_event_count().
1157 <dt>\anchor api-channel-overwrite-mode Overwrite mode
1159 Clear the sub-buffer containing the oldest event records and start
1160 writing the newest event records there.
1162 This mode is sometimes called <em>flight recorder mode</em> because
1164 <a href="https://en.wikipedia.org/wiki/Flight_recorder">flight recorder</a>:
1165 always keep a fixed amount of the latest data. It's also
1166 similar to the roll mode of an oscilloscope.
1168 Since LTTng 2.8, with this mode, LTTng writes to a given
1169 sub-buffer its sequence number within its data stream. With a
1170 \ref api-session-local-mode "local",
1171 \ref api-session-net-mode "network streaming", or
1172 \ref api-session-live-mode "live" recording session, a trace
1173 reader can use such sequence numbers to report discarded packets. A
1174 trace reader can use the saved discarded sub-buffer (packet) count
1175 of the trace to decide whether or not to perform some analysis even
1176 if trace data is known to be missing.
1178 Get the number of discarded packets (sub-buffers) of a channel with
1179 lttng_channel_get_lost_packet_count().
1181 With this mode, LTTng doesn't write to the trace the exact number of
1182 lost event records in the lost sub-buffers.
1185 Which mechanism you should choose depends on your context: prioritize
1186 the newest or the oldest event records in the ring buffer?
1188 Beware that, in overwrite mode, the tracer abandons a <em>whole
1189 sub-buffer</em> as soon as a there's no space left for a new event
1190 record, whereas in discard mode, the tracer only discards the event
1191 record that doesn't fit.
1193 To set the event record loss mode of a channel when you create it:
1195 - Set the lttng_channel_attr::overwrite member of the lttng_channel::attr
1196 member of the structure you pass to lttng_enable_channel().
1198 There are a few ways to decrease your probability of losing event
1200 \ref api-channel-sub-buf-size-count "Sub-buffer size and count" section
1201 shows how to fine-tune the sub-buffer size and count of a channel to
1202 virtually stop losing event records, though at the cost of greater
1205 @sa The <em>Event record loss mode</em> section of
1206 \lt_man{lttng-concepts,7}.
1208 <h3>\anchor api-channel-sub-buf-size-count Sub-buffer size and count</h3>
1210 A channel has one or more ring buffer for each CPU of the target system.
1212 See \ref api-channel-buf-scheme "Buffering scheme" to learn how many
1213 ring buffers of a given channel are dedicated to each CPU depending on
1214 its buffering scheme.
1216 To set the size of each sub-buffer the ring buffers of a channel have
1219 - Set the lttng_channel_attr::subbuf_size member of the
1220 lttng_channel::attr member of the structure you pass to
1221 lttng_enable_channel().
1223 To set the number of sub-buffers each ring buffer of a channel has
1226 - Set the lttng_channel_attr::num_subbuf member of the
1227 lttng_channel::attr member of the structure you pass to
1228 lttng_enable_channel().
1230 Note that LTTng switching the current sub-buffer of a ring buffer
1231 (marking a full one as consumable and switching to an available one for
1232 LTTng to record the next events) introduces noticeable CPU overhead.
1233 Knowing this, the following list presents a few practical situations
1234 along with how to configure the sub-buffer size and count for them:
1237 <dt>High event throughput
1239 In general, prefer large sub-buffers to lower the risk of losing
1242 Having larger sub-buffers also ensures a lower sub-buffer
1243 \ref api-channel-switch-timer "switching frequency".
1245 The sub-buffer count is only meaningful if you create the channel in
1246 \ref api-channel-overwrite-mode "overwrite mode": in this case, if
1247 LTTng overwrites a sub-buffer, then the other sub-buffers are left
1250 <dt>Low event throughput
1252 In general, prefer smaller sub-buffers since the risk of losing
1253 event records is low.
1255 Because LTTng emits events less frequently, the sub-buffer switching
1256 frequency should remain low and therefore the overhead of the tracer
1257 shouldn't be a problem.
1259 <dt>Low memory system
1261 If your target system has a low memory limit, prefer fewer first,
1262 then smaller sub-buffers.
1264 Even if the system is limited in memory, you want to keep the
1265 sub-buffers as large as possible to avoid a high sub-buffer
1266 switching frequency.
1269 Note that LTTng uses <a href="https://diamon.org/ctf/">CTF</a> as its
1270 trace format, which means event record data is very compact. For
1271 example, the average LTTng kernel event record weights about
1272 32 bytes. Therefore, a sub-buffer size of 1 MiB is considered
1275 The previous scenarios highlight the major trade-off between a few large
1276 sub-buffers and more, smaller sub-buffers: sub-buffer switching
1277 frequency vs. how many event records are lost in
1278 \ref api-channel-overwrite-mode "overwrite mode".
1279 Assuming a constant event throughput and using the overwrite mode, the
1280 two following configurations have the same ring buffer total size:
1283 <dt>Two sub-buffers of 4 MiB each
1285 Expect a very low sub-buffer switching frequency, but if LTTng ever
1286 needs to overwrite a sub-buffer, half of the event records so far
1287 (4 MiB) are definitely lost.
1289 <dt>Eight sub-buffers of 1 MiB each
1291 Expect four times the tracer overhead of the configuration above,
1292 but if LTTng needs to overwrite a sub-buffer, only the eighth of
1293 event records so far (1 MiB) are definitely lost.
1296 In \ref api-channel-discard-mode "discard mode", the sub-buffer count
1297 parameter is pointless: use two sub-buffers and set their size according
1298 to your requirements.
1300 @sa The <em>Sub-buffer size and count</em> section of
1301 \lt_man{lttng-concepts,7}.
1303 <h3>\anchor api-channel-max-trace-file-size-count Maximum trace file size and count</h3>
1305 By default, trace files can grow as large as needed.
1307 To set the maximum size of each trace file that LTTng writes from the
1308 ring buffers of a channel when you create it:
1310 - Set the lttng_channel_attr::tracefile_size member of the
1311 lttng_channel::attr member of the structure you pass to
1312 lttng_enable_channel().
1314 When the size of a trace file reaches the fixed maximum size of the
1315 channel, LTTng creates another file to contain the next event records.
1316 LTTng appends a file count to each trace file name in this case.
1318 If you set the trace file size attribute when you create a channel, the
1319 maximum number of trace files that LTTng creates is <em>unlimited</em>
1322 To limit the size of each trace file that LTTng writes from the
1323 ring buffers of a channel when you create it:
1325 - Set the lttng_channel_attr::tracefile_count member of the
1326 lttng_channel::attr member of the structure you pass to
1327 lttng_enable_channel().
1329 When the number of trace files reaches the fixed maximum count of the
1330 channel, LTTng overwrites the oldest trace file. This mechanism is
1331 called <em>trace file rotation</em>.
1335 Even if you don't limit the trace file count, always assume that
1336 LTTng manages all the trace files of the recording session.
1338 In other words, there's no safe way to know if LTTng still holds a
1339 given trace file open with the trace file rotation feature.
1341 The only way to obtain an unmanaged, self-contained LTTng trace
1342 before you \link lttng_destroy_session_ext() destroy the
1343 recording session\endlink is with the
1344 \ref api_session_rotation "recording session rotation" feature,
1345 which is available since LTTng 2.11.
1348 @sa The <em>Maximum trace file size and count</em> section of
1349 \lt_man{lttng-concepts,7}.
1351 <h3>\anchor api-channel-timers Timers</h3>
1353 Each channel can have up to four optional
1354 <strong><em>timers</em></strong>:
1357 <dt>\anchor api-channel-switch-timer Switch timer
1359 When this timer expires, a sub-buffer switch happens: for each ring
1360 buffer of the channel, LTTng marks the current sub-buffer as
1361 consumable and switches to an available one to record the next
1364 A switch timer is useful to ensure that LTTng consumes and commits
1365 trace data to trace files or to a distant relay daemon
1366 (see \lt_man{lttng-relayd,8}) periodically in case of a low event
1369 Such a timer is also convenient when you use
1370 \ref api-channel-sub-buf-size-count "large sub-buffers"
1371 to cope with a sporadic high event throughput, even if the
1372 throughput is otherwise low.
1374 To set the period of the switch timer of a channel when you create
1377 - Set the lttng_channel_attr::switch_timer_interval member of the
1378 lttng_channel::attr member of the structure you pass to
1379 lttng_enable_channel().
1381 A channel only has a switch timer when its
1382 recording session is \em not in
1383 \ref api-session-live-mode "live mode". lttng_enable_channel()
1384 ignores the lttng_channel_attr::switch_timer_interval member with a
1385 live recording session. For a live recording session, the
1386 \ref api-channel-live-timer "live timer" plays the role of the
1389 <dt>\anchor api-channel-live-timer Live timer
1391 Like the \ref api-channel-switch-timer "switch timer", but for a
1392 channel which belongs to a
1393 \ref api-session-live-mode "live" recording session.
1395 If this timer expires but there's no sub-buffer to consume, LTTng
1396 sends a message with a timestamp to the connected relay daemon (see
1397 \lt_man{lttng-relayd,8}) so that its live readers can progress.
1399 To set the period of the live timer of a channel when you create
1400 its recording session:
1402 - Set the \lt_p{live_timer_period} parameter when you call
1403 lttng_session_descriptor_live_network_create() to create a
1404 live recording session descriptor to pass to
1405 lttng_create_session_ext().
1408 All the channels of a live recording session share the same
1411 <dt>\anchor api-channel-read-timer Read timer
1413 When this timer expires, LTTng checks for full, consumable
1416 By default, the LTTng tracers use an asynchronous message mechanism
1417 to signal a full sub-buffer so that a consumer daemon can consume
1420 When such messages must be avoided, for example in real-time
1421 applications, use this timer instead.
1423 To set the period of the read timer of a channel when you create
1426 - Set the lttng_channel_attr::read_timer_interval member of the
1427 lttng_channel::attr member of the structure you pass to
1428 lttng_enable_channel().
1430 <dt>\anchor api-channel-monitor-timer Monitor timer
1432 When this timer expires, the consumer daemon samples some channel
1433 statistics to evaluate the following trigger conditions:
1435 -# The consumed buffer size of a given recording session becomes
1436 greater than some value.
1438 -# The buffer usage of a given channel becomes greater than some
1441 -# The buffer usage of a given channel becomes less than some value.
1443 If you disable the monitor timer of a channel \lt_var{C}:
1445 - The consumed buffer size value of the recording session
1446 of \lt_var{C} could be wrong for trigger condition
1447 type 1: the consumed buffer size of \lt_var{C} won't be
1448 part of the grand total.
1450 - The buffer usage trigger conditions (types 2 and 3)
1451 for \lt_var{C} will never be satisfied.
1453 See \ref api_trigger to learn more about triggers.
1455 To set the period of the monitor timer of a channel when you create
1458 - Call lttng_channel_set_monitor_timer_interval() with the
1459 #lttng_channel structure you pass to lttng_enable_channel().
1462 @sa The <em>Timers</em> section of \lt_man{lttng-concepts,7}.
1464 @defgroup api_rer Recording event rule API
1465 @ingroup api_channel
1469 An <em>instrumentation point</em> is a point, within a piece of
1470 software, which, when executed, creates an LTTng <em>event</em>.
1471 See \ref api_inst_pt to learn how to list the available instrumentation
1474 An <em>event rule</em> is a set of \ref api-rer-conds "conditions" to
1475 match a set of events.
1477 A <strong><em>recording event rule</em></strong> is a specific type of
1478 event rule of which the action is to serialize and write the matched
1479 event as an <em>event record</em> to a sub-buffer of its attached
1482 An event record has a \ref api-rer-er-name "name" and fields.
1484 When LTTng creates an event \lt_var{E}, a recording event
1485 rule \lt_var{ER} is said to <em>match</em> \lt_var{E}
1486 when \lt_var{E} satisfies \em all the conditions
1487 of \lt_var{ER}. This concept is similar to a regular expression
1488 which matches a set of strings.
1490 When a recording event rule matches an event, LTTng \em emits the event,
1491 therefore attempting to record it.
1495 The event creation and emission processes are \em documentation
1496 concepts to help understand the journey from an instrumentation
1497 point to an event record.
1499 The actual creation of an event can be costly because LTTng needs to
1500 evaluate the arguments of the instrumentation point.
1502 In practice, LTTng implements various optimizations for the
1503 \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink and
1504 \link #LTTNG_DOMAIN_UST user space\endlink \lt_obj_domains
1505 to avoid actually creating an event when the tracer knows, thanks to
1506 properties which are independent from the event payload and current
1507 \link #lttng_event_context_type context\endlink, that it would never
1508 emit such an event. Those properties are:
1510 - The \ref api-rer-conds-inst-pt-type "instrumentation point type".
1512 - The \ref api-rer-conds-event-name "instrumentation point name" (or
1515 - The \ref api-rer-conds-ll "instrumentation point log level".
1517 - The \link lttng_event::enabled status\endlink (enabled or
1518 disabled) of the rule itself.
1520 - The \link lttng_channel::enabled status\endlink (enabled or
1521 disabled) of the \lt_obj_channel containing the rule.
1523 - The \link lttng_session::enabled activity\endlink (started or
1524 stopped) of the \lt_obj_session containing the rule.
1526 - Whether or not the process for which LTTng would create the event
1527 is \ref api_pais "allowed to record events".
1529 In other words: if, for a given instrumentation point \lt_var{IP},
1530 the LTTng tracer knows that it would never emit an event,
1531 executing \lt_var{IP} represents a simple boolean variable check
1532 and, for a \link #LTTNG_DOMAIN_KERNEL Linux kernel\endlink
1533 \lt_obj_rer, a few current process attribute checks.
1536 You always attach a recording event rule to a
1537 \lt_obj_channel, which belongs to
1538 a \lt_obj_session, when you
1539 \link lttng_enable_event_with_exclusions() create it\endlink.
1540 A channel owns recording event rules.
1542 When multiple matching recording event rules are attached to the same
1543 channel, LTTng attempts to serialize and record the matched event
1546 @image html event-rule.png "Logical path from an instrumentation point to an event record."
1548 As of LTTng-tools \lt_version_maj_min, you cannot remove a
1549 recording event rule: it exists as long as its \lt_obj_session exists.
1553 The recording event rule operations are:
1562 -# Call lttng_event_create() to create an initial
1563 \link #lttng_event recording event rule descriptor\endlink.
1565 -# Set the properties of the recording event rule descriptor of
1566 step 1 through direct members or with dedicated setters.
1568 See the property table below.
1570 -# Create a \link #lttng_handle recording session handle\endlink
1571 structure to specify the name of the recording session and the
1572 tracing domain of the recording event rule to create.
1574 -# Call lttng_enable_event_with_exclusions() with the recording
1575 session handle of step 3, the recording event rule
1576 descriptor of step 1, the name of a
1577 \lt_obj_channel to which to attach the
1578 created recording event rule, and, depending on the selected
1579 function, other properties to create the rule.
1581 -# Destroy the recording session handle with
1582 lttng_destroy_handle() and the recording event rule descriptor
1583 with lttng_event_destroy().
1585 @sa \lt_man{lttng-enable-event,1}
1591 - The members of #lttng_event
1592 - lttng_event_get_userspace_probe_location()
1593 - lttng_event_set_userspace_probe_location()
1594 - lttng_event_get_filter_expression()
1595 - lttng_event_get_exclusion_name_count()
1596 - lttng_event_get_exclusion_name()
1598 @sa \ref api-rer-conds "Recording event rule conditions".
1602 With an #lttng_event instance which comes from
1603 lttng_list_events(), use lttng_enable_event().
1605 Otherwise, use lttng_enable_event_with_exclusions().
1607 @sa \lt_man{lttng-enable-event,1}
1611 Use lttng_disable_event() or lttng_disable_event_ext().
1613 @sa \lt_man{lttng-disable-event,1}
1616 <h1>\anchor api-rer-conds Recording event rule conditions</h1>
1618 For LTTng to emit and record an event \lt_var{E}, \lt_var{E}
1619 must satisfy \em all the conditions of a recording event
1620 rule \lt_var{ER}, that is:
1623 <dt>Explicit conditions
1625 You set the following conditions when you
1626 \link lttng_enable_event_with_exclusions() create\endlink
1627 \lt_var{ER} from some
1628 \link #lttng_event recording event rule descriptor\endlink
1629 \c event_rule (#lttng_event).
1637 \anchor api-rer-conds-inst-pt-type
1638 \ref api-rer-conds-inst-pt-type "Instrumentation point type"
1640 \lt_var{E} satisfies the instrumentation point type condition
1641 of \lt_var{ER} if the instrumentation point from which LTTng
1642 creates \lt_var{E} is, depending on the
1643 \lt_obj_domain which contains \lt_var{ER}:
1646 <dt>#LTTNG_DOMAIN_KERNEL
1649 \link lttng_event::type <code>event_rule.type</code>\endlink:
1652 <dt>#LTTNG_EVENT_TRACEPOINT
1654 An LTTng kernel tracepoint, that is, a statically
1655 defined point in the source code of the kernel image
1656 or of a kernel module with LTTng kernel tracer macros.
1658 @sa lttng_list_tracepoints()
1660 <dt>#LTTNG_EVENT_SYSCALL
1662 The entry and exit of a Linux kernel system call.
1664 @sa lttng_list_syscalls()
1666 <dt>#LTTNG_EVENT_PROBE
1669 <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kprobe</a>,
1670 that is, a single probe dynamically placed in the
1671 compiled kernel code.
1673 \link lttng_event::lttng_event_attr_u::probe
1674 <code>event_rule.attr.probe</code>\endlink
1675 indicates the kprobe location,
1676 while \link lttng_event::name
1677 <code>event_rule.name</code>\endlink
1678 is the name of the created kprobe instrumentation
1679 point (future event name).
1681 The payload of a Linux kprobe event is empty.
1683 <dt>#LTTNG_EVENT_FUNCTION
1686 <a href="https://www.kernel.org/doc/html/latest/trace/kprobes.html">kretprobe</a>,
1687 that is, two probes dynamically placed at the entry
1688 and exit of a function in the compiled kernel code.
1690 \link lttng_event::lttng_event_attr_u::probe
1691 <code>event_rule.attr.probe</code>\endlink
1692 indicates the kretprobe location,
1693 while \link lttng_event::name
1694 <code>event_rule.name</code>\endlink
1695 is the name of the created kretprobe instrumentation
1696 point (future event name).
1698 The payload of a Linux kretprobe event is empty.
1700 <dt>#LTTNG_EVENT_USERSPACE_PROBE
1703 <a href="https://lwn.net/Articles/499190/">uprobe</a>,
1704 that is, a single probe dynamically placed at the
1705 entry of a compiled user space application/library
1706 function through the kernel.
1708 Set and get the location of the uprobe with
1709 lttng_event_set_userspace_probe_location() and
1710 lttng_event_get_userspace_probe_location().
1712 \link lttng_event::name <code>event_rule.name</code>\endlink
1713 is the name of the created uprobe instrumentation
1714 point (future event name).
1716 The payload of a Linux uprobe event is empty.
1719 <dt>#LTTNG_DOMAIN_UST
1721 An LTTng user space tracepoint, that is, a statically
1722 defined point in the source code of a C/C++
1723 application/library with LTTng user space tracer macros.
1725 \link lttng_event::type <code>event_rule.type</code>\endlink
1726 must be #LTTNG_EVENT_TRACEPOINT.
1728 @sa lttng_list_tracepoints()
1730 <dt>#LTTNG_DOMAIN_JUL
1731 <dt>#LTTNG_DOMAIN_LOG4J
1732 <dt>#LTTNG_DOMAIN_PYTHON
1734 A Java/Python logging statement.
1736 \link lttng_event::type <code>event_rule.type</code>\endlink
1737 must be #LTTNG_EVENT_TRACEPOINT.
1739 @sa lttng_list_tracepoints()
1743 \anchor api-rer-conds-event-name
1744 \ref api-rer-conds-event-name "Event name"
1746 An event \lt_var{E} satisfies the event name condition
1747 of \lt_var{ER} if the two following statements are
1750 - \link lttng_event::name <code>event_rule.name</code>\endlink
1751 matches, depending on
1752 \link lttng_event::type <code>event_rule.type</code>\endlink
1753 (see \ref api-rer-conds-inst-pt-type "Instrumentation point type"
1757 <dt>#LTTNG_EVENT_TRACEPOINT
1759 The full name of the LTTng tracepoint or Java/Python
1760 logger from which LTTng creates \lt_var{E}.
1762 Note that the full name of a
1763 \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
1764 <code><em>PROVIDER</em>:<em>NAME</em></code>, where
1765 <code><em>PROVIDER</em></code> is the tracepoint
1766 provider name and <code><em>NAME</em></code> is the
1769 <dt>#LTTNG_EVENT_SYSCALL
1771 The name of the system call, without any
1772 <code>sys_</code> prefix, from which LTTng
1773 creates \lt_var{E}.
1776 @sa \ref api-rer-er-name "Event record name".
1778 - If the \lt_obj_domain
1779 containing \lt_var{ER} is #LTTNG_DOMAIN_UST:
1780 none of the event name exclusion patterns of
1781 \c event_rule matches the full name of the user
1782 space tracepoint from which LTTng creates \lt_var{E}.
1784 Set the event name exclusion patterns of
1785 \c event_rule when you call
1786 lttng_enable_event_with_exclusions().
1788 Get the event name exclusion patterns of
1789 a recording event rule descriptor with
1790 lttng_event_get_exclusion_name_count() and
1791 lttng_event_get_exclusion_name().
1793 This condition is only meaningful when
1794 \link lttng_event::type <code>event_rule.type</code>\endlink
1795 is #LTTNG_EVENT_TRACEPOINT or
1796 #LTTNG_EVENT_SYSCALL: it's always satisfied for the other
1797 \ref api-rer-conds-inst-pt-type "instrumentation point types".
1800 \link lttng_event::name <code>event_rule.name</code>\endlink
1801 and the event name exclusion patterns of
1802 \c event_rule are <em>globbing patterns</em>: the
1803 <code>*</code> character means "match anything". To match a
1804 literal <code>*</code> character, use <code>\\*</code>.
1807 \anchor api-rer-conds-ll
1808 \ref api-rer-conds-ll "Instrumentation point log level"
1810 An event \lt_var{E} satisfies the instrumentation point
1811 log level condition of \lt_var{ER} if, depending on
1812 \link lttng_event::loglevel_type <code>event_rule.loglevel_type</code>\endlink,
1813 the log level of the LTTng user space tracepoint or
1814 logging statement from which LTTng creates \lt_var{E}
1818 <dt>#LTTNG_EVENT_LOGLEVEL_ALL
1820 Anything (the condition is always satisfied).
1822 <dt>#LTTNG_EVENT_LOGLEVEL_RANGE
1824 At least as severe as
1825 \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink.
1827 <dt>#LTTNG_EVENT_LOGLEVEL_SINGLE
1830 \link lttng_event::loglevel <code>event_rule.loglevel</code>\endlink.
1833 This condition is only meaningful when the \lt_obj_domain
1834 containing \lt_var{ER} is \em not #LTTNG_DOMAIN_KERNEL:
1835 it's always satisfied for #LTTNG_DOMAIN_KERNEL.
1838 \anchor api-rer-conds-filter
1839 \ref api-rer-conds-filter "Event payload and context filter"
1841 An event \lt_var{E} satisfies the event payload and
1842 context filter condition of \lt_var{ER} if
1843 \c event_rule has no filter expression or if its filter
1844 expression \lt_var{EXPR} evaluates to \b true
1845 when LTTng creates \lt_var{E}.
1847 This condition is only meaningful when:
1849 - The \lt_obj_domain containing \lt_var{ER} is
1850 #LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST: it's always
1851 satisfied for the other tracing domains.
1853 - \link lttng_event::type <code>event_rule.type</code>\endlink
1854 is #LTTNG_EVENT_TRACEPOINT or #LTTNG_EVENT_SYSCALL:
1855 it's always satisfied for the other
1856 \ref api-rer-conds-inst-pt-type "instrumentation point types".
1858 Set the event payload and context filter expression of
1859 \c event_rule when you call
1860 lttng_enable_event_with_exclusions().
1862 Get the event payload and context filter expression of
1863 a recording event rule descriptor with
1864 lttng_event_get_filter_expression().
1866 \lt_var{EXPR} can contain references to the payload fields
1867 of \lt_var{E} and to the current
1868 \link #lttng_event_context_type context\endlink fields.
1870 The expected syntax of \lt_var{EXPR} is similar to the syntax
1871 of a C language conditional expression (an expression
1872 which an \c if statement can evaluate), but there are a few
1875 - A <code><em>NAME</em></code> expression identifies an event
1876 payload field named <code><em>NAME</em></code> (a
1879 Use the C language dot and square bracket notations to
1880 access nested structure and array/sequence fields. You can
1881 only use a constant, positive integer number within square
1882 brackets. If the index is out of bounds, \lt_var{EXPR} is
1885 The value of an enumeration field is an integer.
1887 When a field expression doesn't exist, \lt_var{EXPR} is
1890 Examples: <code>my_field</code>, <code>target_cpu</code>,
1891 <code>seq[7]</code>, <code>msg.user[1].data[2][17]</code>.
1893 - A <code>$ctx.<em>TYPE</em></code> expression identifies the
1894 statically-known context field having the type
1895 <code><em>TYPE</em></code> (a C identifier).
1897 When a field expression doesn't exist, \lt_var{EXPR} is \b
1900 Examples: <code>$ctx.prio</code>,
1901 <code>$ctx.preemptible</code>,
1902 <code>$ctx.perf:cpu:stalled-cycles-frontend</code>.
1904 - A <code>$app.<em>PROVIDER</em>:<em>TYPE</em></code>
1905 expression identifies the application-specific context field
1906 having the type <code><em>TYPE</em></code> (a
1907 C identifier) from the provider
1908 <code><em>PROVIDER</em></code> (a C identifier).
1910 When a field expression doesn't exist, \lt_var{EXPR} is \b
1913 Example: <code>$app.server:cur_user</code>.
1915 - Compare strings, either string fields or string literals
1916 (double-quoted), with the <code>==</code> and
1917 <code>!=</code> operators.
1919 When comparing to a string literal, the <code>*</code>
1920 character means "match anything". To match a literal
1921 <code>*</code> character, use <code>\\*</code>.
1923 Examples: <code>my_field == "user34"</code>,
1924 <code>my_field == my_other_field</code>,
1925 <code>my_field == "192.168.*"</code>.
1928 <a href="https://en.wikipedia.org/wiki/Order_of_operations">precedence table</a>
1929 of the operators which are supported in
1930 \lt_var{EXPR} is as follows. In this table, the highest
1931 precedence is 1:
1961 <td><code><<</code>
1962 <td>Bitwise left shift
1966 <td><code>>></code>
1967 <td>Bitwise right shift
1971 <td><code>&</code>
1986 <td><code><</code>
1991 <td><code><=</code>
1992 <td>Less than or equal to
1996 <td><code>></code>
2001 <td><code>>=</code>
2002 <td>Greater than or equal to
2016 <td><code>&&</code>
2026 Parentheses are supported to bypass the default order.
2029 Unlike the C language, the bitwise AND and OR
2030 operators (<code>&</code> and <code>|</code>) in
2031 \lt_var{EXPR} take precedence over relational
2032 operators (<code><<</code>, <code><=</code>,
2033 <code>></code>, <code>>=</code>, <code>==</code>,
2034 and <code>!=</code>). This means the expression
2035 <code>2 & 2 == 2</code>
2036 is \b true while the equivalent C expression
2039 The arithmetic operators are :not: supported.
2041 LTTng first casts all integer constants and fields to signed
2042 64-bit integers. The representation of negative integers is
2043 two's complement. This means that, for example, the signed
2044 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff
2045 (still -1) once casted.
2047 Before a bitwise operator is applied, LTTng casts all its
2048 operands to unsigned 64-bit integers, and then casts the
2049 result back to a signed 64-bit integer. For the bitwise NOT
2050 operator, it's the equivalent of this C expression:
2053 (int64_t) ~((uint64_t) val)
2056 For the binary bitwise operators, it's the equivalent of those
2060 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
2061 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
2062 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
2063 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
2064 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
2067 If the right-hand side of a bitwise shift operator
2068 (<code><<</code> and <code>>></code>) is not in
2069 the [0, 63] range, then \lt_var{EXPR} is \b false.
2072 See the \ref api_pais to allow or disallow processes to
2073 record LTTng events based on their attributes
2074 instead of using equivalent statically-known context
2075 fields in \lt_var{EXPR} like <code>$ctx.pid</code>.
2076 The former method is much more efficient.
2078 \lt_var{EXPR} examples:
2081 msg_id == 23 && size >= 2048
2085 $ctx.procname == "lttng*" && (!flag || poel < 34)
2089 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
2093 $ctx.cpu_id == 2 && filename != "*.log"
2097 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
2101 <dt>Implicit conditions
2103 - \lt_var{ER} itself is \link lttng_event::enabled enabled\endlink.
2105 A recording event rule is enabled on
2106 \link lttng_enable_event_with_exclusions() creation\endlink.
2108 @sa lttng_enable_event() --
2109 Creates or enables a recording event rule.
2110 @sa lttng_disable_event_ext() --
2111 Disables a recording event rule.
2113 - The \lt_obj_channel which contains \lt_var{ER} is
2114 \link lttng_channel::enabled enabled\endlink.
2116 A channel is enabled on
2117 \link lttng_enable_channel() creation\endlink.
2119 @sa lttng_enable_channel() --
2120 Creates or enables a channel.
2121 @sa lttng_disable_channel() --
2124 - The \lt_obj_session which contains \lt_var{ER} is
2125 \link lttng_session::enabled active\endlink (started).
2127 A recording session is inactive (stopped) on
2128 \link lttng_create_session_ext() creation\endlink.
2130 @sa lttng_start_tracing() --
2131 Starts a recording session.
2132 @sa lttng_stop_tracing() --
2133 Stops a recording session.
2135 - The process for which LTTng creates \lt_var{E} is
2136 \ref api_pais "allowed to record events".
2138 All processes are allowed to record events on recording session
2139 \link lttng_create_session_ext() creation\endlink.
2142 <h1>\anchor api-rer-er-name Event record name</h1>
2144 When LTTng records an event \lt_var{E}, the resulting event record
2145 has a name which depends on the
2146 \ref api-rer-conds-inst-pt-type "instrumentation point type condition"
2147 of the recording event rule \lt_var{ER} which matched \lt_var{E}
2148 as well as on the \lt_obj_domain which contains \lt_var{ER}:
2153 <th>Instrumentation point type
2154 <th>Event record name
2156 <td>#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST
2157 <td>#LTTNG_EVENT_TRACEPOINT
2159 Full name of the tracepoint from which LTTng creates \lt_var{E}.
2161 Note that the full name of a
2162 \link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
2163 <code><em>PROVIDER</em>:<em>NAME</em></code>, where
2164 <code><em>PROVIDER</em></code> is the tracepoint provider name and
2165 <code><em>NAME</em></code> is the tracepoint name.
2167 <td>#LTTNG_DOMAIN_JUL
2168 <td>#LTTNG_EVENT_TRACEPOINT
2170 <code>lttng_jul:event</code>
2172 Such an event record has a string field <code>logger_name</code>
2173 which contains the name of the <code>java.util.logging</code>
2174 logger from which LTTng creates \lt_var{E}.
2176 <td>#LTTNG_DOMAIN_LOG4J
2177 <td>#LTTNG_EVENT_TRACEPOINT
2179 <code>lttng_log4j:event</code>
2181 Such an event record has a string field <code>logger_name</code>
2182 which contains the name of the Apache Log4j 1.x logger from which
2183 LTTng creates \lt_var{E}.
2185 <td>#LTTNG_DOMAIN_LOG4J2
2186 <td>#LTTNG_EVENT_TRACEPOINT
2188 <code>lttng_log4j2:event</code>
2190 Such an event record has a string field <code>logger_name</code>
2191 which contains the name of the Apache Log4j 2 logger from which
2192 LTTng creates \lt_var{E}.
2194 <td>#LTTNG_DOMAIN_PYTHON
2195 <td>#LTTNG_EVENT_TRACEPOINT
2197 <code>lttng_python:event</code>
2199 Such an event record has a string field <code>logger_name</code>
2200 which contains the name of the Python logger from which LTTng
2201 creates \lt_var{E}.
2203 <td>#LTTNG_DOMAIN_KERNEL
2204 <td>#LTTNG_EVENT_SYSCALL
2211 <code>syscall_entry_<em>NAME</em></code>, where
2212 <code><em>NAME</em></code> is the name of the system call from
2213 which LTTng creates \lt_var{E}, without any
2214 <code>sys_</code> prefix.
2218 <code>syscall_exit_<em>NAME</em></code>, where
2219 <code><em>NAME</em></code> is the name of the system call from
2220 which LTTng creates \lt_var{E}, without any
2221 <code>sys_</code> prefix.
2224 <td>#LTTNG_DOMAIN_KERNEL
2225 <td>#LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE
2227 The lttng_event::name member of the
2228 descriptor you used to create \lt_var{ER} with
2229 lttng_enable_event_with_exclusions().
2231 <td>#LTTNG_DOMAIN_KERNEL
2232 <td>#LTTNG_EVENT_FUNCTION
2238 <dd><code><em>NAME</em>_entry</code>
2241 <dd><code><em>NAME</em>_exit</code>
2244 where <code><em>NAME</em></code> is the lttng_event::name member
2245 of the descriptor you used to create
2246 \lt_var{ER} with lttng_enable_event_with_exclusions().
2249 @defgroup api_pais Process attribute inclusion set API
2250 @ingroup api_session
2254 @defgroup api_session_clear Recording session clearing API
2255 @ingroup api_session
2257 This API makes it possible to clear a \lt_obj_session, that is, to
2258 delete the contents of its tracing buffers and/or of all its
2259 \ref api-session-local-mode "local" and
2260 \ref api-session-net-mode "streamed" trace data.
2262 To clear a recording session:
2264 -# Call lttng_clear_session(), passing the name of the recording session
2267 This function initiates a clearing operation, returning immediately.
2269 This function can set a pointer to a
2270 \link #lttng_clear_handle clearing handle\endlink
2271 so that you can wait for the completion of the
2272 operation. Without such a handle, you can't know when the clearing
2273 operation completes and whether or not it does successfully.
2275 -# <strong>If you have a clearing handle from step 1</strong>:
2277 -# Call lttng_clear_handle_wait_for_completion() to wait for the
2278 completion of the clearing operation.
2280 -# Call lttng_clear_handle_get_result() to get whether or not the
2281 clearing operation successfully completed.
2283 -# Destroy the clearing handle with lttng_clear_handle_destroy().
2285 @sa \lt_man{lttng-clear,1}
2287 @defgroup api_session_snapshot Recording session snapshot API
2288 @ingroup api_session
2292 @defgroup api_session_rotation Recording session rotation API
2293 @ingroup api_session
2297 @defgroup api_session_save_load Recording session saving and loading API
2298 @ingroup api_session
2302 @defgroup api_inst_pt Instrumentation point listing API
2304 The lttng_list_tracepoints() and lttng_list_syscalls() functions set a
2305 pointer to an array of
2306 <strong><em>\ref api-rer-inst-pt-descr "instrumentation point descriptors"</em></strong>.
2308 With those two functions, you can get details about the available
2309 LTTng tracepoints, Java/Python loggers, and Linux kernel system calls,
2311 \ref api-gen-sessiond-conn "connect to a session daemon".
2312 You can then use the discovered information to create corresponding
2313 \lt_obj_rers so that you can record the events
2314 which LTTng creates from instrumentation points.
2316 See \ref api_rer to learn more about instrumentation points, events,
2317 event records, and recording event rules.
2319 @defgroup api_trigger Trigger API
2323 @defgroup api_trigger_cond Trigger condition API
2324 @ingroup api_trigger
2328 @defgroup api_trigger_cond_er_matches "Event rule matches" trigger condition API
2329 @ingroup api_trigger_cond
2333 @defgroup api_er Event rule API
2334 @ingroup api_trigger_cond_er_matches
2338 @defgroup api_ll_rule Log level rule API
2343 @defgroup api_ev_expr Event expression API
2344 @ingroup api_trigger_cond_er_matches
2348 @defgroup api_ev_field_val Event field value API
2349 @ingroup api_trigger_cond_er_matches
2353 @defgroup api_trigger_action Trigger action API
2354 @ingroup api_trigger
2358 @defgroup api_notif Notification API
2359 @ingroup api_trigger_action
2363 @defgroup api_error Error query API