-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 linklttng: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 linklttng:lttng-enable-event(1) command can automatically
-create default channels when no channel exist.
-
-A channel is always contained in a tracing session
-(see linklttng: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 option:--session option. If the option:--session
-option is omitted, the current tracing session is targeted.
-
-Existing enabled channels can be disabled using
-linklttng:lttng-disable-channel(1). Channels of a given session can be
-listed using linklttng:lttng-list(1).
-
-As of this version of LTTng, it is not possible to:
-
-* 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
- (option:--buffers-uid or option:--buffers-pid options) and create
- a second user space channel with a different buffering scheme in the
- same tracing session.
-
-
-Event loss modes
-~~~~~~~~~~~~~~~~
-LTTng tracers are non-blocking: 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.
-
-When it comes to losing events because no empty sub-buffer is available,
-the channel's event loss mode, specified by one of the option:--discard
-and option:--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 (option:--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 (option:--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 option:--num-subbuf and option:--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 (option:--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 (option:--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 and read timers
-~~~~~~~~~~~~~~~~~~~~~~
-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.