LTTNG-ENABLE-ROTAT(1)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

💖 lttng-enable-rotation(1) — the LTTng Manual, bestie edition 💖

okay so this is lttng-enable-rotation from the LTTng Manual, and we're gonna set up automatic rotation schedules like the absolute queens we are 👑

✨ 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 🦋

So the lttng enable-rotation command sets a recording session rotation schedule for… okay let's break it down bestie, it depends on who we're targeting:

  • With the --session=SESSION option — it's for the recording session named SESSION. Your girl, specifically.
  • Without the --session option — it's for the current recording session (peep lttng-concepts(7) if you wanna know more about what the current recording session even is).

Also go read lttng-concepts(7) to learn more about the recording session rotation and trace chunk concepts. It's giving homework but it's good homework 📚

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) command). Which means, bestie:

  • 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. it's giving "we tried our best".
  • 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. tandem slay 💫

See the lttng-concepts(7) 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) command. (breaking up is easy, apparently.)

Important 🚨 You may only use the enable-rotation command when all of the following conditions are true: - The selected recording session was created in normal mode or in network streaming mode (see lttng-create(1)). - 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) command). For a given recording session, LTTng only performs an automatic rotation when it’s not currently performing a rotation. one thing at a time, we're not multitasking here 💅

💅 OPTIONS 💅

See lttng(1) 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_LIST_LEGACY — Set to 1 to use the legacy output format (LTTng 2.14 and earlier) for the lttng-list(1) command instead of the modern output format. Note that the legacy output doesn’t show anything related to features introduced after LTTng 2.14.
  • LTTNG_MAN_BIN_PATH — Absolute path to the manual pager to use to read the LTTng command-line help (with lttng-help(1) or with the --help option) instead of /usr/bin/man.
  • LTTNG_NO_UTF_8 — Set to 1 to NOT emit multi-byte UTF-8 sequences, even if the locale claims to support it.
  • 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)) to spawn from the lttng-create(1) command. The --sessiond-path general option overrides this environment variable.
  • LTTNG_TERM_COLOR — Controls when to emit terminal SGR codes in the output. The NO_COLOR environment variable overrides this. One of:
    • auto (default) — Only emit SGR codes when the standard output is connected to a color-capable terminal.
    • always — Always emit SGR codes.
    • never — Never emit SGR codes.
  • NO_COLOR — If set and not empty, then it’s equivalent to setting LTTNG_TERM_COLOR to never. See NO_COLOR <https://no-color.org/> to learn more.

🍓 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-create(1) and lttng-set-session(1) 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) 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) and lttng-load(1)).
  • /etc/lttng/sessions — Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).
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 👑

This program is part of the LTTng-tools project.

LTTng-tools is distributed under the GNU General Public License version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

🌸 THANKS 🌸

Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> 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-create(1), lttng-disable-rotation(1), lttng-rotate(1), lttng-concepts(7)

and that's the whole page bestie, no cap 💖 this lil manual is from LTTng 2.15.1, dated 14 June 2021 — periodt ✨ go rotate something iconic 💅

📦 where this page comes from