lttng-enable-channel — Create or enable LTTng channels
Create a Linux kernel channel:
lttng [GENERAL OPTIONS] enable-channel--kernel
[--overwrite
] [--output
=(mmap
|splice
)] [--subbuf-size
=SIZE
] [--num-subbuf
=COUNT
] [--switch-timer
=PERIODUS
] [--read-timer
=PERIODUS
] [--monitor-timer
=PERIODUS
] [--tracefile-size
=SIZE
] [--tracefile-count
=COUNT
] [--session
=SESSION
]CHANNEL
Create a user space channel:
lttng [GENERAL OPTIONS] enable-channel--userspace
[--overwrite
|--blocking-timeout
=TIMEOUTUS
] [--buffers-pid
] [--subbuf-size
=SIZE
] [--num-subbuf
=COUNT
] [--switch-timer
=PERIODUS
] [--read-timer
=PERIODUS
] [--monitor-timer
=PERIODUS
] [--tracefile-size
=SIZE
] [--tracefile-count
=COUNT
] [--session
=SESSION
]CHANNEL
Enable existing channel(s):
lttng [GENERAL OPTIONS] enable-channel (--userspace
|--kernel
) [--session
=SESSION
]CHANNEL
[,CHANNEL
]…
The lttng enable-channel
command can create a new channel, or enable
one or more existing and disabled ones.
A channel is the owner of sub-buffers holding recorded events. Event, rules, when created using lttng-enable-event(1), are always assigned to a channel. When creating a new channel, many parameters related to those sub-buffers can be fine-tuned. They are described in the subsections below.
When CHANNEL
does not name an existing channel, a channel named
CHANNEL
is created. Otherwise, the disabled channel named CHANNEL
is enabled.
Note that the lttng-enable-event(1) command can automatically create default channels when no channel exist.
A channel is always contained in a tracing session
(see lttng-create(1) for creating a tracing session). The
session in which a channel is created using lttng enable-channel
can
be specified using the --session
option. If the --session
option is omitted, the current tracing session is targeted.
Existing enabled channels can be disabled using lttng-disable-channel(1). Channels of a given session can be listed using lttng-list(1).
See the LIMITATIONS section below for a list of limitations of this command to consider.
LTTng tracers are non-blocking by default: when no empty sub-buffer exists, losing events is acceptable when the alternative would be to cause substantial delays in the instrumented application’s execution.
LTTng privileges performance over integrity, aiming at perturbing the traced system as little as possible in order to make tracing of subtle race conditions and rare interrupt cascades possible.
You can allow the user space tracer to block with a
--blocking-timeout
option set to a positive value or to inf
,
and with an application which is instrumented with LTTng-UST started
with a set LTTNG_UST_ALLOW_BLOCKING
environment variable. See
lttng-ust(3) for more details.
When it comes to losing events because no empty sub-buffer is available,
the channel’s event loss mode, specified by one of the --discard
and --overwrite
options, determines what to do amongst:
Drop the newest events until a sub-buffer is released.
Clear the sub-buffer containing the oldest recorded events and start recording the newest events there. This mode is sometimes called flight recorder mode because it behaves like a flight recorder: always keep a fixed amount of the latest data.
Which mechanism to choose depends on the context: prioritize the newest or the oldest events in the ring buffer?
Beware that, in overwrite mode (--overwrite
option), a whole
sub-buffer is abandoned as soon as a new event doesn’t find an empty
sub-buffer, whereas in discard mode (--discard
option), only the
event that doesn’t fit is discarded.
Also note that a count of lost events is incremented and saved in the trace itself when an event is lost in discard mode, whereas no information is kept when a sub-buffer gets overwritten before being committed.
The probability of losing events, if it is experience in a given context, can be reduced by fine-tuning the sub-buffers count and size (see next subsection).
The --num-subbuf
and --subbuf-size
options respectively
set the number of sub-buffers and their individual size when creating
a new channel.
Note that there is a noticeable tracer’s CPU overhead introduced when
switching sub-buffers (marking a full one as consumable and switching
to an empty one for the following events to be recorded). Knowing this,
the following list presents a few practical situations along with how
to configure sub-buffers for them when creating a channel in overwrite
mode (--overwrite
option):
In general, prefer bigger sub-buffers to lower the risk of losing events. Having bigger sub-buffers also ensures a lower sub-buffer switching frequency. The number of sub-buffers is only meaningful if the channel is enabled in overwrite mode: in this case, if a sub-buffer overwrite happens, the other sub-buffers are left unaltered.
In general, prefer smaller sub-buffers since the risk of losing events is already low. Since events happen less frequently, the sub-buffer switching frequency should remain low and thus the tracer’s overhead should not be a problem.
If the target system has a low memory limit, prefer fewer first, then smaller sub-buffers. Even if the system is limited in memory, it is recommended to keep the sub-buffers as big as possible to avoid a high sub-buffer switching frequency.
In discard mode (--discard
option), the sub-buffers count
parameter is pointless: using two sub-buffers and setting their size
according to the requirements of the context is fine.
When a channel’s switch timer fires, a sub-buffer switch happens. This timer may be used to ensure that event data is consumed and committed to trace files periodically in case of a low event throughput.
It’s also convenient when big sub-buffers are used to cope with sporadic high event throughput, even if the throughput is normally lower.
Use the --switch-timer
option to control the switch timer’s
period of the channel to create.
By default, an internal notification mechanism is used to signal a full sub-buffer so that it can be consumed. When such notifications must be avoided, for example in real-time applications, the channel’s read timer can be used instead. When the read timer fires, sub-buffers are checked for consumption when they are full.
Use the --read-timer
option to control the read timer’s period of
the channel to create.
When a channel’s monitor timer fires, its registered trigger conditions are evaluated using the current values of its properties (for example, the current usage of its sub-buffers). When a trigger condition is true, LTTng executes its associated action. The only type of action currently supported is to notify one or more user applications.
See the installed C/C++ headers in lttng/action
,
lttng/condition
, lttng/notification
, and lttng/trigger
to learn
more about application notifications and triggers.
Use the --monitor-timer
option to control the monitor timer’s
period of the channel to create.
In the user space tracing domain, two buffering schemes are available when creating a channel:
--buffers-pid
option)
Keep one ring buffer per process.
--buffers-uid
option)
Keep one ring buffer for all the processes of a single user.
The per-process buffering scheme consumes more memory than the per-user option if more than one process is instrumented for LTTng-UST. However, per-process buffering ensures that one process having a high event throughput won’t fill all the shared sub-buffers, only its own.
The Linux kernel tracing domain only has one available buffering scheme
which is to use a single ring buffer for the whole system
(--buffers-global
option).
By default, trace files can grow as large as needed. The maximum size
of each trace file written by a channel can be set on creation using the
--tracefile-size
option. When such a trace file’s size reaches
the channel’s fixed maximum size, another trace file is created to hold
the next recorded events. A file count is appended to each trace file
name in this case.
If the --tracefile-size
option is used, the maximum number of
created trace files is unlimited. To limit them, the
--tracefile-count
option can be used. This option is always used
in conjunction with the --tracefile-size
option.
For example, consider this command:
$
lttng enable-channel --kernel --tracefile-size=4096 \ --tracefile-count=32 my-channel
Here, for each stream, the maximum size of each trace file is 4 kiB and there can be a maximum of 32 different files. When there is no space left in the last file, trace file rotation happens: the first file is cleared and new sub-buffers containing events are written there.
LTTng does not guarantee that you can view the trace of an active tracing session before you run the lttng-stop(1) command, even with multiple trace files, because LTTng could overwrite them at any moment, or some of them could be incomplete. You can archive a tracing session’s current trace chunk while the tracing session is active to obtain an unmanaged and self-contained LTTng trace: see the lttng-rotate(1) and lttng-enable-rotation(1) commands.
General options are described in lttng(1).
One of:
-k
, --kernel
Enable channel in the Linux kernel domain.
-u
, --userspace
Enable channel in the user space domain.
--blocking-timeout
=TIMEOUTUS
Set the channel’s blocking timeout value to TIMEOUTUS
µs for
instrumented applications executed with a set
LTTNG_UST_ALLOW_BLOCKING
environment variable:
Do not block (non-blocking mode).
inf
Block forever until room is available in the sub-buffer to write the event record.
Wait for at most n µs when trying to write into a sub-buffer. After n µs, discard the event record.
This option is only available with the --userspace
option and
without the --overwrite
option.
One of:
--discard
Discard events when sub-buffers are full (default).
--overwrite
Flight recorder mode: always keep a fixed amount of the latest data.
--num-subbuf
=COUNT
Use COUNT
sub-buffers. Rounded up to the next power of two.
Default values:
--userspace
and --buffers-uid
options:
4
--userspace
and --buffers-pid
options:
4
--kernel
option: 4
metadata
channel: 2
--output
=TYPE
Set channel’s output type to TYPE
.
Available types: mmap
(always available) and splice
(only available
with the --kernel
option).
Default values:
--userspace
and --buffers-uid
options: mmap
--userspace
and --buffers-pid
options: mmap
--kernel
option: splice
metadata
channel: mmap
--subbuf-size
=SIZE
Set the individual size of sub-buffers to SIZE
bytes.
The k
(kiB), M
(MiB), and G
(GiB) suffixes are supported.
Rounded up to the next power of two.
The minimum sub-buffer size, for each tracer, is the maximum value
between the default below and the system’s page size. The following
command shows the current system’s page size: getconf PAGE_SIZE
.
Default values:
--userspace
and --buffers-uid
options:
524288
--userspace
and --buffers-pid
options:
16384
--kernel
option: 1048576
metadata
channel: 4096
One of:
--buffers-global
Use shared sub-buffers for the whole system (only available with the
--kernel
option).
--buffers-pid
Use different sub-buffers for each traced process (only available
with the the --userspace
option). This is the default
buffering scheme for user space channels.
--buffers-uid
Use shared sub-buffers for all the processes of the user running
the command (only available with the --userspace
option).
--tracefile-count
=COUNT
Limit the number of trace files created by this channel to
COUNT
. 0 means unlimited. Default:
0.
Use this option in conjunction with the --tracefile-size
option.
The file count within a stream is appended to each created trace
file. If COUNT
files are created and more events need to be recorded,
the first trace file of the stream is cleared and used again.
--tracefile-size
=SIZE
Set the maximum size of each trace file written by
this channel within a stream to SIZE
bytes. 0 means unlimited.
Default: 0.
Note: traces generated with this option may inaccurately report discarded events as of CTF 1.8.
--monitor-timer
Set the channel’s monitor timer’s period to PERIODUS
µs. 0 means a
disabled monitor timer.
Default values:
--userspace
and --buffers-uid
options:
1000000
--userspace
and --buffers-pid
options:
1000000
--kernel
option: 1000000
--read-timer
Set the channel’s read timer’s period to PERIODUS
µs. 0 means a
disabled read timer.
Default values:
--userspace
and --buffers-uid
options:
0
--userspace
and --buffers-pid
options:
0
--kernel
option: 200000
metadata
channel: 0
--switch-timer
=PERIODUS
Set the channel’s switch timer’s period to PERIODUS
µs. 0 means
a disabled switch timer.
Default values:
--userspace
and --buffers-uid
options:
0
--userspace
and --buffers-pid
options:
0
--kernel
option: 0
metadata
channel: 0
-h
, --help
Show command help.
This option, like lttng-help(1), attempts to launch
/usr/bin/man
to view the command’s man page. The path to the man pager
can be overridden by the LTTNG_MAN_BIN_PATH
environment variable.
--list-options
List available command options.
As of this version of LTTng, it is not possible to perform the following
actions with the lttng enable-channel
command:
Reconfigure a channel once it is created.
Re-enable a disabled channel once its tracing session has been active at least once.
Create a channel once its tracing session has been active at least once.
Create a user space channel with a given buffering scheme
(--buffers-uid
or --buffers-pid
options) and create
a second user space channel with a different buffering scheme in the
same tracing session.
LTTNG_ABORT_ON_ERROR
Set to 1 to abort the process after the first error is encountered.
LTTNG_HOME
Overrides the $HOME
environment variable. Useful when the user
running the commands has a non-writable home directory.
LTTNG_MAN_BIN_PATH
Absolute path to the man pager to use for viewing help information
about LTTng commands (using lttng-help(1) or
lttng COMMAND --help
).
LTTNG_SESSION_CONFIG_XSD_PATH
Path in which the session.xsd
session configuration XML
schema may be found.
LTTNG_SESSIOND_PATH
Full session daemon binary path.
The --sessiond-path
option has precedence over this
environment variable.
Note that the lttng-create(1) command can spawn an LTTng session daemon automatically if none is running. See lttng-sessiond(8) for the environment variables influencing the execution of the session daemon.
$LTTNG_HOME/.lttngrc
User LTTng runtime configuration.
This is where the per-user current tracing session is stored between executions of lttng(1). The current tracing session can be set with lttng-set-session(1). See lttng-create(1) for more information about tracing sessions.
$LTTNG_HOME/lttng-traces
Default output directory of LTTng traces. This can be overridden
with the --output
option of the lttng-create(1)
command.
$LTTNG_HOME/.lttng
User LTTng runtime and configuration directory.
$LTTNG_HOME/.lttng/sessions
Default location of saved user tracing sessions (see lttng-save(1) and lttng-load(1)).
/etc/lttng/sessions
System-wide location of saved tracing sessions (see lttng-save(1) and lttng-load(1)).
Note:$LTTNG_HOME
defaults to $HOME
when not explicitly set.
Success
Command error
Undefined command
Fatal error
Command warning (something went wrong during the command)
If you encounter any issue or usability problem, please report it on the LTTng bug tracker.
Mailing list for support and
development: lttng-dev@lists.lttng.org
IRC channel: #lttng
on irc.oftc.net
This program is part of the LTTng-tools project.
LTTng-tools is distributed under the
GNU General
Public License version 2. See the
LICENSE
file
for details.
Special thanks to Michel Dagenais and the DORSAL laboratory at École Polytechnique de Montréal for the LTTng journey.
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases.