lttng-enable-channel(1)
=======================
:revdate: 15 April 2025


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


SYNOPSIS
--------
Create a Linux kernel 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 channel:

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

Enable 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 a channel named 'CHANNEL'.

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

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

The 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 channel when no channel exists for the provided tracing domain.

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

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

Disable an enabled 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 channel.

* Enable a disabled channel once its recording session has been active
  (started; see man: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
  (option:--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.
====


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


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

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

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


Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Create or enable 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
    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
    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 channel.
+
Setting option:--buffer-ownership to `user` or `process` determines
what entity gets a 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 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.


Event record loss mode
~~~~~~~~~~~~~~~~~~~~~~
option:--blocking-timeout='TIMEOUTUS'::
    Set the blocking timeout value of the 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` channel:::
    +{default_metadata_subbuf_num}+

option:--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 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` 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` channel:::
    +{default_metadata_subbuf_size}+


Trace files
~~~~~~~~~~~
option:--tracefile-count='COUNT'::
    Limit the number of trace files which LTTng writes for this 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 channel to __SIZE__{nbsp}bytes.
+
'SIZE' set to `0` means ``unlimited''.
+
Default: +{default_channel_tracefile_size}+.
+
NOTE: Data streams which LTTng writes for a channel configured with this
option may inaccurately report discarded event records as of
CTF{nbsp}1.8.


Timers
~~~~~~
option:--monitor-timer='PERIODUS'::
    Set the period of the monitor timer of the 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 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` channel:::
    +{default_metadata_read_timer}+

option:--switch-timer='PERIODUS'::
    Set the period of the switch timer of the 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` channel:::
    +{default_metadata_switch_timer}+


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


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


[[examples]]
EXAMPLES
--------
.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.

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

.Create a user space 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 channel with a per-user buffer ownership model (default) and a per-channel buffer allocation policy.
====
See the option:--buffer-allocation option.

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

.Create a Linux kernel 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 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 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)
