---
name: "lttng-enable-channel"
section: "1"
platform: "linux"
package: "lttng-tools"
version: "2.13.15-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/lttng-enable-channel"
---

# lttng-enable-channel(1)

Create or enable LTTng channels

## NAME

lttng-enable-channel - 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] [--buffers-global]
      [--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] [--buffers-uid | --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 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)](/lttng-concepts/7.md) 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)](/lttng-concepts/7.md) to learn more about the current recording session).

**Note**\

The [**lttng-enable-event**(1)](/lttng-enable-event/1.md) 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)](/lttng-list/1.md) and [**lttng-status**(1)](/lttng-status/1.md) commands.

Disable an enabled channel with the [**lttng-disable-channel**(1)](/lttng-disable-channel/1.md) command.

**Important**\

As of LTTng 2.13.15, 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)](/lttng-start/1.md)) at least once.

• Create a channel once its recording 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 recording session.

## OPTIONS

See [**lttng**(1)](/lttng/1.md) 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.

### Buffering scheme

One of:

- **--buffers-global**

  Allocate a single set of ring buffers for the whole system.

  Only available with the **--kernel** option.

  As of LTTng 2.13.15, this is the default buffering scheme for the Linux kernel tracing domain, but this may change in the future.

- **--buffers-pid**

  Allocate one set of ring buffers (one per CPU) 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)](/lttng/1.md) to learn how a user application connects to a session daemon.

  Otherwise

  Your Unix user.

  Only available with the **--userspace** option.

- **--buffers-uid**

  Allocate one set of ring buffers (one per CPU) 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)](/lttng/1.md) 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.13.15, this is the default buffering scheme for the user space tracing domain, but this may change in the future.

### Event record loss mode

- **--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.

  *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.13.15, 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 **--buffers-uid** options

  **4**

  **--userspace** and **--buffers-pid** options

  **4**

  **--kernel** and **--buffers-global** options

  **4**

  **metadata** channel

  **2**

- **--output**=*TYPE*

  Set channel’s output type to *TYPE*.

  *TYPE* is one of:

  **mmap**

  Share ring buffers between the tracer and the consumer daemon with the [**mmap**(2)](/mmap/2.md) system call.

  **splice**

  Share ring buffers between the tracer and the consumer daemon with the [**splice**(2)](/splice/2.md) system call.

  Only available with the **--kernel** option.

  Default values:

  **--userspace** and **--buffers-uid** options

  **mmap**

  **--userspace** and **--buffers-pid** options

  **mmap**

  **--kernel** and **--buffers-global** 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)](/getconf/1.md) with the **PAGE\_SIZE** variable).

  Default values:

  **--userspace** and **--buffers-uid** options

  **524288**

  **--userspace** and **--buffers-pid** options

  **16384**

  **--kernel** and **--buffers-global** 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 **--buffers-uid** options

  **1000000**

  **--userspace** and **--buffers-pid** options

  **1000000**

  **--kernel** and **--buffers-global** 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 **--buffers-uid** options

  **0**

  **--userspace** and **--buffers-pid** options

  **0**

  **--kernel** and **--buffers-global** options

  **200000**

  **metadata** channel

  **0**

- **--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 **--buffers-uid** options

  **0**

  **--userspace** and **--buffers-pid** options

  **0**

  **--kernel** and **--buffers-global** options

  **0**

  **metadata** channel

  **0**

### 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)](/lttng-help/1.md) 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)](/lttng-sessiond/8.md)) to spawn from the [**lttng-create**(1)](/lttng-create/1.md) 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/1.md). [**lttng-create**(1)](/lttng-create/1.md) and [**lttng-set-session**(1)](/lttng-set-session/1.md) 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)](/lttng-create/1.md) 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)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)).

**/etc/lttng/sessions**

Directory containing the system-wide saved recording session configurations (see [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)).

**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 buffering scheme in a specific recording session.**

See the **--session** and **--buffers-pid** options.

```
$ lttng enable-channel --session=my-session --userspace \
                       --buffers-pid my-channel
```

**Example 3. 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 4. 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 5. 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**

## COPYRIGHT

This program is part of the LTTng-tools project.

LTTng-tools is distributed under the GNU General Public License version 2 \<http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html\>. See the **LICENSE** \<https://github.com/lttng/lttng-tools/blob/master/LICENSE\> file for details.

## THANKS

Special thanks to Michel Dagenais and the DORSAL laboratory \<http://www.dorsal.polymtl.ca/\> 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.

## SEE ALSO

[**lttng**(1)](/lttng/1.md), [**lttng-disable-channel**(1)](/lttng-disable-channel/1.md), [**lttng-list**(1)](/lttng-list/1.md), [**lttng-concepts**(7)](/lttng-concepts/7.md)