lttng-enable-channel - Man Page

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:

Discard

Drop the newest events until a sub-buffer is released.

Overwrite

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):

High event throughput

Low event throughput

Low memory system

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:

Per-process buffering (--buffers-pid option)

Per-user buffering (--buffers-uid option)

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.

One of:

-k, --kernel

Enable channel in the Linux kernel domain.

-u, --userspace

Enable channel in the user space domain.

-s SESSION, --session=SESSION

Create or enable channel in the tracing session named SESSION instead of the current tracing session.

--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:

0 (default)

Do not block (non-blocking mode).

inf

Block forever until room is available in the sub-buffer to write the event record.

n, a positive value

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.