doc/man/manpage.xsl: do not indent the title of an admonition block

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

lttng-enable-rotation(1)
========================
:revdate: 21 April 2021


NAME
----
lttng-enable-rotation - Set a tracing session rotation schedule


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-rotation* [option:--session='SESSION']
      (option:--timer='PERIODUS' | option:--size='SIZE' | option:--timer='PERIODUS' option:--size='SIZE')


DESCRIPTION
-----------
The `lttng enable-rotation` command sets a tracing session rotation
schedule for:

With the option:--session='SESSION' option::
    The tracing session named 'SESSION'.

Without the option:--session option::
    The current tracing session (see man:lttng-create(1) and
    man:lttng-set-session(1) to learn more about the current tracing
    session).

See man:lttng-rotate(1) for more information about the concepts of a
tracing session _rotation_ and a _trace chunk_.

With the option:--timer='PERIODUS' option, the `enable-rotation` command
sets a rotation schedule so that LTTng performs an automatic rotation at
least every 'PERIODUS'.

With the option:--size='SIZE' option, the `enable-rotation` command sets
a rotation schedule so that LTTng performs an automatic rotation every
time the total size of the flushed part of the current trace chunk is at
least 'SIZE'.

For both the option:--timer and option:--size options, LTTng checks the
schedule condition periodically using the monitor timers of the channels
of the selected tracing session (see the nloption:--monitor-timer option
of man:lttng-enable-channel(1)). This means that:

* With the option:--timer='PERIODUS' option, LTTng can perform an
  automatic rotation when the elapsed time since the last automatic
  rotation is slightly greater than 'PERIODUS'.
+
The exact precision depends on the precision of the monitor timer, which
relies on the precision of the platform implementation of POSIX timers.

* With the option:--size='SIZE' option, LTTng can perform an automatic
  rotation when the size of the flushed part of the current trace chunk
  is greater than 'SIZE'.

You may combine the option:--timer and option:--size options.

The naming convention of a trace chunk archive which an automatic
rotation operation creates is the same as with the immediate rotation
command, man:lttng-rotate(1).

Unset a tracing session rotation schedule with the
man:lttng-disable-rotation(1) command.

[IMPORTANT]
====
The `enable-rotation` command only works 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 man:lttng-enable-channel(1)).

For a given tracing session, LTTng only performs an automatic rotation
when no other rotation is currently happening.
====


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


Rotation schedule condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~
option:--size='SIZE'::
    Set a rotation schedule so that LTTng performs an automatic rotation
    every time the total size of the flushed part of the current trace
    chunk is at least 'SIZE' bytes.
+
The `k`{nbsp}(KiB), `M`{nbsp}(MiB), and `G`{nbsp}(GiB) suffixes are
supported.

option:--timer='PERIODUS'::
    Set a rotation schedule so that LTTng performs an automatic rotation at
    least every 'PERIODUS' microseconds.
+
The `ms`{nbsp}(milliseconds), `s`{nbsp}(seconds), `m`{nbsp}(minutes),
and `h`{nbsp}(hours) suffixes are supported.


Recording target
~~~~~~~~~~~~~~~~
option:-s 'SESSION', option:--session='SESSION'::
    Set a rotation schedule for the tracing session named 'SESSION'
    instead of the current tracing session.


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


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


SEE ALSO
--------
man:lttng(1),
man:lttng-create(1),
man:lttng-disable-rotation(1),
man:lttng-rotate(1)