--- name: "lttng-enable-rotation" section: "1" platform: "linux" package: "lttng-tools" version: "2.13.15-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/lttng-enable-rotation" --- # lttng-enable-rotation(1) Set an LTTng recording session rotation schedule ## NAME lttng-enable-rotation - Set an LTTng recording session rotation schedule ## SYNOPSIS ``` lttng [GENERAL OPTIONS] enable-rotation [--session=SESSION] (--timer=PERIODUS | --size=SIZE | --timer=PERIODUS --size=SIZE) ``` ## DESCRIPTION The **lttng enable-rotation** command sets a recording session rotation schedule for: With the **--session**=*SESSION* option The recording session named *SESSION*. Without the **--session** option The current recording session (see [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn more about the current recording session). See [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn more about the recording session rotation and trace chunk concepts. With the **--timer**=*PERIODUS* option, the **enable-rotation** command sets a rotation schedule so that LTTng performs an automatic rotation at least every *PERIODUS*. With the **--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 **--timer** and **--size** options, LTTng checks the schedule condition periodically using the monitor timers of the channels of the selected recording session (see the **--monitor-timer** option of the [**lttng-enable-channel**(1)](/lttng-enable-channel/1.md) command). This means that: • With the **--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 **--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 **--timer** and **--size** options. See the [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn how LTTng names a trace chunk archive directory. See the “EXAMPLES” section below for usage examples. Unset a recording session rotation schedule with the [**lttng-disable-rotation**(1)](/lttng-disable-rotation/1.md) command. **Important**\ You may only use the **enable-rotation** command when: • The selected recording session was created in normal mode or in network streaming mode (see [**lttng-create**(1)](/lttng-create/1.md)). • No channel was created with a configured trace file count or size limit (see the **--tracefile-size** and **--tracefile-count** options of the [**lttng-enable-channel**(1)](/lttng-enable-channel/1.md) command). For a given recording session, LTTng only performs an automatic rotation when it’s not currently performing a rotation. ## OPTIONS See [**lttng**(1)](/lttng/1.md) for *GENERAL OPTIONS*. ### Rotation schedule condition - **--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** (KiB), **M** (MiB), and **G** (GiB) suffixes are supported. - **--timer**=*PERIODUS* Set a rotation schedule so that LTTng performs an automatic rotation approximately every *PERIODUS* microseconds. The **ms** (milliseconds), **s** (seconds), **m** (minutes), and **h** (hours) suffixes are supported. ### Recording target - **-s** *SESSION*, **--session**=*SESSION* Set a rotation schedule for the recording session named *SESSION* instead of the current recording session. ### Program information - **-h**, **--help** Show help. This option attempts to launch **/usr/bin/man** to view this manual page. Override the manual pager path with the **LTTNG\_MAN\_BIN\_PATH** environment variable. - **--list-options** List available command options and quit. ## EXIT STATUS **0** Success **1** Command error **2** Undefined command **3** Fatal error **4** Command warning (something went wrong during the command) ## ENVIRONMENT **LTTNG\_ABORT\_ON\_ERROR** Set to **1** to abort the process after the first error is encountered. **LTTNG\_HOME** Path to the LTTng home directory. Defaults to **$HOME**. Useful when the Unix user running the commands has a non-writable home directory. **LTTNG\_MAN\_BIN\_PATH** Absolute path to the manual pager to use to read the LTTng command-line help (with [**lttng-help**(1)](/lttng-help/1.md) or with the **--help** option) instead of **/usr/bin/man**. **LTTNG\_SESSION\_CONFIG\_XSD\_PATH** Path to the directory containing the **session.xsd** recording session configuration XML schema. **LTTNG\_SESSIOND\_PATH** Absolute path to the LTTng session daemon binary (see [**lttng-sessiond**(8)](/lttng-sessiond/8.md)) to spawn from the [**lttng-create**(1)](/lttng-create/1.md) command. The **--sessiond-path** general option overrides this environment variable. ## FILES **$LTTNG\_HOME/.lttngrc** Unix user’s LTTng runtime configuration. This is where LTTng stores the name of the Unix user’s current recording session between executions of [**lttng**(1)](/lttng/1.md). [**lttng-create**(1)](/lttng-create/1.md) and [**lttng-set-session**(1)](/lttng-set-session/1.md) set the current recording session. **$LTTNG\_HOME/lttng-traces** Default output directory of LTTng traces in local and snapshot modes. Override this path with the **--output** option of the [**lttng-create**(1)](/lttng-create/1.md) command. **$LTTNG\_HOME/.lttng** Unix user’s LTTng runtime and configuration directory. **$LTTNG\_HOME/.lttng/sessions** Default directory containing the Unix user’s saved recording session configurations (see [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)). **/etc/lttng/sessions** Directory containing the system-wide saved recording session configurations (see [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)). **Note**\ **$LTTNG\_HOME** defaults to the value of the **HOME** environment variable. ## EXAMPLES **Example 1. Set the size-based rotation schedule of the current recording session.** See the **--size** option. ``` $ lttng disable-rotation --size=256M ``` **Example 2. Set the periodic rotation schedule of a specific recording session.** See the **--timer** and **--session** options. ``` $ lttng disable-rotation --session=my-session --timer=5m ``` ## RESOURCES • LTTng project website \ • LTTng documentation \ • LTTng bug tracker \ • Git repositories \ • GitHub organization \ • Continuous integration \ • Mailing list \ for support and development: **lttng-dev@lists.lttng.org** • IRC channel \: **#lttng** on **irc.oftc.net** ## COPYRIGHT This program is part of the LTTng-tools project. LTTng-tools is distributed under the GNU General Public License version 2 \. See the **LICENSE** \ file for details. ## THANKS Special thanks to Michel Dagenais and the DORSAL laboratory \ at École Polytechnique de Montréal for the LTTng journey. Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases. ## SEE ALSO [**lttng**(1)](/lttng/1.md), [**lttng-create**(1)](/lttng-create/1.md), [**lttng-disable-rotation**(1)](/lttng-disable-rotation/1.md), [**lttng-rotate**(1)](/lttng-rotate/1.md), [**lttng-concepts**(7)](/lttng-concepts/7.md)