/*! @mainpage Bonjour! Welcome to the \lt_api (liblttng-ctl) documentation! The Linux Trace Toolkit: next generation is an open-source software package used for correlated tracing of the Linux kernel, user applications, and user libraries. liblttng-ctl, which is part of the LTTng-tools project, makes it possible to control LTTng tracing, but also to \ref api_trigger "receive notifications when specific events occur".
%lttng/lttng.h
:
@code
#include liblttng-ctl
:
@code{.unparsed}
$ cc my-app.o ... -llttng-ctl
@endcode
With pkg-config, get the required linker options with:
@code{.unparsed}
$ pkg-config --libs lttng-ctl
@endcode
\--group=GROUP
option of the root
session daemon
GROUP
.
In that case, you must call lttng_set_tracing_group(), passing
exactly GROUP
, \em before you call a
liblttng-ctl function which needs to connect to a session daemon.
\--group
option of the root
session daemon
Operation | Means |
---|---|
Creation | -# Create a \lt_obj_session_descr with one of the dedicated creation functions depending on the \ref api-session-modes "recording session mode". -# Call lttng_create_session_ext(), passing the recording session descriptor of step 1. -# When you're done with the recording session descriptor, destroy it with lttng_session_descriptor_destroy(). @sa \lt_man{lttng-create,1} |
Destruction | -# Call lttng_destroy_session_ext(), passing the name of the recording session to destroy. This function initiates a destruction operation, returning immediately. This function can set a pointer to a \ref api_session_destr_handle "destruction handle" (#lttng_destruction_handle) so that you can wait for the completion of the operation. Without such a handle, you can't know when the destruction operation completes and whether or not it does successfully. -# If you have a destruction handle from step 1: -# Call lttng_destruction_handle_wait_for_completion() to wait for the completion of the destruction operation. -# Call lttng_destruction_handle_get_result() to get whether or not the destruction operation successfully completed. You can also call lttng_destruction_handle_get_rotation_state() and lttng_destruction_handle_get_archive_location() at this point. -# Destroy the destruction handle with lttng_destruction_handle_destroy(). @sa \lt_man{lttng-destroy,1} |
Basic property access | See: - The members of #lttng_session - lttng_session_descriptor_get_session_name() - lttng_session_get_creation_time() - lttng_set_session_shm_path() - lttng_data_pending() |
\lt_obj_c_domain access |
-# Call lttng_list_domains(), passing the name of the recording
session of which to get the tracing domains.
This function sets a pointer to an array of
\link #lttng_domain tracing domain summaries\endlink
and returns the number of entries.
-# Access the properties of each tracing domain summary through
structure members.
-# When you're done with the array of tracing domain summaries,
free it with free() .
|
\lt_obj_c_channel access |
-# Create a \link #lttng_handle recording session handle\endlink
with lttng_create_handle() to specify the name of the
recording session and the summary of the
\lt_obj_domain of the channels to access.
-# Call lttng_list_channels(), passing the recording session
handle of step 1.
This function sets a pointer to an array of
\link #lttng_channel channel summaries\endlink
and returns the number of entries.
-# Destroy the recording session handle of step 1 with
lttng_destroy_handle().
-# Access the \ref api-channel-channel-props "properties" of each
channel summary through structure members or using dedicated
getters.
-# When you're done with the array of channel summaries,
free it with free() .
|
Activity control | See: - lttng_start_tracing() - lttng_stop_tracing() - lttng_stop_tracing_no_wait() The #LTTNG_ACTION_TYPE_START_SESSION and #LTTNG_ACTION_TYPE_STOP_SESSION trigger actions can also activate and deactivate a recording session. |
Listing |
-# Call lttng_list_sessions().
This function sets a pointer to an array of
\link #lttng_session recording session summaries\endlink
and returns the number of entries.
-# Access the properties of each recording session summary through
structure members or using dedicated getters.
-# When you're done with the array of recording session summaries,
free it with free() .
@sa \lt_man{lttng-list,1}
|
Process attribute inclusion set access | See \ref api_pais |
Clearing | See \ref api_session_clear |
Snapshot recording | See \ref api_session_snapshot The #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger action can also take a recording session snapshot. |
Rotation | See \ref api_session_rotation The #LTTNG_ACTION_TYPE_ROTATE_SESSION trigger action can also rotate a recording session. |
Saving and loading | See \ref api_session_save_load |
Trace data regeneration | See: - lttng_regenerate_metadata() - lttng_regenerate_statedump() @sa \lt_man{lttng-regenerate,1} |
Mode | Description | Descriptor creation function(s) |
---|---|---|
\anchor api-session-local-mode Local | Write the trace data to the local file system, or do not write any trace data. | - lttng_session_descriptor_create() - lttng_session_descriptor_local_create() |
\anchor api-session-net-mode Network streaming | Send the trace data over the network to a listening relay daemon (see \lt_man{lttng-relayd,8}). | lttng_session_descriptor_network_create() |
\anchor api-session-snapshot-mode Snapshot | Only write the trace data to the local file system or send it to a listening relay daemon when LTTng takes a \ref api_session_snapshot "snapshot". LTTng takes a snapshot of such a recording session when: - You call lttng_snapshot_record(). - LTTng executes an #LTTNG_ACTION_TYPE_SNAPSHOT_SESSION trigger action. LTTng forces the \ref api-channel-er-loss-mode "event record loss mode" of all the channels of such a recording session to be \"\ref api-channel-overwrite-mode "overwrite"\". | - lttng_session_descriptor_snapshot_create() - lttng_session_descriptor_snapshot_local_create() - lttng_session_descriptor_snapshot_network_create() |
\anchor api-session-live-mode Live | Send the trace data over the network to a listening relay daemon for live reading. An LTTng live reader (for example, Babeltrace 2) can connect to the same relay daemon to receive trace data while the recording session is active. | lttng_session_descriptor_live_network_create() |
Type | Description | Format |
---|---|---|
\anchor api-session-local-url Local | Send trace data to the local file system, without connecting to a relay daemon. Accepted by: - lttng_create_session() (deprecated) - lttng_create_session_snapshot() (deprecated) - lttng_snapshot_output_set_local_path() - lttng_save_session_attr_set_output_url() - lttng_load_session_attr_set_input_url() - lttng_load_session_attr_set_override_url() |
file://TRACEDIR
|
\anchor api-session-one-port-url Remote: single port | Send trace data and/or control commands to a specific relay daemon with a specific TCP port. Accepted by: - lttng_session_descriptor_network_create() - lttng_session_descriptor_snapshot_network_create() - lttng_session_descriptor_live_network_create() - lttng_snapshot_output_set_network_urls() - lttng_snapshot_output_set_ctrl_url() - lttng_snapshot_output_set_data_url() - lttng_load_session_attr_set_override_ctrl_url() - lttng_load_session_attr_set_override_data_url() |
PROTO://HOST [:PORT ][/TRACEDIR ]
|
\anchor api-session-two-port-url Remote: control and data ports | Send trace data and control commands to a specific relay daemon with specific TCP ports. This form is usually a shorthand for two \ref api-session-one-port-url "single-port output URLs" with specified ports. Accepted by: - lttng_create_session_snapshot() (deprecated) - lttng_create_session_live() (deprecated) - lttng_session_descriptor_network_create() - lttng_session_descriptor_snapshot_network_create() - lttng_session_descriptor_live_network_create() - lttng_snapshot_output_set_network_url() - lttng_snapshot_output_set_network_urls() - lttng_snapshot_output_set_ctrl_url() - lttng_load_session_attr_set_override_url() - lttng_load_session_attr_set_override_ctrl_url() |
PROTO://HOST:CTRLPORT:DATAPORT [/TRACEDIR ]
|
Domain name | Type enumerator |
---|---|
Linux kernel | #LTTNG_DOMAIN_KERNEL |
User space | #LTTNG_DOMAIN_UST |
java.util.logging (JUL)
| #LTTNG_DOMAIN_JUL |
Apache log4j | #LTTNG_DOMAIN_LOG4J |
Python logging | #LTTNG_DOMAIN_PYTHON |
java.util.logging
\endlink,
\link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink, and
\link #LTTNG_DOMAIN_PYTHON Python\endlink tracing
domains each have a default channel which you can't configure.
Note that the some functions, like lttng_enable_event_with_exclusions(),
can automatically create a default channel with sane defaults when no
channel exists for the provided \lt_obj_domain.
A channel owns \lt_obj_rers.
@image html concepts.png "A recording session contains channels that are members of tracing domains and contain recording event rules."
You can't destroy a channel.
Operation | Means |
---|---|
Creation | -# Call lttng_channel_create() with a \lt_obj_domain summary to create an initial channel summary. This function calls lttng_channel_set_default_attr() to set the properties of the created channel summary to default values depending on the tracing domain summary. -# Set the properties of the channel summary of step 1 through direct members or with dedicated setters. See the property table below. -# Create a \link #lttng_handle recording session handle\endlink structure to specify the name of the recording session and the tracing domain of the channel to create. -# Call lttng_enable_channel() with the recording session handle of step 3 and the channel summary of step 1 o create the channel. -# Destroy the recording session handle with lttng_destroy_handle() and the channel summary with lttng_channel_destroy(). @sa \lt_man{lttng-enable-channel,1} |
Basic property access | See the \ref api-channel-channel-props "property table" below. |
\lt_obj_c_rer access |
-# Create a \link #lttng_handle recording session handle\endlink
with lttng_create_handle() to specify the name of the
recording session and the summary of the
\lt_obj_domain of the channel of which to get the recording
event rule descriptors.
-# Call lttng_list_events(), passing the recording session
handle of step 1 and a channel name.
This function sets a pointer to an array of
\link #lttng_event recording event rule descriptors\endlink
and returns the number of entries.
-# Destroy the recording session handle of step 1 with
lttng_destroy_handle().
-# Access the properties of each
recording event rule descriptor through structure members or
using dedicated getters.
-# When you're done with the array of recording event rule
descriptors, free it with free() .
|
Event record context field adding | -# Initialize a #lttng_event_context structure, setting its properties to describe the context field to be added. -# Create a \link #lttng_handle recording session handle\endlink structure to specify the name of the recording session and the tracing domain of the channel to create. -# Call lttng_add_context() with the recording session handle of step 2 and the context field descriptor of step 1, optionally passing the name of the channel to target. -# Destroy the recording session handle with lttng_destroy_handle(). @sa \lt_man{lttng-add-context,1} |
Enabling | Use lttng_enable_channel(). @sa \lt_man{lttng-enable-channel,1} |
Disabling | Use lttng_disable_channel(). @sa \lt_man{lttng-disable-channel,1} |
Statistics | See: - lttng_channel_get_discarded_event_count() - lttng_channel_get_lost_packet_count() |
Property name | Description | Access |
---|---|---|
Buffering scheme | See \ref api-channel-buf-scheme "Buffering scheme". | The lttng_domain::buf_type member for the containing tracing domain. All the channels of a given tracing domain share the same buffering scheme. |
Event record loss mode | See \ref api-channel-er-loss-mode "Event record loss mode". | The lttng_channel_attr::overwrite member. |
Sub-buffer size | See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". | The lttng_channel_attr::subbuf_size member. |
Sub-buffer count | See \ref api-channel-sub-buf-size-count "Sub-buffer size and count". | The lttng_channel_attr::num_subbuf member. |
Maximum trace file size | See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". | The lttng_channel_attr::tracefile_size member. |
Maximum trace file count | See \ref api-channel-max-trace-file-size-count "Maximum trace file size and count". | The lttng_channel_attr::tracefile_count member. |
Read timer period | See \ref api-channel-read-timer "Read timer". | The lttng_channel_attr::read_timer_interval member. |
Switch timer period | See \ref api-channel-switch-timer "Switch timer". | The lttng_channel_attr::switch_timer_interval member. |
Live timer period | See \ref api-channel-live-timer "Live timer". | The \lt_p{live_timer_period} parameter of lttng_session_descriptor_live_network_create() when you create the descriptor of a \ref api-session-live-mode "live" recording session to contain the channel. |
Monitor timer period | See \ref api-channel-monitor-timer "Monitor timer". | - lttng_channel_get_monitor_timer_interval() - lttng_channel_set_monitor_timer_interval() |
Output type (Linux kernel channel) |
Whether to use mmap() or splice() .
| The lttng_channel_attr::output member. |
\anchor api-channel-blocking-timeout Blocking timeout (user space channel) | How long to block (if ever) at the instrumentation point site when a sub-buffer is not available for applications executed with the \c LTTNG_UST_ALLOW_BLOCKING environment variable set. | - lttng_channel_get_blocking_timeout() - lttng_channel_set_blocking_timeout() |
root
root
Operation | Means |
---|---|
Creation | -# Call lttng_event_create() to create an initial \link #lttng_event recording event rule descriptor\endlink. -# Set the properties of the recording event rule descriptor of step 1 through direct members or with dedicated setters. See the property table below. -# Create a \link #lttng_handle recording session handle\endlink structure to specify the name of the recording session and the tracing domain of the recording event rule to create. -# Call lttng_enable_event_with_exclusions() with the recording session handle of step 3, the recording event rule descriptor of step 1, the name of a \lt_obj_channel to which to attach the created recording event rule, and, depending on the selected function, other properties to create the rule. -# Destroy the recording session handle with lttng_destroy_handle() and the recording event rule descriptor with lttng_event_destroy(). @sa \lt_man{lttng-enable-event,1} |
Property access | See: - The members of #lttng_event - lttng_event_get_userspace_probe_location() - lttng_event_set_userspace_probe_location() - lttng_event_get_filter_expression() - lttng_event_get_exclusion_name_count() - lttng_event_get_exclusion_name() @sa \ref api-rer-conds "Recording event rule conditions". |
Enabling | With an #lttng_event instance which comes from lttng_list_events(), use lttng_enable_event(). Otherwise, use lttng_enable_event_with_exclusions(). @sa \lt_man{lttng-enable-event,1} |
Disabling | Use lttng_disable_event() or lttng_disable_event_ext(). @sa \lt_man{lttng-disable-event,1} |
Name | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
\anchor api-rer-conds-inst-pt-type \ref api-rer-conds-inst-pt-type "Instrumentation point type" |
\lt_var{E} satisfies the instrumentation point type condition
of \lt_var{ER} if the instrumentation point from which LTTng
creates \lt_var{E} is, depending on the
\lt_obj_domain which contains \lt_var{ER}:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
\anchor api-rer-conds-event-name \ref api-rer-conds-event-name "Event name" |
An event \lt_var{E} satisfies the event name condition
of \lt_var{ER} if the two following statements are
\b true:
- \link lttng_event::name event_rule.name \endlink
matches, depending on
\link lttng_event::type event_rule.type \endlink
(see \ref api-rer-conds-inst-pt-type "Instrumentation point type"
above):
event_rule.type \endlink
is #LTTNG_EVENT_TRACEPOINT or
#LTTNG_EVENT_SYSCALL: it's always satisfied for the other
\ref api-rer-conds-inst-pt-type "instrumentation point types".
In all cases,
\link lttng_event::name event_rule.name \endlink
and the event name exclusion patterns of
\c event_rule are globbing patterns: the
* character means "match anything". To match a
literal * character, use \\* .
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
\anchor api-rer-conds-ll \ref api-rer-conds-ll "Instrumentation point log level" |
An event \lt_var{E} satisfies the instrumentation point
log level condition of \lt_var{ER} if, depending on
\link lttng_event::loglevel_type event_rule.loglevel_type \endlink,
the log level of the LTTng user space tracepoint or
logging statement from which LTTng creates \lt_var{E}
is:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
\anchor api-rer-conds-filter \ref api-rer-conds-filter "Event payload and context filter" |
An event \lt_var{E} satisfies the event payload and
context filter condition of \lt_var{ER} if
\c event_rule has no filter expression or if its filter
expression \lt_var{EXPR} evaluates to \b true
when LTTng creates \lt_var{E}.
This condition is only meaningful when:
- The \lt_obj_domain containing \lt_var{ER} is
#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST: it's always
satisfied for the other tracing domains.
- \link lttng_event::type event_rule.type \endlink
is #LTTNG_EVENT_TRACEPOINT or #LTTNG_EVENT_SYSCALL:
it's always satisfied for the other
\ref api-rer-conds-inst-pt-type "instrumentation point types".
Set the event payload and context filter expression of
\c event_rule when you call
lttng_enable_event_with_exclusions().
Get the event payload and context filter expression of
a recording event rule descriptor with
lttng_event_get_filter_expression().
\lt_var{EXPR} can contain references to the payload fields
of \lt_var{E} and to the current
\link #lttng_event_context_type context\endlink fields.
The expected syntax of \lt_var{EXPR} is similar to the syntax
of a C language conditional expression (an expression
which an \c if statement can evaluate), but there are a few
differences:
- A NAME expression identifies an event
payload field named NAME (a
C identifier).
Use the C language dot and square bracket notations to
access nested structure and array/sequence fields. You can
only use a constant, positive integer number within square
brackets. If the index is out of bounds, \lt_var{EXPR} is
\b false.
The value of an enumeration field is an integer.
When a field expression doesn't exist, \lt_var{EXPR} is
\b false.
Examples: my_field , target_cpu ,
seq[7] , msg.user[1].data[2][17] .
- A $ctx.TYPE expression identifies the
statically-known context field having the type
TYPE (a C identifier).
When a field expression doesn't exist, \lt_var{EXPR} is \b
false.
Examples: $ctx.prio ,
$ctx.preemptible ,
$ctx.perf:cpu:stalled-cycles-frontend .
- A $app.PROVIDER:TYPE
expression identifies the application-specific context field
having the type TYPE (a
C identifier) from the provider
PROVIDER (a C identifier).
When a field expression doesn't exist, \lt_var{EXPR} is \b
false.
Example: $app.server:cur_user .
- Compare strings, either string fields or string literals
(double-quoted), with the == and
!= operators.
When comparing to a string literal, the *
character means "match anything". To match a literal
* character, use \\* .
Examples: my_field == "user34" ,
my_field == my_other_field ,
my_field == "192.168.*" .
- The
precedence table
of the operators which are supported in
\lt_var{EXPR} is as follows. In this table, the highest
precedence is 1:
& and | ) in
\lt_var{EXPR} take precedence over relational
operators (<< , <= ,
> , >= , == ,
and != ). This means the expression
2 & 2 == 2
is \b true while the equivalent C expression
is \b false.
The arithmetic operators are :not: supported.
LTTng first casts all integer constants and fields to signed
64-bit integers. The representation of negative integers is
two's complement. This means that, for example, the signed
8-bit integer field 0xff (-1) becomes 0xffffffffffffffff
(still -1) once casted.
Before a bitwise operator is applied, LTTng casts all its
operands to unsigned 64-bit integers, and then casts the
result back to a signed 64-bit integer. For the bitwise NOT
operator, it's the equivalent of this C expression:
@code
(int64_t) ~((uint64_t) val)
@endcode
For the binary bitwise operators, it's the equivalent of those
C expressions:
@code
(int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
(int64_t) ((uint64_t) lhs << (uint64_t) rhs)
(int64_t) ((uint64_t) lhs & (uint64_t) rhs)
(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
(int64_t) ((uint64_t) lhs | (uint64_t) rhs)
@endcode
If the right-hand side of a bitwise shift operator
(<< and >> ) is not in
the [0, 63] range, then \lt_var{EXPR} is \b false.
@note
See the \ref api_pais to allow or disallow processes to
record LTTng events based on their attributes
instead of using equivalent statically-known context
fields in \lt_var{EXPR} like $ctx.pid .
The former method is much more efficient.
\lt_var{EXPR} examples:
@code{.unparsed}
msg_id == 23 && size >= 2048
@endcode
@code{.unparsed}
$ctx.procname == "lttng*" && (!flag || poel < 34)
@endcode
@code{.unparsed}
$app.my_provider:my_context == 17.34e9 || some_enum >= 14
@endcode
@code{.unparsed}
$ctx.cpu_id == 2 && filename != "*.log"
@endcode
@code{.unparsed}
eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
@endcode
|
Tracing domain | Instrumentation point type | Event record name |
---|---|---|
#LTTNG_DOMAIN_KERNEL or #LTTNG_DOMAIN_UST | #LTTNG_EVENT_TRACEPOINT |
Full name of the tracepoint from which LTTng creates \lt_var{E}.
Note that the full name of a
\link #LTTNG_DOMAIN_UST user space\endlink tracepoint is
PROVIDER:NAME , where
PROVIDER is the tracepoint provider name and
NAME is the tracepoint name.
|
#LTTNG_DOMAIN_JUL | #LTTNG_EVENT_TRACEPOINT |
lttng_jul:event
Such an event record has a string field logger_name
which contains the name of the java.util.logging
logger from which LTTng creates \lt_var{E}.
|
#LTTNG_DOMAIN_LOG4J | #LTTNG_EVENT_TRACEPOINT |
lttng_log4j:event
Such an event record has a string field logger_name
which contains the name of the Apache log4j logger from which
LTTng creates \lt_var{E}.
|
#LTTNG_DOMAIN_PYTHON | #LTTNG_EVENT_TRACEPOINT |
lttng_python:event
Such an event record has a string field logger_name
which contains the name of the Python logger from which LTTng
creates \lt_var{E}.
|
#LTTNG_DOMAIN_KERNEL | #LTTNG_EVENT_SYSCALL |
Location:
|
#LTTNG_DOMAIN_KERNEL | #LTTNG_EVENT_PROBE or #LTTNG_EVENT_USERSPACE_PROBE | The lttng_event::name member of the descriptor you used to create \lt_var{ER} with lttng_enable_event_with_exclusions(). |
#LTTNG_DOMAIN_KERNEL | #LTTNG_EVENT_FUNCTION |
Location:
NAME is the lttng_event::name member
of the descriptor you used to create
\lt_var{ER} with lttng_enable_event_with_exclusions().
|