// SPDX-FileCopyrightText: 2015-2025 Philippe Proulx <pproulx@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

lttng-enable-channel(1)
=======================
:revdate: 20 March 2026


NAME
----
lttng-enable-channel - Create or enable LTTng event record channels


SYNOPSIS
--------
Create a Linux kernel event record channel:

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

Create a user space event record channel:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
      [option:--overwrite |
       [option:--discard] [option:--blocking-timeout='TIMEOUTUS']
       [option:--auto-reclaim-memory=(**off** | **consumed** | **older-than:**__AGEUS__)]]
      [option:--output=**mmap**] [option:--buffer-ownership=(**user** | **process**)]
      [option:--buffer-allocation=(**per-cpu** | **per-channel**)]
      [option:--buffer-preallocation=(**preallocate** | **on-demand**)]
      [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
      [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
      [option:--monitor-timer='PERIODUS'] [option:--watchdog-timer='PERIODUS']
      [option:--tracefile-size='SIZE' [option:--tracefile-count='COUNT']]
      [option:--session='SESSION'] 'CHANNEL'

Enable event record channel(s):

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
      [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...


DESCRIPTION
-----------
The `lttng enable-channel` command does one of:

* Create an event record channel named 'CHANNEL'.

* Enable one or more disabled event record channels named 'CHANNEL'
  (non-option argument, comma-separated).

See man:lttng-concepts(7) to learn more about event record channels.

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

With the option:--session='SESSION' option::
    The recording session named 'SESSION'.

Without the option:--session option::
    The current recording session (see man:lttng-concepts(7) to learn
    more about the current recording session).

NOTE: The man:lttng-enable-event(1) command can automatically create a
default event record channel when no event record channel exists for the
provided tracing domain.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.

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

Disable an enabled event record channel with the
man:lttng-disable-channel(1) command.

[IMPORTANT]
====
As of LTTng{nbsp}{lttng_version}, you may :not: perform the following
operations with the `enable-channel` command:

* Change an attribute of an existing event record channel.

* Enable a disabled event record channel once its recording session has
  been active (started; see man:lttng-start(1)) at least once.

* Create an event record channel once its recording session has been
  active at least once.

* Create a user space event record channel with a given buffer ownership
  model (option:--buffer-ownership set to `user` or `process`) and
  create a second user space event record channel with a different
  buffer ownership model in the same recording session.
====


include::common-lttng-cmd-options-head.txt[]


Tracing domain
~~~~~~~~~~~~~~
One of:

option:-k, option:--kernel::
    Create or enable event record channels in the Linux kernel domain.

option:-u, option:--userspace::
    Create or enable event record channels in the user space domain.


Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Create or enable event record channels in the recording session named 'SESSION'
    instead of the current recording session.


Buffer ownership model
~~~~~~~~~~~~~~~~~~~~~~
One of:

option:--buffers-global::
    Equivalent to option:--buffer-ownership=**system**.
+
Deprecated.

option:--buffer-ownership='MODEL'::
    Depending on 'MODEL':

`process`:::
    Allocate one set of ring buffers (one per CPU or one for the whole
    event record channel, depending on option:--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 man:lttng(1) to learn
how a user application connects to a session daemon.

Otherwise::
    Your Unix user.
--
+
Only available with the option:--userspace option.

`system`:::
    Allocate a single set of ring buffers (one per CPU) for
    the whole system.
+
Only available with the option:--kernel option.
+
As of LTTng{nbsp}{lttng_version}, 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
    event record channel, depending on option:--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 man:lttng(1) to learn
how a user application connects to a session daemon.

Otherwise::
    Your Unix user.
--
+
Only available with the option:--userspace option.
+
As of LTTng{nbsp}{lttng_version}, this is the default buffer ownership
model for the user space tracing domain, but this may change in the
future.

option:--buffers-pid::
    Equivalent to option:--buffer-ownership=**process**.
+
Deprecated.

option:--buffers-uid::
    Equivalent to option:--buffer-ownership=**user**.
+
Deprecated.


Buffer allocation policy
~~~~~~~~~~~~~~~~~~~~~~~~
option:--buffer-allocation='POLICY'::
    Depending on 'POLICY', allocate one ring buffer for:

`per-channel`:::
    The whole event record channel.
+
Setting option:--buffer-ownership to `user` or `process` determines
what entity gets an event-record-channel-wise ring buffer.
+
Only available with the option:--userspace option.

`per-cpu`:::
    Each CPU.
+
Setting option:--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 event
record channel, similar to running:
+
[role="term"]
----
$ lttng add-context --session=SESSION --channel=CHANNEL \
                    --type=cpu_id
----
+
As of LTTng{nbsp}{lttng_version}, this is the default buffer allocation
policy, but this may change in the future.


Buffer preallocation policy
~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:--buffer-preallocation='POLICY'::
    Depending on 'POLICY', allocate:
+
--
`preallocate`:::
    The full backing memory for all ring buffers when
    you create the event record channel.
+
This policy provides consistent performance but uses more memory
upfront. Use this policy to optimize instrumented application
startup time.
+
As of LTTng{nbsp}{lttng_version}, this is the default buffer
preallocation policy, but this may change in the future.

`on-demand`:::
    Backing memory for ring buffers incrementally, as
    needed during tracing.
+
This policy uses less initial memory but may introduce slight
performance overhead when allocating new memory during tracing.
--
+
Only available with the option:--userspace option.


Automatic memory reclaim
~~~~~~~~~~~~~~~~~~~~~~~~
option:--auto-reclaim-memory='STRATEGY'::
    Set the automatic memory reclaim strategy to 'STRATEGY'
    for the created event record channel.
+
'STRATEGY' is one of:
+
--
`off` (default)::
    No automatic memory reclaim.

`consumed`::
    LTTng automatically reclaims the memory of sub-buffers
    as soon as they're consumed (read).
+
This strategy is not available for event record channels of recording
sessions in snapshot mode or without an output.

**older-than:**__AGEUS__::
    LTTng automatically reclaims the memory of sub-buffers
    of which the _closing time_ exceeds __AGEUS__{nbsp}µs.
+
The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
and `h`{nbsp}(hours) suffixes are supported.
+
This is more or less equivalent to automatically running the
man:lttng-reclaim-memory(1) command. LTTng automatically evaluates
the eligibility of sub-buffers for a memory reclaim operation at
regular intervals (every half __AGEUS__{nbsp}µs, but also
at least a period defined at build time) and reclaims sub-buffers
of which the age of the _closing time_ have exceeded
__AGEUS__{nbsp}µs.
+
More specifically:

If __AGEUS__{nbsp}>{nbsp}last stream activity age:::
    Only sub-buffers of which the age, at the moment of closing them,
    is greater than{nbsp}__AGEUS__ are eligible for a memory reclaim.

If __AGEUS__{nbsp}<{nbsp}last stream activity age:::
    _All_ sub-buffers are eligible and LTTng flushes the targeted event
    record channel so that any open sub-buffer gets closed to become
    eligible.
--
+
Only available with the option:--userspace and
option:--discard options.


Event record loss mode
~~~~~~~~~~~~~~~~~~~~~~
option:--blocking-timeout='TIMEOUTUS'::
    Set the blocking timeout value of the event record channel
    to __TIMEOUTUS__{nbsp}µ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__{nbsp}µs when trying to write to a sub-buffer.
    After __N__{nbsp}µs, discard the event record.
--
+
This option is only available with both the option:--userspace and
option:--discard options.

One of:

option:--discard::
    Discard event records when there's no available sub-buffer.
+
As of LTTng{nbsp}{lttng_version}, this is the default event record loss
mode, but this may change in the future.

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


Sub-buffers
~~~~~~~~~~~
option:--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:
+
option:--userspace and option:--buffer-ownership=`user` options:::
    +{default_ust_uid_channel_subbuf_num}+
option:--userspace and option:--buffer-ownership=`process` options:::
    +{default_ust_pid_channel_subbuf_num}+
option:--kernel and option:--buffer-ownership=`system` options:::
    +{default_kernel_channel_subbuf_num}+
`metadata` event record channel:::
    +{default_metadata_subbuf_num}+

option:--output='TYPE'::
    Set the output type of the event record channel to 'TYPE'.
+
'TYPE' is one of:
+
--
`mmap`:::
    Share ring buffers between the tracer and the consumer daemon with
    the man:mmap(2) system call.

`splice`:::
    Share ring buffers between the tracer and the consumer daemon
    with the man:splice(2) system call.
+
Only available with the option:--kernel option.
--
+
Default values:
+
option:--userspace and option:--buffer-ownership=`user` options:::
    `mmap`
option:--userspace and option:--buffer-ownership=`process` options:::
    `mmap`
option:--kernel and option:--buffer-ownership=`system` options:::
    `splice`
`metadata` event record channel:::
    `mmap`

option:--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`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(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 man:getconf(1)
with the `PAGE_SIZE` variable).
+
Default values:
+
option:--userspace and option:--buffer-ownership=`user` options:::
    +{default_ust_uid_channel_subbuf_size}+
option:--userspace and option:--buffer-ownership=`process` options:::
    +{default_ust_pid_channel_subbuf_size}+
option:--kernel and option:--buffer-ownership=`system` options:::
    +{default_kernel_channel_subbuf_size}+
`metadata` event record channel:::
    +{default_metadata_subbuf_size}+


Trace files
~~~~~~~~~~~
option:--tracefile-count='COUNT'::
    Limit the number of trace files which LTTng writes for this event
    record channel to 'COUNT'.
+
'COUNT' set to `0` means ``unlimited''.
+
Default: +{default_channel_tracefile_count}+.
+
You must also use the option:--tracefile-size option with this option.

option:--tracefile-size='SIZE'::
    Set the maximum size of each trace file which LTTng writes for
    this event record channel to __SIZE__{nbsp}bytes.
+
'SIZE' set to `0` means ``unlimited''.
+
Default: +{default_channel_tracefile_size}+.
+
NOTE: Data streams which LTTng writes for an event record channel
configured with this option may inaccurately report discarded event
records as of CTF{nbsp}1.8 and CTF{nbsp}2.


Timers
~~~~~~
option:--monitor-timer='PERIODUS'::
    Set the period of the monitor timer of the event record channel to
    __PERIODUS__{nbsp}µs.
+
Set 'PERIODUS' to `0` to disable the monitor timer.
+
Default values:
+
option:--userspace and option:--buffer-ownership=`user` options:::
    +{default_ust_uid_channel_monitor_timer}+
option:--userspace and option:--buffer-ownership=`process` options:::
    +{default_ust_pid_channel_monitor_timer}+
option:--kernel and option:--buffer-ownership=`system` options:::
    +{default_kernel_channel_monitor_timer}+

option:--read-timer='PERIODUS'::
    Set the period of the read timer of the event record channel to
    __PERIODUS__{nbsp}µs.
+
Set 'PERIODUS' to `0` to disable the read timer.
+
Default values:
+
option:--userspace and option:--buffer-ownership=`user` options:::
    +{default_ust_uid_channel_read_timer}+
option:--userspace and option:--buffer-ownership=`process` options:::
    +{default_ust_pid_channel_read_timer}+
option:--kernel and option:--buffer-ownership=`system` options:::
    +{default_kernel_channel_read_timer}+
`metadata` event record channel:::
    +{default_metadata_read_timer}+

option:--switch-timer='PERIODUS'::
    Set the period of the switch timer of the event record channel to
    __PERIODUS__{nbsp}µs.
+
Set 'PERIODUS' to `0` to disable the switch timer.
+
Default values:
+
option:--userspace and option:--buffer-ownership=`user` options:::
    +{default_ust_uid_channel_switch_timer}+
option:--userspace and option:--buffer-ownership=`process` options:::
    +{default_ust_pid_channel_switch_timer}+
option:--kernel and option:--buffer-ownership=`system` options:::
    +{default_kernel_channel_switch_timer}+
`metadata` event record channel:::
    +{default_metadata_switch_timer}+

option:--watchdog-timer='PERIODUS'::
    Set the period of the watchdog timer of the event record channel to
    __PERIODUS__{nbsp}µs.
+
Set 'PERIODUS' to `0` to disable the watchdog timer.
+
You may only use this option with the
option:--userspace and option:--buffer-ownership=`user` options.
+
Default value: +{default_ust_uid_channel_watchdog_timer}+.


include::common-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.Create a Linux kernel event record channel with default attributes in the current recording session.
====
The following command line only creates a new event record channel if
`my-channel` doesn't name an existing Linux kernel event record channel
in the current recording session.

[role="term"]
----
$ lttng enable-channel --kernel my-channel
----
====

.Create a user space event record channel with a per-process buffer ownership model in a specific recording session.
====
See the option:--session and option:--buffer-ownership options.

[role="term"]
----
$ lttng enable-channel --session=my-session --userspace \
                       --buffer-ownership=process my-channel
----
====

.Create a user space event record channel with a per-user buffer ownership model (default) and a per-event-record-channel buffer allocation policy.
====
See the option:--buffer-allocation option.

[role="term"]
----
$ lttng enable-channel --userspace \
                       --buffer-allocation=per-channel my-channel
----
====

.Create a user space event record channel with an ``on-demand'' preallocation policy and an automatic memory reclaim.
====
See the option:--buffer-preallocation and
option:--auto-reclaim-memory options.

[role="term"]
----
$ lttng enable-channel --userspace my-channel \
                       --buffer-preallocation=on-demand \
                       --auto-reclaim-memory=older-than:30s
----
====

.Create a Linux kernel event record channel in the current recording session with four 32-MiB sub-buffers per ring buffer.
====
See the option:--num-subbuf and option:--subbuf-size options.

[role="term"]
----
$ lttng enable-channel --kernel my-channel \
                       --num-subbuf=4 --subbuf-size=32M
----
====

.Create a user space event record channel in the current recording session with trace file rotation.
====
See the option:--tracefile-count and option:--tracefile-size options.

[role="term"]
----
$ lttng enable-channel --userspace my-channel \
                       --tracefile-count=16 --tracefile-size=8M
----
====

.Enable two user space event record channels of a specific recording session.
====
[role="term"]
----
$ lttng enable-channel --session=my-session --userspace \
                       canal-d,rds
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-disable-channel(1),
man:lttng-list(1),
man:lttng-concepts(7)
