[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'
[option:--overwrite] [option:--buffers-pid]
[option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
[option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
+ [option:--monitor-timer='PERIODUS'] [option:--blocking-timeout='TIMEOUTUS']
[option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
[option:--session='SESSION'] 'CHANNEL'
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
For example, consider this command:
[role="term"]
------------------------------------------------------
-lttng enable-channel --kernel --tracefile-size=4096 \
+----
+$ 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
* 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.
* option:--kernel option: {default_kernel_channel_switch_timer}
* `metadata` channel: {default_metadata_switch_timer}
+Timeouts
+~~~~~~~~
+option:--blocking-timeout='TIMEOUTUS'::
+ Set the channel's blocking timeout value to 'TIMEOUTUS' µs
+ for applications executed with a set `LTTNG_UST_ALLOW_BLOCKING`
+ environment variable:
++
+--
+0 (default)::
+ Do not block.
+
+-1::
+ 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.
+--
+
include::common-cmd-help-options.txt[]
SEE ALSO
--------
man:lttng-disable-channel(1),
-man:lttng(1)
+man:lttng(1),
+man:lttng-ust(3)
projects / lttng-tools.git / blobdiff