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]
 SYNOPSIS
 --------
 [verse]

-*lttng* ['GENERAL OPTIONS'] *stop* [option:--no-wait] ['SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *stop* [option:--no-wait] ['SESSION']

 
 
 DESCRIPTION
 
 
 DESCRIPTION


@@ -18,19 +18,19 @@ DESCRIPTION
 The `lttng stop` command stops the various LTTng tracers for a given
 active tracing session.
 
 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
 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
 
 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`
 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
 
 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.
 
 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::
 
 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[]
 
 
 include::common-cmd-help-options.txt[]


@@ -55,5 +64,5 @@ include::common-cmd-footer.txt[]
 
 SEE ALSO
 --------
 
 SEE ALSO
 --------

-linklttng:lttng-start(1),
-linklttng:lttng(1)
+man:lttng-start(1),
+man:lttng(1)