-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
-option:--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
-man: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 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 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 option:--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 option:--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 option:--monitor-timer option to control the monitor timer's
-period of the channel to create.