[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:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
[option:--session='SESSION'] 'CHANNEL'
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
- [option:--overwrite] [option:--buffers-pid]
+ [option:--overwrite | option:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid]
[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'
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 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:
according to the requirements of the context is fine.
-Switch and read timers
-~~~~~~~~~~~~~~~~~~~~~~
+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.
-By default, a 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:--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.
Buffering scheme
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 man: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
+man:lttng-rotate(1) and man:lttng-enable-rotation(1).
+
include::common-cmd-options-head.txt[]
Event loss mode
~~~~~~~~~~~~~~~
+option:--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 option:--userspace option and
+without the option:--overwrite option.
+
One of:
option:--discard::
* option:--kernel option: {default_kernel_channel_subbuf_num}
* `metadata` channel: {default_metadata_subbuf_num}
+option:--output='TYPE'::
+ Set channel's output type to 'TYPE'.
++
+Available types: `mmap` (always available) and `splice` (only available
+with the option:--kernel option).
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options: `mmap`
+* option:--userspace and option:--buffers-pid options: `mmap`
+* option:--kernel option: `splice`
+* `metadata` channel: `mmap`
+
option:--subbuf-size='SIZE'::
Set the individual size of sub-buffers to 'SIZE' bytes.
The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
* option:--kernel option: {default_kernel_channel_subbuf_size}
* `metadata` channel: {default_metadata_subbuf_size}
-option:--output='TYPE'::
- Set channel's output type to 'TYPE'.
-+
-Available types: `mmap` (always available) and `splice` (only available
-with the option:--kernel option).
-+
-Default values:
-+
-* option:--userspace and option:--buffers-uid options: `mmap`
-* option:--userspace and option:--buffers-pid options: `mmap`
-* option:--kernel option: `splice`
-* `metadata` channel: `mmap`
Buffering scheme
~~~~~~~~~~~~~~~~
Timers
~~~~~~
+option:--monitor-timer::
+ Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
+ disabled monitor timer.
++
+Default values:
++
+* option:--userspace and option:--buffers-uid options:
+ {default_ust_uid_channel_monitor_timer}
+* option:--userspace and option:--buffers-pid options:
+ {default_ust_pid_channel_monitor_timer}
+* option:--kernel option: {default_kernel_channel_monitor_timer}
+
option:--read-timer::
Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
disabled read timer.
SEE ALSO
--------
man:lttng-disable-channel(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-ust(3)
projects / lttng-tools.git / blobdiff