lttng-reclaim-memory - Man Page

Reclaim event record channel memory immediately

Synopsis

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

Description

The lttng reclaim-memory command immediately reclaims memory for the sub-buffers of:

With the --all option

All the user space event record channels of the targeted session.

With one or more CHANNEL arguments

Each named user space event record channel.

The targeted session is either:

With the --session=SESSION argument: The recording session named SESSION.
Otherwise: The current recording session (see lttng-concepts(7) to learn more about the current recording session).

See lttng-concepts(7) to learn more about event record channel memory reclaim.

The event record channel memory reclaim operation behaviour depends on the configured event record loss mode of the event record 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.

Overwrite mode

Reclaim any delivered sub-buffer, since old data will be overwritten anyway: no need to wait for consumption.

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 event record 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.

See the “Examples” section below for usage examples.

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 event record channels of the targeted session.

--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.

-s SESSION, --session=SESSION

Reclaim memory for event record channels of the recording session named SESSION.

-u, --userspace

Reclaim memory of a user space event record channel.

As of LTTng 2.16.0, this option is mandatory.

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)).

/usr/local/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 event record 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 event record 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 event record channels of the recording session named my-session without waiting for completion.

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

Resources

LTTng project website <https://lttng.org>
LTTng documentation <https://lttng.org/docs>
LTTng bug tracker <https://bugs.lttng.org>
Git repositories <https://git.lttng.org>
GitHub organization <https://github.com/lttng>
Continuous integration <https://ci.lttng.org/>
Mailing list <https://lists.lttng.org/> for support and development: lttng-dev@lists.lttng.org
IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
Mastodon <https://mastodon.social/@lttng>