lttng-enable-channel - Man Page

Create or enable LTTng channels

Synopsis

Create a Linux kernel channel:

lttng [GENERAL OPTIONS] enable-channel --kernel
      [--discard | --overwrite] [--output=(mmap | splice)]
      [--subbuf-size=SIZE] [--num-subbuf=COUNT]
      [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
      [--monitor-timer=PERIODUS]
      [--buffer-ownership=system] [--buffer-allocation=per-cpu]
      [--tracefile-size=SIZE [--tracefile-count=COUNT]]
      [--session=SESSION] CHANNEL

Create a user space channel:

lttng [GENERAL OPTIONS] enable-channel --userspace
      [--overwrite | [--discard] --blocking-timeout=TIMEOUTUS]
      [--output=mmap] [--buffer-ownership=(user | process)]
      [--buffer-allocation=(per-cpu | per-channel)]
      [--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 channel(s):

lttng [GENERAL OPTIONS] enable-channel (--userspace | --kernel)
      [--session=SESSION] CHANNEL[,CHANNEL]...

Description

The lttng enable-channel command does one of:

Create a channel named CHANNEL.
Enable one or more disabled channels named CHANNEL (non-option argument, comma-separated).

See lttng-concepts(7) to learn more about channels.

The channel(s) to create or enable belong to:

With the --session=SESSION option: The recording session named SESSION.
Without the --session option: The current recording session (see lttng-concepts(7) to learn more about the current recording session).
Note: The lttng-enable-event(1) command can automatically create a default channel when no channel exists for the provided tracing domain.

See the “Examples” section below for usage examples.

List the channels of a given recording session with the lttng-list(1) and lttng-status(1) commands.

Disable an enabled channel with the lttng-disable-channel(1) command.
Important

As of LTTng 2.14.0, you may NOT perform the following operations with the enable-channel command:

Change an attribute of an existing channel.
Enable a disabled channel once its recording session has been active (started; see lttng-start(1)) at least once.
Create a channel once its recording session has been active at least once.
Create a user space channel with a given buffer ownership model (--buffer-ownership set to user or process) and create a second user space channel with a different buffer ownership model in the same recording session.

Options

See lttng(1) for GENERAL OPTIONS.

Tracing domain

One of:

-k, --kernel: Create or enable channels in the Linux kernel domain.
-u, --userspace: Create or enable channels in the user space domain.

Recording target

-s SESSION, --session=SESSION: Create or enable channels in the recording session named SESSION instead of the current recording session.

Buffer ownership model

One of:

--buffers-global

Equivalent to --buffer-ownership=system.

Deprecated.

--buffer-ownership=MODEL

Depending on MODEL:

process

Allocate one set of ring buffers (one per CPU or one for the whole channel, depending on --buffer-allocation) for each instrumented process of:

If you connect to the root session daemon

All Unix users.

See the “Session daemon connection” section of lttng(1) to learn how a user application connects to a session daemon.

Otherwise: Your Unix user.

Only available with the --userspace option.

system

Allocate a single set of ring buffers (one per CPU) for the whole system.

Only available with the --kernel option.

As of LTTng 2.14.0, this is the default buffer ownership model for the Linux kernel tracing domain, but this may change in the future.

user

Allocate one set of ring buffers (one per CPU or one for the whole channel, depending on --buffer-allocation) shared by all the instrumented processes of:

If you connect to the root session daemon

Each Unix user.

See the “Session daemon connection” section of lttng(1) to learn how a user application connects to a session daemon.

Otherwise: Your Unix user.

Only available with the --userspace option.

As of LTTng 2.14.0, this is the default buffer ownership model for the user space tracing domain, but this may change in the future.

--buffers-pid

Equivalent to --buffer-ownership=process.

Deprecated.

--buffers-uid

Equivalent to --buffer-ownership=user.

Deprecated.

Buffer allocation policy

--buffer-allocation=POLICY

Depending on POLICY, allocate one ring buffer for:

per-channel

The whole channel.

Setting --buffer-ownership to user or process determines what entity gets a channel-wise ring buffer.

Only available with the --userspace option.

per-cpu

Each CPU.

Setting --buffer-ownership to user, process, or system determines what entity gets a set of per-CPU ring buffers.

Using this buffer allocation policy implies adding the cpu_id context field, without any way to remove it, for the created channel, similar to running:

$ lttng add-context --session=SESSION --channel=CHANNEL \
                    --type=cpu_id

As of LTTng 2.14.0, this is the default buffer allocation policy, but this may change in the future.

Event record loss mode

--blocking-timeout=TIMEOUTUS

Set the blocking timeout value of the channel to TIMEOUTUS µs for instrumented applications executed with a set LTTNG_UST_ALLOW_BLOCKING environment variable.

TIMEOUTUS is one of:

0 (default): Do not block (non-blocking mode).
inf: Block forever until a sub-buffer is available to write the event record.
N, a positive value: Wait for at most N µs when trying to write to a sub-buffer. After N µs, discard the event record.

This option is only available with both the --userspace and --discard options.

One of:

--discard

Discard event records when there’s no available sub-buffer.

As of LTTng 2.14.0, this is the default event record loss mode, but this may change in the future.

--overwrite

Overwrite the whole sub-buffer containing the oldest event records when there’s no available sub-buffer (flight recorder mode).

Sub-buffers

--num-subbuf=COUNT

Use COUNT sub-buffers per ring buffer.

The effective value is COUNT rounded up to the next power of two.

Default values:

--userspace and --buffer-ownership=user options: 4
--userspace and --buffer-ownership=process options: 4
--kernel and --buffer-ownership=system options: 4

metadata channel

--output=TYPE

Set the output type of the channel to TYPE.

TYPE is one of:

mmap

Share ring buffers between the tracer and the consumer daemon with the mmap(2) system call.

splice

Share ring buffers between the tracer and the consumer daemon with the splice(2) system call.

Only available with the --kernel option.

Default values:

--userspace and --buffer-ownership=user options: mmap
--userspace and --buffer-ownership=process options: mmap
--kernel and --buffer-ownership=system options: splice
metadata channel: mmap

--subbuf-size=SIZE

Set the size of each sub-buffer to SIZE bytes.

The effective value is SIZE rounded up to the next power of two.

The k (KiB), M (MiB), and G (GiB) suffixes are supported.

The minimum sub-buffer size, for each tracer, is the maximum value between the default below and the system page size (see getconf(1) with the PAGE_SIZE variable).

Default values:

--userspace and --buffer-ownership=user options: 524288
--userspace and --buffer-ownership=process options: 16384
--kernel and --buffer-ownership=system options: 1048576

metadata channel

4096

Trace files

--tracefile-count=COUNT

Limit the number of trace files which LTTng writes for this channel to COUNT.

COUNT set to 0 means “unlimited”.

Default: 0.

You must also use the --tracefile-size option with this option.

--tracefile-size=SIZE

Set the maximum size of each trace file which LTTng writes for this channel to SIZE bytes.

SIZE set to 0 means “unlimited”.

Default: 0.
Note

Data streams which LTTng writes for a channel configured with this option may inaccurately report discarded event records as of CTF 1.8.

Timers

--monitor-timer=PERIODUS

Set the period of the monitor timer of the channel to PERIODUS µs.

Set PERIODUS to 0 to disable the monitor timer.

Default values:

--userspace and --buffer-ownership=user options: 1000000
--userspace and --buffer-ownership=process options: 1000000
--kernel and --buffer-ownership=system options: 1000000

--read-timer=PERIODUS

Set the period of the read timer of the channel to PERIODUS µs.

Set PERIODUS to 0 to disable the read timer.

Default values:

--userspace and --buffer-ownership=user options: 0
--userspace and --buffer-ownership=process options: 0
--kernel and --buffer-ownership=system options: 200000

metadata channel

--switch-timer=PERIODUS

Set the period of the switch timer of the channel to PERIODUS µs.

Set PERIODUS to 0 to disable the switch timer.

Default values:

--userspace and --buffer-ownership=user options: 0
--userspace and --buffer-ownership=process options: 0
--kernel and --buffer-ownership=system options: 0

metadata channel

Program information

-h, --help

Show help.

This option attempts to launch /usr/bin/man to view this manual page. Override the manual pager path with the LTTNG_MAN_BIN_PATH environment variable.

--list-options

List available command options and quit.

Exit Status

0: Success
1: Command error
2: Undefined command
3: Fatal error
4: Command warning (something went wrong during the command)

Environment

LTTNG_ABORT_ON_ERROR

Set to 1 to abort the process after the first error is encountered.

LTTNG_HOME

Path to the LTTng home directory.

Defaults to $HOME.

Useful when the Unix user running the commands has a non-writable home directory.

LTTNG_MAN_BIN_PATH

Absolute path to the manual pager to use to read the LTTng command-line help (with lttng-help(1) or with the --help option) instead of /usr/bin/man.

LTTNG_SESSION_CONFIG_XSD_PATH

Path to the directory containing the session.xsd recording session configuration XML schema.

LTTNG_SESSIOND_PATH

Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from the lttng-create(1) command.

The --sessiond-path general option overrides this environment variable.

Files

$LTTNG_HOME/.lttngrc

Unix user’s LTTng runtime configuration.

This is where LTTng stores the name of the Unix user’s current recording session between executions of lttng(1). lttng-create(1) and lttng-set-session(1) set the current recording session.

$LTTNG_HOME/lttng-traces

Default output directory of LTTng traces in local and snapshot modes.

Override this path with the --output option of the lttng-create(1) command.

$LTTNG_HOME/.lttng

Unix user’s LTTng runtime and configuration directory.

$LTTNG_HOME/.lttng/sessions

Default directory containing the Unix user’s saved recording session configurations (see lttng-save(1) and lttng-load(1)).

/usr/local/etc/lttng/sessions

Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).

Note

$LTTNG_HOME defaults to the value of the HOME environment variable.

Examples

Example 1. Create a Linux kernel channel with default attributes in the current recording session.

The following command line only creates a new channel if my-channel doesn’t name an existing Linux kernel channel in the current recording session.

$ lttng enable-channel --kernel my-channel

Example 2. Create a user space channel with a per-process buffer ownership model in a specific recording session.

See the --session and --buffer-ownership options.

$ lttng enable-channel --session=my-session --userspace \
                       --buffer-ownership=process my-channel

Example 3. Create a user space channel with a per-user buffer ownership model (default) and a per-channel buffer allocation policy.

See the --buffer-allocation option.

$ lttng enable-channel --userspace \
                       --buffer-allocation=per-channel my-channel

Example 4. Create a Linux kernel channel in the current recording session with four 32-MiB sub-buffers per ring buffer.

See the --num-subbuf and --subbuf-size options.

$ lttng enable-channel --kernel my-channel \
                       --num-subbuf=4 --subbuf-size=32M

Example 5. Create a user space channel in the current recording session with trace file rotation.

See the --tracefile-count and --tracefile-size options.

$ lttng enable-channel --userspace my-channel \
                       --tracefile-count=16 --tracefile-size=8M

Example 6. Enable two user space channels of a specific recording session.

$ lttng enable-channel --session=my-session --userspace \
                       canal-d,rds

Resources

LTTng project website <https://lttng.org>
LTTng documentation <https://lttng.org/docs>
LTTng bug tracker <https://bugs.lttng.org>
Git repositories <https://git.lttng.org>
GitHub organization <https://github.com/lttng>
Continuous integration <https://ci.lttng.org/>
Mailing list <https://lists.lttng.org/> for support and development: lttng-dev@lists.lttng.org
IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
Mastodon <https://mastodon.social/@lttng>

lttng-enable-channel - Man Page

Synopsis

Description

Options

Tracing domain

Recording target

Buffer ownership model

Buffer allocation policy

Event record loss mode

Sub-buffers

Trace files

Timers

Program information

Exit Status

Environment

Files

Examples

Resources

Copyright

Thanks

See Also

Referenced By