// SPDX-FileCopyrightText: 2015-2026 Philippe Proulx <pproulx@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

lttng-load(1)
=============
:revdate: 27 April 2026


NAME
----
lttng-load - Load LTTng recording session configurations


SYNOPSIS
--------
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *load* [option:--force] [option:--input-path='PATH']
      [option:--override-url='URL'] [option:--no-triggers]
      [option:--all | 'SESSION' [option:--override-name='NAME']]


DESCRIPTION
-----------
The `lttng load` command loads the configurations of one or more
recording sessions from files.

See man:lttng-concepts(7) to learn more about recording sessions.

Use the `load` command in conjunction with the man:lttng-save(1) command
to save and restore the complete configurations of recording sessions. A
recording session configuration includes the enabled event record
channels and recording event rules, the context fields to be recorded,
the recording activity, and more.

Once LTTng loads one or more recording session configurations, they
appear exactly as they were saved from the user's point of view.

When the man:lttng-save(1) command writes a recording session
configuration file, it also writes *all* the triggers (see
man:lttng-add-trigger(1)) which exist at saving time, even
those triggers which aren't directly related to the saved recording
session(s). The `load` command also loads those triggers, unless you use
the option:--no-triggers option. With this option, the loaded recording
session(s) lose, amongst other things, their ``increment map value''
actions.

For each trigger which the `load` command loads, if a trigger with the
same name already exists, then the loaded trigger must have *exactly*
the same condition and action as the existing trigger. Otherwise, the
`load` command fails without loading any recording session configuration
or any trigger.

The `load` command doesn't restore the original owner of a loaded
recording session or trigger: the Unix user running the command becomes
the owner of every loaded recording session and trigger, regardless of
which user owned them when the man:lttng-save(1) command saved them.

LTTng searches the following directories, non-recursively, in this order
for recording session configuration files:

. `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`)
. +{system_sessions_dir}+

Override the input path with the option:--input-path='PATH' option. With
this option, LTTng does :not: search the default directories above.
'PATH' can be the path of one of:

A directory::
    With the 'SESSION' argument:::
        LTTng searches for the recording session configuration named
        'SESSION' in all the files of the directory 'PATH' and loads it
        if found.

    Without the 'SESSION' argument:::
        The option:--all option is implicit: LTTng loads all the
        recording session configurations found in all the files in the
        directory 'PATH'.

A file::
    With the 'SESSION' argument:::
        LTTng searches for the recording session configuration named
        'SESSION' in the file 'PATH' and loads it if found.

    Without the 'SESSION' argument:::
        The option:--all option is implicit: LTTng loads all the
        recording session configurations found in the file 'PATH'.

Override the output URL of the loaded recording session configurations
with the option:--override-url option.

With the 'SESSION' argument, override the name of the loaded recording
session configuration with the option:--override-name option.

By default, the `load` command does :not: overwrite existing recording
sessions: the command fails. Allow the `load` command to overwrite
existing recording sessions with the option:--force option.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.


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


option:-a, option:--all::
    Load all the recording session configurations (default).

option:-f, option:--force::
    Overwrite existing recording sessions when loading.

option:-i 'PATH', option:--input-path='PATH'::
    Load recording session configurations from 'PATH', either a
    directory or a file, instead of loading them from the default search
    directories.

option:--no-triggers::
    Do :not: load any trigger (see man:lttng-add-trigger(1)) from the
    recording session configuration file(s).
+
This is the behaviour of LTTng{nbsp}≤{nbsp}2.15.
+
With this option, the loaded recording session(s) lose, amongst other
things, their ``increment map value'' actions.

option:--override-name='NAME'::
    Override the name of the loaded recording session configuration,
    'SESSION', with 'NAME'.

option:--override-url='URL'::
    Override the output URL of the loaded recording session
    configurations with 'URL'.
+
This is the equivalent of the nloption:--set-url option of
man:lttng-create(1). The validity of the URL override depends on the
type of recording session configurations to load. This option applies to
_all_ the loaded recording session configurations.


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


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.Load all the recording session configurations from the default search directories.
====
[role="term"]
----
$ lttng load
----
====

.Load all the recording session configurations from a specific directory.
====
See the option:--input-path option.

[role="term"]
----
$ lttng load --input-path=/path/to/sessions
----
====

.Load a specific recording session configuration from the default search directories.
====
[role="term"]
----
$ lttng load my-session
----
====

.Allow LTTng to overwrite existing recording sessions when loading.
====
See the option:--force option.

[role="term"]
----
$ lttng load --force
----
====

.Load a specific recording session configuration from a specific file, overriding its name.
====
See the option:--input-path and option:--override-name options.

[role="term"]
----
$ lttng load my-session --input-path=/path/to/sessions.lttng \
             --override-name=new-test
----
====

.Load all the recording session configurations without loading any trigger.
====
See the option:--no-triggers option.

[role="term"]
----
$ lttng load --no-triggers
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-add-trigger(1),
man:lttng-save(1),
man:lttng-concepts(7)
