doc/man: add links between man pages about session rotation

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

lttng-snapshot(1)
=================


NAME
----
lttng-snapshot - Take LTTng snapshots and configure snapshot outputs


SYNOPSIS
--------
Add a snapshot output:

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

Remove a snapshot output:

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

List current snapshot outputs:

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

Take a 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')


DESCRIPTION
-----------
The `lttng snapshot` command manages the snapshot outputs and takes
snapshots.

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.

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.

Note that, when a snapshot is taken, the sub-buffers are not cleared.
This means that different recorded snapshots may contain the same
events.

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.


Snapshot outputs
~~~~~~~~~~~~~~~~
Snapshot outputs are the destinations of snapshot files when a
snapshot is taken using the `record` action.

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.

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.

Snapshot outputs can be listed using the `list-output` action.

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.


Taking a snapshot
~~~~~~~~~~~~~~~~~
Taking a snapshot of the current tracing session is as easy as:

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

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


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.


Snapshot output
~~~~~~~~~~~~~~~
option:-C 'URL', option:--ctrl-url='URL'::
    Set control path URL to 'URL' (must use option:--data-url option
    also).

option:-D 'URL', option:--data-url='URL'::
    Set data path URL to 'URL' (must use option:--ctrl-url option
    also).

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.

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


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


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


SEE ALSO
--------
man:lttng(1)