lttng-enable-channel(1): move --output description to maintain A-Z ordering

[lttng-tools.git] / doc / man / lttng-enable-channel.1.txt

diff --git a/doc/man/lttng-enable-channel.1.txt b/doc/man/lttng-enable-channel.1.txt
index b1514ed5162c4a8b0616c7a19b56961cdbf27fb7..c4781c0f1953bfaad67382a9f948a686cd09fe9c 100644 (file)
--- a/doc/man/lttng-enable-channel.1.txt
+++ b/doc/man/lttng-enable-channel.1.txt
@@ -13,9 +13,10 @@ Create a Linux kernel channel:
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel

-      [option:--discard | option:--overwrite] [option:--output=(`mmap` | `splice`)]
+      [option:--overwrite] [option:--output=(`mmap` | `splice`)]

       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
       [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:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--session='SESSION'] 'CHANNEL'
 


@@ -23,9 +24,10 @@ Create a user space channel:
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace

-      [option:--discard | option:--overwrite] [option:--buffers-pid]
+      [option:--overwrite] [option:--buffers-pid]

       [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
       [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
       [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'
 
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--session='SESSION'] 'CHANNEL'
 


@@ -147,8 +149,8 @@ parameter is pointless: using two sub-buffers and setting their size
 according to the requirements of the context is fine.
 
 
 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.
 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.


@@ -156,11 +158,36 @@ 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.
 
 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
 
 
 Buffering scheme


@@ -201,10 +228,10 @@ in conjunction with the option:--tracefile-size option.
 For example, consider this command:
 
 [role="term"]
 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
                      --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
 
 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


@@ -228,7 +255,7 @@ option:-u, option:--userspace::
 
 Target
 ~~~~~~
 
 Target
 ~~~~~~

-option:-s, option:--session='SESSION'::
+option:-s 'SESSION', option:--session='SESSION'::

     Create or enable channel in the tracing session named 'SESSION'
     instead of the current tracing session.
 
     Create or enable channel in the tracing session named 'SESSION'
     instead of the current tracing session.
 


@@ -259,6 +286,19 @@ Default values:
 * option:--kernel option: {default_kernel_channel_subbuf_num}
 * `metadata` channel: {default_metadata_subbuf_num}
 
 * 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:--subbuf-size='SIZE'::
     Set the individual size of sub-buffers to 'SIZE' bytes.
     The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.


@@ -277,18 +317,6 @@ Default values:
 * option:--kernel option: {default_kernel_channel_subbuf_size}
 * `metadata` channel: {default_metadata_subbuf_size}
 
 * 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
 ~~~~~~~~~~~~~~~~
 
 Buffering scheme
 ~~~~~~~~~~~~~~~~


@@ -332,6 +360,18 @@ discarded events as of CTF 1.8.
 
 Timers
 ~~~~~~
 
 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:--read-timer::
     Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
     disabled read timer.


@@ -358,6 +398,25 @@ Default values:
 * option:--kernel option: {default_kernel_channel_switch_timer}
 * `metadata` channel: {default_metadata_switch_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[]
 
 
 include::common-cmd-help-options.txt[]
 


@@ -385,4 +444,5 @@ include::common-cmd-footer.txt[]
 SEE ALSO
 --------
 man:lttng-disable-channel(1),
 SEE ALSO
 --------
 man:lttng-disable-channel(1),

-man:lttng(1)
+man:lttng(1),
+man:lttng-ust(3)