lttng-rotate.1.txt: update voice and document the `archives` subdir.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/doc/man/lttng-rotate.1.txt b/doc/man/lttng-rotate.1.txt
index 85b95fc3af1173c4086bf47c9dadcabaa344b5b5..d197b877b9b8476af17c85140839231109a76c04 100644 (file)
--- a/doc/man/lttng-rotate.1.txt
+++ b/doc/man/lttng-rotate.1.txt
@@ -20,11 +20,11 @@ current tracing session, or of the tracing session named 'SESSION' if
 provided, to the file system. This action is called a tracing session
 _rotation_.
 
-Once a trace chunk is archived, LTTng does not manage it anymore: you
+Once LTTng archives a trace chunk, it does not manage it anymore: you
 can read it, modify it, move it, or remove it.
 
-An archived trace chunk is a collection of metadata and data stream
-files which form a self-contained trace.
+An _archived trace chunk_ is a collection of metadata and data stream
+files which form a self-contained LTTng trace.
 
 The _current trace chunk_ of a given tracing session includes:
 
@@ -39,28 +39,32 @@ The _current trace chunk_ of a given tracing session includes:
 * The content of all the non-flushed sub-buffers of the tracing
   session's channels.
 
-You can use `lttng rotate` either at any time when the tracing session
-is active (see man:lttng-start(1)), or a single time once the tracing
-session becomes inactive (see man:lttng-stop(1)).
-
-By default, the `lttng rotate` command ensures that the rotation is done
-before printing the archived trace chunk's path and returning to the
-prompt. The printed path is absolute when the tracing session was
-created in normal mode and relative to the relay daemon's output
-directory (see the nloption:--output option in man:lttng-relayd(8)) when
-it was created in network streaming mode (see man:lttng-create(1)).
-
-With the option:--no-wait option, the command finishes immediately,
-hence a rotation might not be completed when the command is done. In
-this case, there is no easy way to know when the current trace chunk is
-archived, and the command does not print the archived trace chunk's
-path.
-
-Because a rotation causes the tracing session's current sub-buffers to
-be flushed, archived trace chunks are never redundant, that is, they do
-not overlap over time like snapshots can (see man:lttng-snapshot(1)).
-Also, a rotation does not directly cause discarded event records or
-packets.
+You can use `lttng rotate`:
+
+* At any time when the tracing session is active (see
+  man:lttng-start(1)).
+* A single time once the tracing session becomes inactive
+  (see man:lttng-stop(1)).
+
+By default, the `lttng rotate` command ensures that LTTng finished
+performing the tracing session rotation before it prints the archived
+trace chunk's path and exits. The printed path is absolute when the
+tracing session was created in normal mode and relative to the relay
+daemon's output directory (see the nloption:--output option in
+man:lttng-relayd(8)) when it was created in network streaming mode (see
+man:lttng-create(1)).
+
+With the option:--no-wait option, the command finishes immediately, so
+that LTTng might not have completed the rotation when the command exits.
+In this case, there is no easy way to know when the current trace chunk
+becomes archived, and the command does not print the archived trace
+chunk's path.
+
+Because when LTTng performs a tracing session rotation, it flushes the
+tracing session's current sub-buffers, archived trace chunks are never
+redundant, that is, they do not overlap over time like snapshots can
+(see man:lttng-snapshot(1)). Also, a rotation does not directly cause
+discarded event records or packets.
 
 See <<limitations,LIMITATIONS>> for important limitations regarding
 this command.
@@ -68,9 +72,11 @@ this command.
 
 Trace chunk archive naming
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-A trace chunk archive is a subdirectory of a tracing session's output
-directory (see the nloption:--output option in man:lttng-create(1) and
-man:lttng-relayd(8)) which contains, through tracing domain and possibly
+A trace chunk archive is a subdirectory of the `archives` subdirectory
+within a tracing session's output directory (see the nloption:--output
+option in man:lttng-create(1) and man:lttng-relayd(8)).
+
+A trace chunk archive contains, through tracing domain and possibly
 UID/PID subdirectories, metadata and data stream files.
 
 A trace chunk archive is, at the same time:
@@ -83,15 +89,16 @@ In other words, an LTTng trace reader can read both the tracing
 session output directory (all the trace chunk archives), or a
 single trace chunk archive.
 
-When a tracing session rotation occurs, the created trace chunk
-archive is named:
+When LTTng performs a tracing session rotation, it names the resulting
+trace chunk archive as such, relative to the tracing session's output
+directory:
 
 [verse]
-__BEGIN__-__END__-__ID__
+archives/__BEGIN__-__END__-__ID__
 
 __BEGIN__::
     Date and time of the beginning of the trace chunk archive with
-    the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
+    the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
     `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
     time zone offset from UTC.
 +
@@ -99,17 +106,21 @@ Example: `20171119T152407-0500`
 
 __END__::
     Date and time of the end of the trace chunk archive with
-    the ISO 8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
+    the ISO{nbsp}8601-compatible `YYYYmmddTHHMMSS±HHMM` form, where
     `YYYYmmdd` is the date and `HHMMSS±HHMM` is the time with the
     time zone offset from UTC.
 +
 Example: `20180118T152407+0930`
 
 __ID__::
-    Unique numeric identifier of the trace chunk within its
-    tracing session.
+    Unique numeric identifier of the trace chunk within its tracing
+    session.
+
+Trace chunk archive name example:
 
-Trace chunk archive name example: `20171119T152407-0500-20171119T151422-0500-3`
+----
+archives/20171119T152407-0500-20171119T151422-0500-3
+----
 
 
 include::common-cmd-options-head.txt[]