Fix: ust: app stuck on recv message during UST comm timeout scenario

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

diff --git a/doc/man/lttng-snapshot.1.txt b/doc/man/lttng-snapshot.1.txt
index d60d6fcef0aaba6e24885dc546225b031fb6e5e8..1cf522f1d2029940547c3073266b18f579b967ae 100644 (file)
--- a/doc/man/lttng-snapshot.1.txt
+++ b/doc/man/lttng-snapshot.1.txt
@@ -1,150 +1,258 @@
 lttng-snapshot(1)
 =================
 lttng-snapshot(1)
 =================

-:revdate: 9 November 2018
+:revdate: 14 June 2021

 
 
 NAME
 ----
 
 
 NAME
 ----

-lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
+lttng-snapshot - Take a snapshot of an LTTng recording session

 
 
 SYNOPSIS
 --------
 
 
 SYNOPSIS
 --------

-Add a snapshot output:
+Take a recording session snapshot:

 
 [verse]
 
 [verse]

-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot add-output* [option:--max-size='SIZE']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *record* [option:--max-size='SIZE']

       [option:--name='NAME'] [option:--session='SESSION']
       [option:--name='NAME'] [option:--session='SESSION']

-      (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
+      [option:--ctrl-url='URL' option:--data-url='URL' | 'URL']

 
 

-Remove a snapshot output:
+Add a snapshot output to a recording session:

 
 [verse]
 
 [verse]

-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot del-output* [option:--session='SESSION']
-      ('ID' | 'NAME')
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *add-output* [option:--max-size='SIZE']
+      [option:--name='NAME'] [option:--session='SESSION']
+      (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')

 
 

-List current snapshot outputs:
+Show the snapshot output of a recording session:

 
 [verse]
 
 [verse]

-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot list-output* [option:--session='SESSION']
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *list-output* [option:--session='SESSION']

 
 

-Take a snapshot:
+Remove the snapshot output from a recording session:

 
 [verse]
 
 [verse]

-*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot record* [option:--max-size='SIZE']
-      [option:--name='NAME'] [option:--session='SESSION']
-      (option:--ctrl-url='URL' option:--data-url='URL' | 'URL')
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1*

 
 
 DESCRIPTION
 -----------
 
 
 DESCRIPTION
 -----------

-The `lttng snapshot` command manages the snapshot outputs and takes
-snapshots.
+The `lttng snapshot` command can take a snapshot of, add or remove a
+snapshot output, and show the snapshot output of:
+
+With the option:--session='SESSION' option::
+    The recording session named 'SESSION'.
+
+Without the option:--session option::
+    The current recording session (see man:lttng-concepts(7) to learn more
+    about the current recording session).

 
 

-A _snapshot_ is a dump of the current sub-buffers of all the channels
-of a given tracing session. When a snapshot is taken, the memory dump
-is sent to the registered snapshot outputs.
+See man:lttng-concepts(7) to learn more about recording sessions.

 
 

-The tracing session should be created in _snapshot mode_ to make sure
-that taking snapshots is allowed. This is done at tracing session
-creation time using the man:lttng-create(1) command's
-nloption:--snapshot option.
+A _snapshot_ is a dump of the current sub-buffers of all the channels of
+the selected recording session.

 
 

-Note that, when a snapshot is taken, the sub-buffers are not cleared.
-This means that different recorded snapshots may contain the same
-events.
+When LTTng takes a snapshot, it sends the sub-buffer dump of the
+selected recording session to the local file system or over the network
+to a listening relay daemon (man:lttng-relayd(8)). See the
+``<<output,Snapshot output>>'' section below to learn more.
+
+When LTTng takes a snapshot, it does :not: clear the sub-buffers of the
+selected recording session. In other words, different snapshots of the
+selected recording session can contain the same event records.
+
+You must have created the selected recording session in snapshot mode
+(see the nloption:--snapshot option of the man:lttng-create(1) command
+as well as man:lttng-concepts(7) to learn more about recording session
+modes) to use the `snapshot` command.
+
+A `snapshot-session` trigger action can also take a recording session
+snapshot (see man:lttng-add-trigger(1)).
+
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.

 
 If you want, instead, to keep all the trace data, but divide it into
 
 If you want, instead, to keep all the trace data, but divide it into

-archived chunks which are then free to process (just like snapshots),
-see the lttng-rotate(1) and lttng-enable-rotation(1) commands. Trace
-chunk archives do not overlap like snapshots can.
+archived chunks which are then, like snapshots, ready to be processed,
+see the recording session rotation feature in man:lttng-concepts(7).
+Trace chunk archives do :not: overlap like snapshots can.

 
 

+[NOTE]
+====
+Before you take a snapshot on a system with a high event throughput, the
+LTTng project recommends that you first run the man:lttng-stop(1)
+command. Otherwise, the snapshot could contain ``holes'', the result of
+the tracers overwriting unconsumed trace packets during the snapshot
+operation.

 
 

-Snapshot outputs
-~~~~~~~~~~~~~~~~
-Snapshot outputs are the destinations of snapshot files when a
-snapshot is taken using the `record` action.
+After LTTng writes the snapshot trace data, you can restart the
+recording session with the man:lttng-start(1) command.
+====

 
 

-As of this version, only one snapshot output is allowed.

 
 

-A snapshot output can be added using the `add-output` action. The
-output destination URL is set using either the 'URL' positional
-argument, or both the option:--ctrl-url and option:--data-url options.
-See man:lttng-create(1) to learn more about the URL format.
+[[output]]
+Snapshot output
+~~~~~~~~~~~~~~~
+When you take a recording session snapshot with the `record` action, LTTng
+writes the snapshot trace files to:
+
+If you specify the 'URL' non-option argument or the option:--ctrl-url and option:--data-url options::
+    The output defined by the 'URL' non-option argument or by the
+    arguments of the options.
++
+See man:lttng-create(1) for the format of 'URL'.
+
+Otherwise::
+    The snapshot output of the selected recording session.
++
+Add a snapshot output to a recording session with the `add-output`
+action. As of LTTng{nbsp}{lttng_version}, you may only add one snapshot
+output to a given recording session.
++
+When you create a snapshot mode recording session with the
+nloption:--snapshot option of the man:lttng-create(1) command, and
+without its nloption:--no-output option, the `create` command
+automatically adds a snapshot output named `snapshot-1` to the created
+recording session:
++
+--
+With its nloption:--output, nloption:--set-url, nloption:--ctrl-url, or nloption:--data-url options::
+    Equivalent to using the `add-output` action with the provided or
+    equivalent URL(s) immediately after creating the recording session.
+
+Otherwise::
+    A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
+    defaults to `$HOME`) directory, of which the name contains the
+    recording session name and the date/time.
+--
++
+Show the current snapshot output of a recording session with the
+`list-output` action.
++
+Remove the snapshot output of a recording session with the
+`del-output` action.
+
+For both the `record` and `add-output` actions:
+
+* Assign a name to a snapshot output with the option:--name='NAME'
+  option.
++
+'NAME' becomes part of the snapshot trace file names which LTTng sends
+to this output.
+
+* By default, the snapshot files can be as big as the sum of the sizes
+  of all the sub-buffers of all the channels of the selected recording
+  session.
++
+Set the maximum total size of all the snapshot trace files LTTng writes
+with the option:--max-size option.
+
+
+include::common-lttng-cmd-options-head.txt[]
+
+
+Recording target
+~~~~~~~~~~~~~~~~
+option:-s 'SESSION', option:--session='SESSION'::
+    Take a snapshot of the sub-buffers of the recording session named
+    'SESSION' instead of the current recording session.

 
 

-A name can be assigned to an output when adding it using the
-option:--name option. This name is part of the names of the
-snapshot files written to this output.

 
 

-By default, the snapshot files can be as big as the sum of the
-sizes of all the sub-buffers or all the channels of the selected
-tracing session. The maximum total size of all the snapshot files can
-be configured using the option:--max-size option.
+Output
+~~~~~~
+See the ``<<output,Snapshot output>>'' section above.

 
 

-Snapshot outputs can be listed using the `list-output` action.
+option:-C 'URL', option:--ctrl-url='URL'::
+    Set the control path URL to 'URL'.
++
+You must also use the option:--data-url option.
++
+See man:lttng-create(1) for the format of 'URL'.

 
 

-Snapshot outputs can be removed using the `del-output` action. The
-configured name can be used when removing an output, or an ID as
-listed by the `list-output` action.
+option:-D 'URL', option:--data-url='URL'::
+    Set the trace data path URL to 'URL'.
++
+You must also use the option:--ctrl-url option.
++
+See man:lttng-create(1) for the format of 'URL'.

 
 

+option:-m 'SIZE', option:--max-size='SIZE'::
+    Set the maximum total size of all the snapshot trace files LTTng
+    writes when taking a snapshot to 'SIZE' bytes.
++
+The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
+supported.

 
 

-Taking a snapshot
-~~~~~~~~~~~~~~~~~
-Taking a snapshot of the current tracing session is as easy as:
+option:-n 'NAME', option:--name='NAME'::
+    Assign the name 'NAME' to the snapshot output.

 
 

-[role="term"]
-----
-$ lttng snapshot record
-----

 
 

-This writes the snapshot files to the configured output. It is possible
-to use a custom, unregistered output at record time using the same
-options supported by the `add-output` action.
+include::common-lttng-cmd-help-options.txt[]

 
 

-NOTE: Before taking a snapshot on a system with a high event throughput,
-it is recommended to first run `lttng stop` (see
-man:lttng-stop(1)). Otherwise, the snapshot could contain "holes",
-the result of the tracers overwriting unconsumed trace packets during
-the record operation. After the snapshot is recorded, the tracers can be
-started again with `lttng start` (see man:lttng-start(1)).

 
 

+include::common-lttng-cmd-after-options.txt[]

 
 

-include::common-cmd-options-head.txt[]

 
 

+[[examples]]
+EXAMPLES
+--------
+.Take a snapshot of the current recording session, sending the trace files to its snapshot output.
+====
+[role="term"]
+----
+$ lttng snapshot record
+----
+====

 
 

-Target
-~~~~~~
-option:-s 'SESSION', option:--session='SESSION'::
-    Take a snapshot of the sub-buffers of the channels contained in
-    the tracing session named 'SESSION' instead of the current
-    tracing session.
+.Take a snapshot of a specific recording session, giving it a custom name.
+====
+See the option:--session and option:--name options.

 
 

+[role="term"]
+----
+$ lttng snapshot record --session=my-session --name=SNAP
+----
+====

 
 

-Snapshot output
-~~~~~~~~~~~~~~~
-option:-C 'URL', option:--ctrl-url='URL'::
-    Set control path URL to 'URL' (must use option:--data-url option
-    also).
+.Take a snapshot of the current recording session, sending the trace files to a custom location.
+====
+See the ``Output directory'' section of man:lttng-relayd(8) to
+understand where the relay daemon to connect to (`3.96.87.215`) writes
+the received traces.

 
 

-option:-D 'URL', option:--data-url='URL'::
-    Set data path URL to 'URL' (must use option:--ctrl-url option
-    also).
+[role="term"]
+----
+$ lttng snapshot record net://3.96.87.215
+----
+====

 
 

-option:-m 'SIZE', option:--max-size='SIZE'::
-    Limit the total size of all the snapshot files written when
-    recording a snapshot to 'SIZE' bytes. The `k` (kiB), `M` (MiB),
-    and `G` (GiB) suffixes are supported.
+.Replace the snapshot output of a specific recording session with a local file system path.
+====
+See the option:--session option.

 
 

-option:-n 'NAME', option:--name='NAME'::
-    Assign the name 'NAME' to the snapshot output.
+[role="term"]
+----
+$ lttng snapshot del-output --session=monk 1
+$ lttng snapshot add-output --session=monk \
+                 file:///path/to/snapshots
+----
+====

 
 

+.Take a snapshot of the current recording session, making sure its size is not over 4{nbsp}MiB.
+====
+See the option:--max-size option.

 
 

-include::common-cmd-help-options.txt[]
+[role="term"]
+----
+$ lttng snapshot record --max-size=4M
+----
+====

 
 
 
 

-include::common-cmd-footer.txt[]
+include::common-footer.txt[]

 
 
 SEE ALSO
 --------
 
 
 SEE ALSO
 --------

-man:lttng(1)
+man:lttng(1),
+man:lttng-create(1),
+man:lttng-concepts(7)