Document tracing session rotation features

[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 cad26a8643edf052a67bd0aa0738cfe834c14ba5..95e62e6f1ec069f0438033725433502ad173d2d9 100644 (file)
--- a/doc/man/lttng-enable-channel.1.txt
+++ b/doc/man/lttng-enable-channel.1.txt
@@ -24,10 +24,10 @@ Create a user space 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:--blocking-timeout='TIMEOUTUS']
+      [option:--monitor-timer='PERIODUS']
       [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
       [option:--session='SESSION'] 'CHANNEL'
 
@@ -72,14 +72,20 @@ limitations of this command to consider.
 
 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:
@@ -238,6 +244,14 @@ Here, for each stream, the maximum size of each trace file is
 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[]
 
@@ -262,6 +276,27 @@ option:-s 'SESSION', option:--session='SESSION'::
 
 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::
@@ -286,6 +321,19 @@ Default values:
 * 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.
@@ -304,18 +352,6 @@ Default values:
 * 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
 ~~~~~~~~~~~~~~~~
@@ -397,25 +433,6 @@ Default values:
 * 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[]