lttng-load(1): add usage examples

[lttng-tools.git] / doc / man / lttng-load.1.txt

lttng-load(1)
=============
:revdate: 17 May 2021


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


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


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

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

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

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

LTTng searches the following directories, non-recursively, in this order
for tracing 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 tracing 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 tracing
        session configurations found in all the files in the directory
        'PATH'.

A file::
    With the 'SESSION' argument:::
        LTTng searches for the tracing 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 tracing
        session configurations found in the file 'PATH'.

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

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

By default, the `load` command does :not: overwrite existing tracing
sessions: the command fails. Allow the `load` command to overwrite
existing tracing 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 tracing session configurations (default).

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

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

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

option:--override-url='URL'::
    Override the output URL of the loaded tracing 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 tracing session configurations to load. This option applies to
_all_ the loaded tracing session configurations.


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


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


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

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

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

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

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

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

.Load a specific tracing 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
----
====


include::common-footer.txt[]


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