doc/man: lttng(1) command pages: always include `common-footer.txt`

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

lttng-rotate(1)
===============
:revdate: 30 April 2021


NAME
----
lttng-rotate - Archive the current trace chunk of an LTTng tracing session


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *rotate* [option:--no-wait] ['SESSION']


DESCRIPTION
-----------
The `lttng rotate` command archives to the file system
the current trace chunk of:

With the 'SESSION' argument::
    The tracing session named 'SESSION'.

Without the 'SESSION' argument::
    The current tracing session (see man:lttng-concepts(7) to learn more
    about the current tracing session).

This action is called a _tracing session rotation_.

See man:lttng-concepts(7) to learn more about the tracing session
rotation and trace chunk concepts.

You can use the `rotate` command:

* Any time the tracing session is active.

* A single time once the tracing session becomes inactive.

See man:lttng-concepts(7) to learn more about the activity of a
tracing session.

By default, the `rotate` command ensures that LTTng finished performing
the tracing session rotation before it prints the path of the archived
trace chunk and exits. The printed path is absolute when the tracing
session was created in normal mode and relative to the base output
directory of the relay daemon (see the nloption:--output option of
man:lttng-relayd(8)) when it was created in network streaming mode (see
man:lttng-create(1)).

Make the command exit immediately with the option:--no-wait option. In
this case, there's no easy way to know when the current trace chunk
becomes archived, and the command does :not: print the path of the
archived trace chunk.

Because LTTng flushes the current sub-buffers of the selected tracing
session when it performs a tracing session rotation, archived trace
chunks are never redundant, that is, they do not overlap over time like
snapshots can (see man:lttng-snapshot(1)). Also, a rotation does :not:
directly cause discarded event records or packets.

A `rotate-session` trigger action can also rotate a tracing session (see
man:lttng-add-trigger(1)).

[IMPORTANT]
====
You may only use the `rotate` command when:

* The selected tracing session was created in normal mode or in network
  streaming mode (see man:lttng-create(1)).

* No channel was created with a configured trace file count or size
  limit (see the nloption:--tracefile-size and
  nloption:--tracefile-count options of the man:lttng-enable-channel(1)
  command).

* LTTng is not currently performing an immediate rotation (this
  command).
====


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


option:-n, option:--no-wait::
    Do not ensure that the tracing session rotation operation is
    completed before exiting.


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


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


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-disable-rotation(1),
man:lttng-enable-rotation(1),
man:lttng-concepts(7)