doc/man/lttng-load.1.txt

   1 lttng-load(1)
   2 =============
   3 :revdate: 14 June 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-load - Load LTTng recording session configurations
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *load* [option:--force] [option:--input-path='PATH']
  15       [option:--override-url='URL'] [option:--all | 'SESSION' [option:--override-name='NAME']]
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The `lttng load` command loads the configurations of one or more
  21 recording sessions from files.
  22
  23 See man:lttng-concepts(7) to learn more about recording sessions.
  24
  25 Use the `load` command in conjunction with the man:lttng-save(1) command
  26 to save and restore the complete configurations of recording sessions. A
  27 recording session configuration includes the enabled channels and
  28 recording event rules, the context fields to be recorded, the recording
  29 activity, and more.
  30
  31 Once LTTng loads one or more recording session configurations, they
  32 appear exactly as they were saved from the user's point of view.
  33
  34 LTTng searches the following directories, non-recursively, in this order
  35 for recording session configuration files:
  36
  37 . `$LTTNG_HOME/.lttng/sessions` (`$LTTNG_HOME` defaults to `$HOME`)
  38 . +{system_sessions_dir}+
  39
  40 Override the input path with the option:--input-path='PATH' option. With
  41 this option, LTTng does :not: search the default directories above.
  42 'PATH' can be the path of one of:
  43
  44 A directory::
  45     With the 'SESSION' argument:::
  46         LTTng searches for the recording session configuration named
  47         'SESSION' in all the files of the directory 'PATH' and loads it
  48         if found.
  49
  50     Without the 'SESSION' argument:::
  51         The option:--all option is implicit: LTTng loads all the
  52         recording session configurations found in all the files in the
  53         directory 'PATH'.
  54
  55 A file::
  56     With the 'SESSION' argument:::
  57         LTTng searches for the recording session configuration named
  58         'SESSION' in the file 'PATH' and loads it if found.
  59
  60     Without the 'SESSION' argument:::
  61         The option:--all option is implicit: LTTng loads all the
  62         recording session configurations found in the file 'PATH'.
  63
  64 Override the output URL of the loaded recording session configurations
  65 with the option:--override-url option.
  66
  67 With the 'SESSION' argument, override the name of the loaded recording
  68 session configuration with the option:--override-name option.
  69
  70 By default, the `load` command does :not: overwrite existing recording
  71 sessions: the command fails. Allow the `load` command to overwrite
  72 existing recording sessions with the option:--force option.
  73
  74 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  75
  76
  77 include::common-lttng-cmd-options-head.txt[]
  78
  79
  80 option:-a, option:--all::
  81     Load all the recording session configurations (default).
  82
  83 option:-f, option:--force::
  84     Overwrite existing recording sessions when loading.
  85
  86 option:-i 'PATH', option:--input-path='PATH'::
  87     Load recording session configurations from 'PATH', either a
  88     directory or a file, instead of loading them from the default search
  89     directories.
  90
  91 option:--override-name='NAME'::
  92     Override the name of the loaded recording session configuration,
  93     'SESSION', with 'NAME'.
  94
  95 option:--override-url='URL'::
  96     Override the output URL of the loaded recording session
  97     configurations with 'URL'.
  98 +
  99 This is the equivalent of the nloption:--set-url option of
 100 man:lttng-create(1). The validity of the URL override depends on the
 101 type of recording session configurations to load. This option applies to
 102 _all_ the loaded recording session configurations.
 103
 104
 105 include::common-lttng-cmd-help-options.txt[]
 106
 107
 108 include::common-lttng-cmd-after-options.txt[]
 109
 110
 111 [[examples]]
 112 EXAMPLES
 113 --------
 114 .Load all the recording session configurations from the default search directories.
 115 ====
 116 [role="term"]
 117 ----
 118 $ lttng load
 119 ----
 120 ====
 121
 122 .Load all the recording session configurations from a specific directory.
 123 ====
 124 See the option:--input-path option.
 125
 126 [role="term"]
 127 ----
 128 $ lttng load --input-path=/path/to/sessions
 129 ----
 130 ====
 131
 132 .Load a specific recording session configuration from the default search directories.
 133 ====
 134 [role="term"]
 135 ----
 136 $ lttng load my-session
 137 ----
 138 ====
 139
 140 .Allow LTTng to overwrite existing recording sessions when loading.
 141 ====
 142 See the option:--force option.
 143
 144 [role="term"]
 145 ----
 146 $ lttng load --force
 147 ----
 148 ====
 149
 150 .Load a specific recording session configuration from a specific file, overriding its name.
 151 ====
 152 See the option:--input-path and option:--override-name options.
 153
 154 [role="term"]
 155 ----
 156 $ lttng load my-session --input-path=/path/to/sessions.lttng \
 157              --override-name=new-test
 158 ----
 159 ====
 160
 161
 162 include::common-footer.txt[]
 163
 164
 165 SEE ALSO
 166 --------
 167 man:lttng(1),
 168 man:lttng-save(1),
 169 man:lttng-concepts(7)