lttng-load(1)

1LTTNG-LOAD(1)                    LTTng Manual                    LTTNG-LOAD(1)
2
3
4

NAME

6       lttng-load - Load LTTng recording session configurations
7

SYNOPSIS

9       lttng [GENERAL OPTIONS] load [--force] [--input-path=PATH]
10             [--override-url=URL] [--all | SESSION [--override-name=NAME]]
11

DESCRIPTION

13       The lttng load command loads the configurations of one or more
14       recording sessions from files.
15
16       See lttng-concepts(7) to learn more about recording sessions.
17
18       Use the load command in conjunction with the lttng-save(1) command to
19       save and restore the complete configurations of recording sessions. A
20       recording session configuration includes the enabled channels and
21       recording event rules, the context fields to be recorded, the recording
22       activity, and more.
23
24       Once LTTng loads one or more recording session configurations, they
25       appear exactly as they were saved from the user’s point of view.
26
27       LTTng searches the following directories, non-recursively, in this
28       order for recording session configuration files:
29
30        1. $LTTNG_HOME/.lttng/sessions ($LTTNG_HOME defaults to $HOME)
31
32        2. /usr/local/etc/lttng/sessions
33
34       Override the input path with the --input-path=PATH option. With this
35       option, LTTng does NOT search the default directories above. PATH can
36       be the path of one of:
37
38       A directory
39
40           With the SESSION argument
41               LTTng searches for the recording session configuration named
42               SESSION in all the files of the directory PATH and loads it if
43               found.
44
45           Without the SESSION argument
46               The --all option is implicit: LTTng loads all the recording
47               session configurations found in all the files in the directory
48               PATH.
49
50       A file
51
52           With the SESSION argument
53               LTTng searches for the recording session configuration named
54               SESSION in the file PATH and loads it if found.
55
56           Without the SESSION argument
57               The --all option is implicit: LTTng loads all the recording
58               session configurations found in the file PATH.
59
60       Override the output URL of the loaded recording session configurations
61       with the --override-url option.
62
63       With the SESSION argument, override the name of the loaded recording
64       session configuration with the --override-name option.
65
66       By default, the load command does NOT overwrite existing recording
67       sessions: the command fails. Allow the load command to overwrite
68       existing recording sessions with the --force option.
69
70       See the “EXAMPLES” section below for usage examples.
71

OPTIONS

73       See lttng(1) for GENERAL OPTIONS.
74
75       -a, --all
76           Load all the recording session configurations (default).
77
78       -f, --force
79           Overwrite existing recording sessions when loading.
80
81       -i PATH, --input-path=PATH
82           Load recording session configurations from PATH, either a directory
83           or a file, instead of loading them from the default search
84           directories.
85
86       --override-name=NAME
87           Override the name of the loaded recording session configuration,
88           SESSION, with NAME.
89
90       --override-url=URL
91           Override the output URL of the loaded recording session
92           configurations with URL.
93
94           This is the equivalent of the --set-url option of lttng-create(1).
95           The validity of the URL override depends on the type of recording
96           session configurations to load. This option applies to all the
97           loaded recording session configurations.
98
99   Program information
100       -h, --help
101           Show help.
102
103           This option attempts to launch /usr/bin/man to view this manual
104           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
105           environment variable.
106
107       --list-options
108           List available command options and quit.
109

EXIT STATUS

111       0
112           Success
113
114       1
115           Command error
116
117       2
118           Undefined command
119
120       3
121           Fatal error
122
123       4
124           Command warning (something went wrong during the command)
125

ENVIRONMENT

127       LTTNG_ABORT_ON_ERROR
128           Set to 1 to abort the process after the first error is encountered.
129
130       LTTNG_HOME
131           Path to the LTTng home directory.
132
133           Defaults to $HOME.
134
135           Useful when the Unix user running the commands has a non-writable
136           home directory.
137
138       LTTNG_MAN_BIN_PATH
139           Absolute path to the manual pager to use to read the LTTng
140           command-line help (with lttng-help(1) or with the --help option)
141           instead of /usr/bin/man.
142
143       LTTNG_SESSION_CONFIG_XSD_PATH
144           Path to the directory containing the session.xsd recording session
145           configuration XML schema.
146
147       LTTNG_SESSIOND_PATH
148           Absolute path to the LTTng session daemon binary (see lttng-
149           sessiond(8)) to spawn from the lttng-create(1) command.
150
151           The --sessiond-path general option overrides this environment
152           variable.
153

FILES

155       $LTTNG_HOME/.lttngrc
156           Unix user’s LTTng runtime configuration.
157
158           This is where LTTng stores the name of the Unix user’s current
159           recording session between executions of lttng(1).  lttng-create(1)
160           and lttng-set-session(1) set the current recording session.
161
162       $LTTNG_HOME/lttng-traces
163           Default output directory of LTTng traces in local and snapshot
164           modes.
165
166           Override this path with the --output option of the lttng-create(1)
167           command.
168
169       $LTTNG_HOME/.lttng
170           Unix user’s LTTng runtime and configuration directory.
171
172       $LTTNG_HOME/.lttng/sessions
173           Default directory containing the Unix user’s saved recording
174           session configurations (see lttng-save(1) and lttng-load(1)).
175
176       /usr/local/etc/lttng/sessions
177           Directory containing the system-wide saved recording session
178           configurations (see lttng-save(1) and lttng-load(1)).
179
180       Note
181           $LTTNG_HOME defaults to the value of the HOME environment variable.
182

EXAMPLES

184       Example 1. Load all the recording session configurations from the
185       default search directories.
186
187               $ lttng load
188
189       Example 2. Load all the recording session configurations from a
190       specific directory.
191
192           See the --input-path option.
193
194               $ lttng load --input-path=/path/to/sessions
195
196       Example 3. Load a specific recording session configuration from the
197       default search directories.
198
199               $ lttng load my-session
200
201       Example 4. Allow LTTng to overwrite existing recording sessions when
202       loading.
203
204           See the --force option.
205
206               $ lttng load --force
207
208       Example 5. Load a specific recording session configuration from a
209       specific file, overriding its name.
210
211           See the --input-path and --override-name options.
212
213               $ lttng load my-session --input-path=/path/to/sessions.lttng \
214                            --override-name=new-test
215

RESOURCES

217       •   LTTng project website <https://lttng.org>
218
219       •   LTTng documentation <https://lttng.org/docs>
220
221       •   LTTng bug tracker <https://bugs.lttng.org>
222
223       •   Git repositories <https://git.lttng.org>
224
225       •   GitHub organization <https://github.com/lttng>
226
227       •   Continuous integration <https://ci.lttng.org/>
228
229       •   Mailing list <https://lists.lttng.org/> for support and
230           development: lttng-dev@lists.lttng.org
231
232       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
233

COPYRIGHT

235       This program is part of the LTTng-tools project.
236
237       LTTng-tools is distributed under the GNU General Public License
238       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
239       See the LICENSE <https://github.com/lttng/lttng-
240       tools/blob/master/LICENSE> file for details.
241

THANKS

243       Special thanks to Michel Dagenais and the DORSAL laboratory
244       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
245       the LTTng journey.
246
247       Also thanks to the Ericsson teams working on tracing which helped us
248       greatly with detailed bug reports and unusual test cases.
249