LTTNG-RECLAIM-MEMO(1)

📦
version 2.15.1 · 2 versions
, in ubuntu stonking

💖 NAME 💖

lttng-reclaim-memory — reclaim channel memory immediately, no cap, right now bestie ✨

(Also like… hi, this is the LTTNG-RECLAIM-MEMO(1) page from the LTTng Manual, welcome to my TED talk 🎀)

🦋 SYNOPSIS 🦋

lttng [GENERAL OPTIONS] reclaim-memory --userspace
      [--no-wait] [--older-than=AGEUS]
      [--session=SESSION] (--all | CHANNEL...)

🌸 DESCRIPTION 🌸

Okay so the lttng reclaim-memory command immediately reclaims memory for the sub-buffers of… it depends, bestie:

  • With the --all option — all the user space channels of the targeted session 💅
  • With one or more CHANNEL arguments — each named user space channel 🫶

And the targeted session is either:

  • With the --session=SESSION argument — the recording session named SESSION
  • Otherwise — the current recording session (peep lttng-concepts(7) to learn more about the current recording session 👀)

Also go read lttng-concepts(7) to learn more about channel memory reclaim, it's giving essential reading fr fr.

🧠 how the reclaim actually behaves (it depends on the loss mode, bestie)

The channel memory reclaim operation behaviour depends on the configured event record loss mode of the channel:

  • Discard mode — only reclaim sub-buffers that have been both delivered (completed and ready to be consumed) and consumed, since unconsumed data would be lost forever 😭 no takebacks.
  • Overwrite mode — reclaim any delivered sub-buffer, since old data will be overwritten anyway: no need to wait for consumption. Slay, efficient ✨

⏳ the --older-than=AGEUS age threshold

Specify a sub-buffer age threshold with the --older-than=AGEUS option: only sub-buffers of which the age of the closing time is older than AGEUS µs are eligible for a memory reclaim. Moreover:

  • If AGEUS > last stream activity age — the sub-buffers of which the age, at the moment of closing them, is greater than AGEUS µs are eligible for a memory reclaim.
  • If AGEUS < last stream activity age — all the sub-buffers are eligible. The LTTng tracers flush for the targeted channel so that any open sub-buffer gets closed to become eligible. 🧚

By default, the command waits for the memory reclaim operation to complete and displays the number of reclaimed sub-buffers. Use the --no-wait option to exit immediately without waiting for completion. Main character energy: dip out early 💅

See the “EXAMPLES” section below for usage examples, they're cute.

✨ OPTIONS ✨

See lttng(1) for GENERAL OPTIONS.

🎀 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.
  • -a, --all — reclaim memory for all the user space channels of the targeted session. Go big, periodt 👑
  • --older-than=AGEUS — only reclaim sub-buffers of which the age (µs) of the closing time is greater than AGEUS µs instead of reclaiming the memory of all eligible sub-buffers.

The ms (milliseconds), s (seconds), m (minutes), and h (hours) suffixes are supported. ⏰

  • --no-wait — do NOT wait for the memory reclaim operation to complete before exiting. Leave a text, don't wait around 💀
  • -s SESSION, --session=SESSION — reclaim memory for channels of the recording session named SESSION.
  • -u, --userspace — reclaim memory of a user space channel.

As of LTTng 2.15.1, this option is mandatory. Like, you literally cannot skip it bestie. 🔥

🌈 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. Throwback era 🎀

  • 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 at 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. Reclaim memory for all eligible sub-buffers of user space channel my-channel (current recording session).

$ lttng reclaim-memory --userspace my-channel

Example 2. Reclaim memory for sub-buffers older than 2 s of user space channels mon-canal and mein-Kanal (current recording session).

$ lttng reclaim-memory --userspace --older-than=2s \
                       mon-canal mein-Kanal

Example 3. Reclaim memory for all user space channels of the recording session named my-session without waiting for completion.

$ lttng reclaim-memory --userspace --session=my-session \
                       --no-wait --all

⭐ RESOURCES ⭐

This program is part of the LTTng-tools project.

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

🫶 THANKS 🫶

Special thanks to Michel Dagenais and the DORSAL laboratory at 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. Y'all ate 💅

🌸 SEE ALSO 🌸

lttng(1), lttng-concepts(7), lttng-enable-channel(1)

okay that's the whole page bestie, no crumbs left 💖 This lil masterpiece shipped with LTTng 2.15.1, dated 24 September 2025, and it's the LTTNG-RECLAIM-MEMO(1) page of the LTTng Manual. bye ily, go reclaim some memory 🦋✨

📦 where this page comes from