lttng-enable-rotation.1.txt: --timer option should be fairly precise

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

diff --git a/doc/man/lttng-enable-rotation.1.txt b/doc/man/lttng-enable-rotation.1.txt
index ad753d0c9d7c5a7ff626a747d8d4a0cd8f999489..e8970cd97b64187eac8b3ad8647bfd8d2073477c 100644 (file)
--- a/doc/man/lttng-enable-rotation.1.txt
+++ b/doc/man/lttng-enable-rotation.1.txt
@@ -4,22 +4,22 @@ lttng-enable-rotation(1)
 
 NAME
 ----
-lttng-enable-rotation - Set a tracing session's automatic rotation schedule
+lttng-enable-rotation - Set a tracing session's rotation schedule
 
 
 SYNOPSIS
 --------
 [verse]
-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* (option:--timer='PERIOD' | option:--size='SIZE')
-      [option:--session='SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION']
+      (option:--timer='PERIOD' | option:--size='SIZE' | option:--timer='PERIOD' option:--size='SIZE')
 
 
 DESCRIPTION
 -----------
-The `lttng enable-rotation` command sets an automatic rotation schedule
-for the current tracing session, or for the tracing session named
-'SESSION' if provided. See man:lttng-rotate(1) for more information
-about the concepts of a tracing session _rotation_ and a _trace chunk_.
+The `lttng enable-rotation` command sets a rotation schedule for the
+current tracing session, or for the tracing session named 'SESSION' if
+provided. See man:lttng-rotate(1) for more information about the
+concepts of a tracing session _rotation_ and a _trace chunk_.
 
 With the option:--timer option, the rotation schedule is set so that an
 automatic rotation occurs at least every 'PERIOD' (microseconds without
@@ -30,25 +30,29 @@ so that an automatic rotation occurs every time the total size of the
 flushed part of the current trace chunk is at least 'SIZE' (bytes
 without a unit suffix).
 
-With both the option:--timer and option:--size options, LTTng checks the
+For both option:--timer and option:--size options, LTTng checks the
 schedule condition periodically using the monitor timers of the tracing
-session's channels. This means that, with the option:--timer option, the
-automatic rotation can occur when the elapsed time since the last
-automatic rotation is greater than 'PERIOD', and with the option:--size
-option, the automatic rotation can occur when the size of the flushed
-part of the current trace chunk is greater than 'SIZE'. See the
-nloption:--monitor-timer option in man:lttng-enable-channel(1) for more
-information about the monitor timer.
+session's channels (see the nloption:--monitor-timer option of the
+man:lttng-enable-channel(1) command). This means that:
+
+* With the option:--timer option, the automatic rotation can occur when
+  the elapsed time since the last automatic rotation is slightly greater
+  than 'PERIOD'. The exact precision is governed by the monitor timer's
+  precision, which relies on the precision of the platform's
+  implementation of POSIX timers.
+
+* With the option:--size option, the automatic rotation can occur when
+  the size of the flushed part of the current trace chunk is greater
+  than 'SIZE'.
+
+You can combine the option:--timer and option:--size options.
 
 The naming convention of a trace chunk archive which an automatic
-rotation creates is the same as with the manual rotation command,
+rotation creates is the same as with the immediate rotation command,
 man:lttng-rotate(1).
 
-For a given tracing session, you cannot set multiple automatic rotation
-schedules with the option:--timer or the option:--size option.
-
-You can unset an automatic rotation schedule with the
-man:lttng-disable-rotation(1) command.
+You can unset a rotation schedule with the man:lttng-disable-rotation(1)
+command.
 
 See <<limitations,LIMITATIONS>> for important limitations regarding
 this command.
@@ -57,28 +61,25 @@ this command.
 include::common-cmd-options-head.txt[]
 
 
-Automatic rotation schedule condition
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-One of:
-
+Rotation schedule condition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 option:--size='SIZE'::
-    Set an automatic rotation schedule so that an automatic rotation
-    occurs every time the total size of the flushed part of the current
-    trace chunk is at least 'SIZE' bytes. The `k` (kiB), `M` (MiB), and
-    `G` (GiB) suffixes are supported.
+    Set a rotation schedule so that an automatic rotation occurs every
+    time the total size of the flushed part of the current trace chunk
+    is at least 'SIZE' bytes. The `k` (kiB), `M` (MiB), and `G` (GiB)
+    suffixes are supported.
 
 option:--timer='PERIOD'::
-    Set an automatic rotation schedule so that an automatic rotation
-    occurs at least every 'PERIOD' microseconds. The
-    `ms` (milliseconds), `s` (seconds), `m` (minutes), and `h` (hours)
-    suffixes are supported.
+    Set a rotation schedule so that an automatic rotation occurs at
+    least every 'PERIOD' microseconds. The `ms` (milliseconds), `s`
+    (seconds), `m` (minutes), and `h` (hours) suffixes are supported.
 
 
 Target
 ~~~~~~
 option:-s 'SESSION', option:--session='SESSION'::
-    Set an automatic rotation schedule for the tracing session named
-    'SESSION' instead of the current tracing session.
+    Set a rotation schedule for the tracing session named 'SESSION'
+    instead of the current tracing session.
 
 
 include::common-cmd-help-options.txt[]