Rename "tracing session" -> "recording session"

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

lttng-snapshot(1)
=================
:revdate: 14 June 2021


NAME
----
lttng-snapshot - Take a snapshot of an LTTng recording session


SYNOPSIS
--------
Take a recording session snapshot:

[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']

Add a snapshot output to a recording session:

[verse]
*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')

Show the snapshot output of a recording session:

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

Remove the snapshot output from a recording session:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *snapshot* *del-output* [option:--session='SESSION'] *1*


DESCRIPTION
-----------
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).

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.

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
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.

After LTTng writes the snapshot trace data, you can restart the
recording session with the man:lttng-start(1) command.
====


[[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.


Output
~~~~~~
See the ``<<output,Snapshot output>>'' section above.

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'.

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.

option:-n 'NAME', option:--name='NAME'::
    Assign the name 'NAME' to the snapshot output.


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-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-create(1),
man:lttng-concepts(7)