Document tracing session rotation features

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

diff --git a/doc/man/lttng-stop.1.txt b/doc/man/lttng-stop.1.txt
index 10ed6b60eac6a4e4cba0f85e16c65abf4111aa85..aafde32d88f0663e0a03fa6529523cbe4b7d87b5 100644 (file)
--- a/doc/man/lttng-stop.1.txt
+++ b/doc/man/lttng-stop.1.txt
@@ -10,7 +10,7 @@ lttng-stop - Stop LTTng tracers
 SYNOPSIS
 --------
 [verse]
-*lttng* ['GENERAL OPTIONS'] *stop* [option:--no-wait] ['SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *stop* [option:--no-wait] ['SESSION']
 
 
 DESCRIPTION
@@ -18,19 +18,19 @@ DESCRIPTION
 The `lttng stop` command stops the various LTTng tracers for a given
 active tracing session.
 
-Stoping the LTTng tracers has the effect that all enabled event rules
+Stopping the LTTng tracers has the effect that all enabled event rules
 within enabled channels cannot make event sources _emit_ trace events
 anymore.
 
 A tracing session with no running tracers is said to be _inactive_.
 Inactive tracing sessions can be set active using the
-linklttng:lttng-start(1) command.
+man:lttng-start(1) command.
 
 If 'SESSION' is omitted, the LTTng tracers are stopped for the current
-tracing session (see linklttng:lttng-create(1) for more information
+tracing session (see man:lttng-create(1) for more information
 about the current tracing session). Otherwise, they are stopped for the
 existing tracing session named 'SESSION'. `lttng list`
-outputs all the existing tracing sessions (see linklttng:lttng-list(1)).
+outputs all the existing tracing sessions (see man:lttng-list(1)).
 
 By default, the `lttng stop` command ensures that the tracing session's
 trace data is valid before returning to the prompt. With the
@@ -38,13 +38,22 @@ option:--no-wait option, the command finishes immediately, hence a local
 trace might not be valid when the command is done. In this case, there
 is no way to know when the trace becomes valid.
 
+If at least one rotation occurred during the chosen tracing session's
+lifetime (see man:lttng-rotate(1) and man:lttng-enable-rotation(1)), the
+`lttng stop` command renames the current trace chunk subdirectory and
+prints the renamed path. Although it is safe to read the content of this
+renamed subdirectory while the tracing session remains inactive (until
+the next man:lttng-start(1)), it is :not: a trace chunk archive: you
+need to destroy the tracing session with man:lttng-destroy(1) or make
+a rotation with man:lttng-rotate(1) to archive it.
+
 
 include::common-cmd-options-head.txt[]
 
 
 option:-n, option:--no-wait::
-       Do not ensure that the chosen tracing session's trace data is valid
-       before returning to the prompt.
+    Do not ensure that the chosen tracing session's trace data is valid
+    before returning to the prompt.
 
 
 include::common-cmd-help-options.txt[]
@@ -55,5 +64,5 @@ include::common-cmd-footer.txt[]
 
 SEE ALSO
 --------
-linklttng:lttng-start(1),
-linklttng:lttng(1)
+man:lttng-start(1),
+man:lttng(1)