lttng-snapshot(1)
=================
+:revdate: 14 June 2021
NAME
----
-lttng-snapshot - Take LTTng snapshots and configure snapshot outputs
+lttng-snapshot - Take a snapshot of an LTTng recording session
SYNOPSIS
--------
-Add a snapshot output:
+Take a recording session snapshot:
[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:--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]
-*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]
-*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]
-*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
-----------
-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:
-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.
+With the option:--session='SESSION' option::
+ The recording session named 'SESSION'.
-The tracing session should be created in _snapshot mode_ to make sure
-taking snapshots is allowed. This is done at tracing session creation
-time using the man:lttng-create(1) command.
+Without the option:--session option::
+ The current recording session (see man:lttng-concepts(7) to learn more
+ about the current 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.
+See man:lttng-concepts(7) to learn more about recording sessions.
+A _snapshot_ is a dump of the current sub-buffers of all the channels of
+the selected recording session.
-Snapshot outputs
-~~~~~~~~~~~~~~~~
-Snapshot outputs are the destinations of snapshot files when a
-snapshot is taken using the `record` action.
+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.
-As of this version, only one snapshot output is allowed.
+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.
-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.
+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 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.
+A `snapshot-session` trigger action can also take a recording session
+snapshot (see man:lttng-add-trigger(1)).
-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.
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-Snapshot outputs can be listed using the `list-output` action.
+If you want, instead, to keep all the trace data, but divide it into
+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.
-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.
+[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.
+After LTTng writes the snapshot trace data, you can restart the
+recording session with the man:lttng-start(1) command.
+====
-Taking a snapshot
-~~~~~~~~~~~~~~~~~
-Taking a snapshot of the current tracing session is as easy as:
----------------------
-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.
-
-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-cmd-options-head.txt[]
+[[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.
-Target
+Output
~~~~~~
-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.
-
+See the ``<<output,Snapshot output>>'' section above.
-Snapshot output
-~~~~~~~~~~~~~~~
option:-C 'URL', option:--ctrl-url='URL'::
- Set control path URL to 'URL' (must use option:--data-url option
- also).
+ 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'.
option:-D 'URL', option:--data-url='URL'::
- Set data path URL to 'URL' (must use option:--ctrl-url option
- also).
+ 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'::
- 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.
+ 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.
option:-n 'NAME', option:--name='NAME'::
Assign the name 'NAME' to the snapshot output.
-include::common-cmd-help-options.txt[]
+include::common-lttng-cmd-help-options.txt[]
+
+
+include::common-lttng-cmd-after-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Take a snapshot of the current recording session, sending the trace files to its snapshot output.
+====
+[role="term"]
+----
+$ lttng snapshot record
+----
+====
+
+.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
+----
+====
+
+.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.
+
+[role="term"]
+----
+$ lttng snapshot record net://3.96.87.215
+----
+====
+
+.Replace the snapshot output of a specific recording session with a local file system path.
+====
+See the option:--session option.
+
+[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.
+
+[role="term"]
+----
+$ lttng snapshot record --max-size=4M
+----
+====
-include::common-cmd-footer.txt[]
+include::common-footer.txt[]
SEE ALSO
--------
-man:lttng(1)
+man:lttng(1),
+man:lttng-create(1),
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff