# lttng-enable-channel

## NAME



           lttng-enable-channel - Create or enable LTTng channels
    


## SYNOPSIS



           Create a Linux kernel channel:
    
           **lttng**[_GENERAL OPTIONS_] **enable-channel --kernel**
                 [**--overwrite**] [**--output** =(**mmap** | **splice**)]
                 [**--subbuf-size** =_SIZE_] [**--num-subbuf** =_COUNT_]
                 [**--switch-timer** =_PERIODUS_] [**--read-timer** =_PERIODUS_]
                 [**--monitor-timer** =_PERIODUS_]
                 [**--tracefile-size** =_SIZE_] [**--tracefile-count** =_COUNT_]
                 [**--session** =_SESSION_] _CHANNEL_
    
           Create a user space channel:
    
           **lttng**[_GENERAL OPTIONS_] **enable-channel --userspace**
                 [**--overwrite** | **--blocking-timeout** =_TIMEOUTUS_] [**--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 existing channel(s):
    
           **lttng**[_GENERAL OPTIONS_] **enable-channel**(**--userspace** | **--kernel**)
                 [**--session** =_SESSION_] _CHANNEL_[,_CHANNEL_]...
    


## DESCRIPTION



           The **lttng enable-channel** command can create a new channel, or
           enable one or more existing and disabled ones.
    
           A channel is the owner of sub-buffers holding recorded events.
           Event, rules, when created using lttng-enable-event(1), are always
           assigned to a channel. When creating a new channel, many
           parameters related to those sub-buffers can be fine-tuned. They
           are described in the subsections below.
    
           When _CHANNEL_ does not name an existing channel, a channel named
           _CHANNEL_ is created. Otherwise, the disabled channel named _CHANNEL_
           is enabled.
    
           Note that the lttng-enable-event(1) command can automatically
           create default channels when no channel exist.
    
           A channel is always contained in a tracing session (see
           lttng-create(1) for creating a tracing session). The session in
           which a channel is created using **lttng enable-channel** can be
           specified using the **--session** option. If the **--session** option is
           omitted, the current tracing session is targeted.
    
           Existing enabled channels can be disabled using
           lttng-disable-channel(1). Channels of a given session can be
           listed using lttng-list(1).
    
           See the _LIMITATIONS_ section below for a list of limitations of
           this command to consider.
    
       **Event loss modes**
           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).
    
       **Sub-buffers count and size**
           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
               In general, prefer bigger sub-buffers to lower the risk of
               losing events. Having bigger sub-buffers also ensures a lower
               sub-buffer switching frequency. The number of sub-buffers is
               only meaningful if the channel is enabled in overwrite mode:
               in this case, if a sub-buffer overwrite happens, the other
               sub-buffers are left unaltered.
    
           Low event throughput
               In general, prefer smaller sub-buffers since the risk of
               losing events is already low. Since events happen less
               frequently, the sub-buffer switching frequency should remain
               low and thus the tracer’s overhead should not be a problem.
    
           Low memory system
               If the target system has a low memory limit, prefer fewer
               first, then smaller sub-buffers. Even if the system is limited
               in memory, it is recommended to keep the sub-buffers as big as
               possible to avoid a high sub-buffer switching frequency.
    
           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.
    
       **Switch timer**
           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.
    
       **Read timer**
           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.
    
       **Monitor timer**
           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.
    
       **Buffering scheme**
           In the user space tracing domain, two buffering schemes are
           available when creating a channel:
    
           Per-process buffering (**--buffers-pid** option)
               Keep one ring buffer per process.
    
           Per-user buffering (**--buffers-uid** option)
               Keep one ring buffer for all the processes of a single user.
    
           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).
    
       **Trace files limit and size**
           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
           lttng-rotate(1) and lttng-enable-rotation(1).
    


## OPTIONS



           General options are described in lttng(1).
    
       **Domain**
           One of:
    
           **-k** , **--kernel**
               Enable channel in the Linux kernel domain.
    
           **-u** , **--userspace**
               Enable channel in the user space domain.
    
       **Target**
           **-s** _SESSION_ , **--session** =_SESSION_
               Create or enable channel in the tracing session named _SESSION_
               instead of the current tracing session.
    
       **Event 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:
    
               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.
    
       **Sub-buffers**
           **--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
    
       **Buffering scheme**
           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).
    
       **Trace files**
           **--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.
    
       **Timers**
           **--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
    
       **Program information**
           **-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.
    


## LIMITATIONS



           As of this version of LTTng, it is not possible to perform the
           following actions with the **lttng enable-channel** command:
    
           •   Reconfigure a channel once it is created.
    
           •   Re-enable a disabled channel once its tracing session has been
               active at least once.
    
           •   Create a channel once its tracing 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 tracing session.
    


## ENVIRONMENT VARIABLES



           **LTTNG_ABORT_ON_ERROR**
               Set to 1 to abort the process after the first error is
               encountered.
    
           **LTTNG_HOME**
               Overrides the **$HOME** environment variable. Useful when the user
               running the commands has a non-writable home directory.
    
           **LTTNG_MAN_BIN_PATH**
               Absolute path to the man pager to use for viewing help
               information about LTTng commands (using lttng-help(1) or **lttng**
               **COMMAND --help**).
    
           **LTTNG_SESSION_CONFIG_XSD_PATH**
               Path in which the **session.xsd** session configuration XML schema
               may be found.
    
           **LTTNG_SESSIOND_PATH**
               Full session daemon binary path.
    
               The **--sessiond-path** option has precedence over this
               environment variable.
    
           Note that the lttng-create(1) command can spawn an LTTng session
           daemon automatically if none is running. See lttng-sessiond(8) for
           the environment variables influencing the execution of the session
           daemon.
    


## FILES



           **$LTTNG_HOME/.lttngrc**
               User LTTng runtime configuration.
    
               This is where the per-user current tracing session is stored
               between executions of lttng(1). The current tracing session
               can be set with lttng-set-session(1). See lttng-create(1) for
               more information about tracing sessions.
    
           **$LTTNG_HOME/lttng-traces**
               Default output directory of LTTng traces. This can be
               overridden with the **--output** option of the lttng-create(1)
               command.
    
           **$LTTNG_HOME/.lttng**
               User LTTng runtime and configuration directory.
    
           **$LTTNG_HOME/.lttng/sessions**
               Default location of saved user tracing sessions (see
               lttng-save(1) and lttng-load(1)).
    
           **/usr/local/etc/lttng/sessions**
               System-wide location of saved tracing sessions (see
               lttng-save(1) and lttng-load(1)).
    
               **Note**
    
               **$LTTNG_HOME** defaults to **$HOME** when not explicitly set.
    


## EXIT STATUS



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


## BUGS



           If you encounter any issue or usability problem, please report it
           on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
           tools>.
    


## RESOURCES



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


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


* * *