X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-load.1.txt;h=4cf5c0411a2084db4777ed57105b3c6335f82889;hb=d22ba1ec0497c9dbea3d7263d553be3547dfbe9f;hp=b0241b61cb6ba2df0d670c374786b0b14d6c44dc;hpb=7c1a4458be934fec31aa27a0eb52e4d0b8cb3803;p=lttng-tools.git diff --git a/doc/man/lttng-load.1.txt b/doc/man/lttng-load.1.txt index b0241b61c..4cf5c0411 100644 --- a/doc/man/lttng-load.1.txt +++ b/doc/man/lttng-load.1.txt @@ -1,73 +1,169 @@ lttng-load(1) ============= +:revdate: 14 June 2021 NAME ---- -lttng-load - Load LTTng tracing session configurations +lttng-load - Load LTTng recording session configurations 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 ----------- The `lttng load` command loads the configurations of one or more -tracing sessions from files. +recording 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 recording sessions. -Once one or more tracing session configurations are loaded, they appear -exactly as they were saved from the user's point of view. +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 channels and +recording event rules, the context fields to be recorded, the recording +activity, and more. -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. +Once LTTng loads one or more recording session configurations, they +appear exactly as they were saved from the user's point of view. -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. +LTTng searches the following directories, non-recursively, in this order +for recording session configuration files: -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. +. `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`) +. +{system_sessions_dir}+ -By default, existing tracing sessions are not overwritten when loading; -the command fails. The option:--force option can be used to allow this. +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. -include::common-cmd-options-head.txt[] + 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 ``<>'' section below for usage examples. + + +include::common-lttng-cmd-options-head.txt[] option:-a, option:--all:: - Load all tracing session configurations (default). + Load all the recording session configurations (default). option:-f, option:--force:: - Overwrite existing tracing sessions when loading. + 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:--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[] + -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. +[[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. -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 -------- +man:lttng(1), man:lttng-save(1), -man:lttng(1) +man:lttng-concepts(7)