doc/man: update type/domain options for common event rule spec.

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

diff --git a/doc/man/lttng-load.1.txt b/doc/man/lttng-load.1.txt
index b0241b61cb6ba2df0d670c374786b0b14d6c44dc..bebe1230607d362216f2a95534e5605135dc380b 100644 (file)
--- a/doc/man/lttng-load.1.txt
+++ b/doc/man/lttng-load.1.txt
@@ -1,5 +1,6 @@
 lttng-load(1)
 =============
 lttng-load(1)
 =============

+:revdate: 17 May 2021

 
 
 NAME
 
 
 NAME


@@ -10,7 +11,8 @@ lttng-load - Load LTTng tracing session configurations
 SYNOPSIS
 --------
 [verse]
 SYNOPSIS
 --------
 [verse]

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

 
 
 DESCRIPTION
 
 
 DESCRIPTION


@@ -18,56 +20,150 @@ DESCRIPTION
 The `lttng load` command loads the configurations of one or more
 tracing sessions from files.
 
 The `lttng load` command loads the configurations of one or more
 tracing sessions from files.
 

-The `lttng load` command is used in conjunction with the
-man:lttng-save(1) command to save and restore the complete
-configurations of tracing sessions. This includes the enabled channels
-and event rules, the context added to channels, the tracing activity,
-and more.
+See man:lttng-concepts(7) to learn more about tracing sessions.

 
 

-Once one or more tracing session configurations are loaded, they appear
+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.
 
 exactly as they were saved from the user's point of view.
 

-The default input path is `$LTTNG_HOME/.lttng/sessions`
-(`$LTTNG_HOME` defaults to `$HOME`). The input path can be
-overridden with the option:--input-path option.
+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.

 
 

-If the input path is a directory, then if 'SESSION' is specified, the
-tracing session configuration named 'SESSION' is searched in all the
-files of this directory and loaded if found. If 'SESSION' is not
-specified, the option:--all option is implicit: all the tracing session
-configurations found in all the files in this directory are loaded.
+With the 'SESSION' argument, override the name of the loaded tracing
+session configuration with the option:--override-name option.

 
 

-If the input path is a file, then if 'SESSION' is specified, the tracing
-session configuration named 'SESSION' is searched in this file and
-loaded if found. If 'SESSION' is not specified, the option:--all option
-is implicit: all the tracing session configurations found in this file
-are loaded.
+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.

 
 

-By default, existing tracing sessions are not overwritten when loading;
-the command fails. The option:--force option can be used to allow this.
+See the <<examples,EXAMPLES>> section below for usage examples.

 
 
 
 

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

 
 
 option:-a, option:--all::
 
 
 option:-a, option:--all::

-    Load all tracing session configurations (default).
+    Load all the tracing session configurations (default).

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

-option:-i, option:--input-path='PATH'::
-    Set input path to 'PATH', either a directory or a file, in which
-    tracing session configurations are searched for.
+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.

 
 

-include::common-cmd-help-options.txt[]
+[role="term"]
+----
+$ lttng load my-session --input-path=/path/to/sessions.lttng \
+             --override-name=new-test
+----
+====

 
 
 
 

-include::common-cmd-footer.txt[]
+include::common-footer.txt[]

 
 
 SEE ALSO
 --------
 
 
 SEE ALSO
 --------

+man:lttng(1),

 man:lttng-save(1),
 man:lttng-save(1),

-man:lttng(1)
+man:lttng-concepts(7)