lttng-create(1)

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

NAME

6       lttng-create - Create an LTTng recording session
7

SYNOPSIS

9       Create a local mode recording session:
10
11       lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=DIR]
12             [--no-output | --output=DIR | --set-url=file://DIR]
13
14       Create a network streaming mode recording session:
15
16       lttng [GENERAL OPTIONS] create [SESSION] [--shm-path=DIR]
17             (--set-url=URL | --ctrl-url=URL --data-url=URL)
18
19       Create a snapshot mode recording session:
20
21       lttng [GENERAL OPTIONS] create [SESSION] --snapshot [--shm-path=DIR]
22             [--no-output | --output=DIR | --set-url=URL |
23              --ctrl-url=URL --data-url=URL]
24
25       Create a live mode recording session:
26
27       lttng [GENERAL OPTIONS] create [SESSION] --live[=DELAYUS]
28             [--shm-path=DIR] [--set-url=URL | --ctrl-url=URL --data-url=URL]
29

DESCRIPTION

31       The lttng create command creates a new recording session for your Unix
32       user within the connected session daemon (see the “Session daemon
33       connection” section of lttng(1) to learn how a user application
34       connects to a session daemon).
35
36       See lttng-concepts(7) to learn more about recording sessions.
37
38       Without the SESSION argument, LTTng automatically generates a recording
39       session name having the auto-YYYYmmdd-HHMMSS form, where YYYYmmdd and
40       HHMMSS are the creation date and time. SESSION may NOT contain the
41       character /.
42
43       Specify the path of the directory containing the shared memory files
44       holding the channel ring buffers with the --shm-path option. Specifying
45       a location on an NVRAM file system makes it possible to recover the
46       latest recorded trace data when the system reboots after a crash with
47       the lttng-crash(1) utility. Note that, as of LTTng 2.13.7, this feature
48       is only available for user space channels.
49
50       By default, the create command automatically spawns:
51
52       •   A session daemon for your Unix user if none is currently running.
53
54           Override the path of the session daemon binary to spawn with the
55           general --sessiond-path option.
56
57           Avoid automatically spawning a session daemon with the general
58           --no-sessiond option.
59
60       •   A relay daemon (see lttng-relayd(8)) if all the following
61           statements are true:
62
63           •   You specify the --live option.
64
65           •   You don’t specify any of the --set-url, --ctrl-url, or --data-
66               url options.
67
68           •   No relay daemon is currently listening for TCP connections on
69               127.0.0.1:5344 (default LTTng live reader connection address
70               and port).
71
72           In this case, the create command spawns a relay daemon as such:
73
74               lttng-relayd --live-port=tcp://localhost:5344
75
76           Override the path of the relay daemon binary to spawn with the
77           general --relayd-path option.
78
79       On success, the create command sets the current recording session (see
80       lttng-concepts(7) to learn more) to the created recording session.
81
82       See the “EXAMPLES” section below for usage examples.
83
84       Show the status of the current recording session with the lttng-
85       status(1) command.
86
87       List the recording sessions of your Unix user, or of all users if your
88       Unix user is root, within the connected session daemon with the lttng-
89       list(1) command.
90
91       Start and stop a recording session with the lttng-start(1) and lttng-
92       stop(1) commands.
93
94       Save and load a recording session with the lttng-save(1) and lttng-
95       load(1) commands.
96
97       Allow and disallow specific processes to record events with the lttng-
98       track(1) and lttng-untrack(1) commands.
99
100       Archive the current trace chunk of (rotate) a recording session with
101       the lttng-rotate(1) command.
102
103       Destroy a recording session with the lttng-destroy(1) command.
104
105   Recording session modes
106       As documented in lttng-concepts(7), LTTng offers four recording session
107       modes:
108
109       Local mode
110           Write the trace data to the local file system.
111
112           The trace data output directory is:
113
114           With the --no-output option
115               None: the file system output is disabled.
116
117           With the --output=DIR or --set-url=file://DIR option
118               The directory DIR.
119
120           Otherwise
121               A subdirectory, under the $LTTNG_HOME/lttng-traces ($LTTNG_HOME
122               defaults to $HOME) directory, of which the name contains the
123               recording session name and the date/time.
124
125       Network streaming mode
126           Send the trace data over the network to a listening relay daemon
127           (see lttng-relayd(8)).
128
129           Set the trace output destination with the --set-url option, or with
130           the --ctrl-url and --data-url options (see the “URL format” section
131           below).
132
133       Snapshot mode (--snapshot option)
134           Only write the trace data to the local file system or send it to a
135           listening relay daemon (lttng-relayd(8)) when LTTng takes a
136           snapshot (see the lttng-snapshot(1) command).
137
138           With this mode, LTTng:
139
140           With the --no-output option
141               Does NOT add any snapshot output to the created recording
142               session.
143
144           With the --output option, the --set-url option, or the --ctrl-url
145           and --data-url options
146               Adds a snapshot output named snapshot-1 using the provided path
147               or URL(s) to the created recording session.
148
149           Otherwise
150               Adds an automatic snapshot output named snapshot-1 to the
151               created recording session.
152
153               The automatic snapshot output is a subdirectory, under the
154               $LTTNG_HOME/lttng-traces ($LTTNG_HOME defaults to $HOME)
155               directory, of which the name contains the recording session
156               name and the date/time.
157
158       Live mode (--live option)
159           Send the trace data over the network to a listening relay daemon
160           (see lttng-relayd(8)) for live reading.
161
162           Set the trace output destination with the --set-url=URL option, or
163           with the --ctrl-url=URL and --data-url=URL options (see the “URL
164           format” section below).  URL may NOT start with file://.
165
166   URL format
167       The argument of the --set-url=URL, --ctrl-url=URL, and --data-url=URL
168       options is an URL.
169
170       There are two available URL formats.
171
172       Local format
173
174               file://TRACEDIR
175
176           The file:// protocol targets the local file system: you may only
177           use such an URL with the --set-url option when you create the
178           recording session in local or snapshot mode (see the “Recording
179           session modes” section above).
180
181           TRACEDIR
182               Absolute path to the directory containing the trace data on the
183               local file system.
184
185       Network format
186
187               NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEDIR]
188
189           This format is only available when you create the recording session
190           in network streaming, snapshot (--snapshot), or live (--live) mode
191           (see the “Recording session modes” section above).
192
193           NETPROTO
194               Network protocol, amongst:
195
196               net
197                   TCP over IPv4.
198
199                   The default values of CTRLPORT and DATAPORT are
200                   respectively 5342 and 5343.
201
202               net6
203                   TCP over IPv6.
204
205                   The default values of CTRLPORT and DATAPORT are
206                   respectively 5342 and 5343.
207
208               tcp
209                   Same as the net protocol.
210
211                   You may only use this with the --ctrl-url and --data-url
212                   options together.
213
214               tcp6
215                   Same as the net6 protocol.
216
217                   You can only be use this with the --ctrl-url and --data-url
218                   options together.
219
220           (HOST | IPADDR)
221               Hostname or IP address.
222
223               IPv6 address must be enclosed in square brackets ([ and ]); see
224               RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>.
225
226           CTRLPORT
227               Control TCP port.
228
229           DATAPORT
230               Data TCP port.
231
232           TRACEDIR
233               Path of the directory containing the trace data on the remote
234               file system.
235
236               This path is relative to the base output directory of the LTTng
237               relay daemon (see the --output option of lttng-relayd(8)).
238

OPTIONS

240       See lttng(1) for GENERAL OPTIONS.
241
242   Mode selection
243       See the “Recording session modes” section above.
244
245       At most one of:
246
247       --live[=DELAYUS]
248           Create the recording session in live mode.
249
250           The optional DELAYUS argument is the maximum time (in µs) you can
251           wait for the data to be flushed (sent to the connected LTTng relay
252           daemon). The default value of DELAYUS is 1000000.
253
254           Set the URL of the relay daemon to connect to with the --set-url
255           option, or with the --ctrl-url and --data-url options, instead of
256           using net://127.0.0.1.
257
258           The session daemon must be able to connect to a listening relay
259           daemon (see lttng-relayd(8)).
260
261       --snapshot
262           Create the recording session in snapshot mode.
263
264           This is equivalent to:
265
266           •   One of:
267
268               With the --no-output option
269                   Not adding any snapshot output after LTTng creates the
270                   recording session.
271
272               With the --output option, the --set-url option, or the --ctrl-
273               url and --data-url options
274                   Adding a snapshot output named snapshot-1 using the
275                   provided path or URL(s) immediately after LTTng creates the
276                   recording session.
277
278               Otherwise
279                   Adding an automatic snapshot output named snapshot-1
280                   immediately after LTTng creates the recording session.
281
282                   The automatic snapshot output is a subdirectory, under the
283                   $LTTNG_HOME/lttng-traces ($LTTNG_HOME defaults to $HOME)
284                   directory, of which the name contains the recording session
285                   name and the date/time.
286
287           •   Forcing all the channels to be created for the recording
288               session to be configured with the --override and --output=mmap
289               options (see lttng-enable-channel(1)).
290
291   Output
292       --no-output
293           Depending on the recording session mode (see the “Recording session
294           modes” section above):
295
296           Local mode
297               Disable the file system output.
298
299           Snapshot mode (--snapshot option)
300               Do NOT add a snapshot output after creating the recording
301               session.
302
303       -o DIR, --output=DIR
304           Equivalent to --set-url=file://DIR.
305
306       --shm-path=DIR
307           Set the path of the directory containing the shared memory files
308           holding the channel ring buffers to DIR on the local file sytem.
309
310           Note
311               As of LTTng 2.13.7, LTTng only considers this option for user
312               space (including Java and Python) channels, but this may change
313               in the future.
314
315   URL
316       See the “URL format” section above to learn more about the syntax of
317       the URL argument of the following options.
318
319       -C URL, --ctrl-url=URL
320           Set the control path URL to URL.
321
322           You must also use the --data-url option.
323
324           Not available in local mode (see the “Recording session modes”
325           section above).
326
327           In snapshot mode, this is equivalent to using the --ctrl-url option
328           of the add-output action of the lttng-snapshot(1) command
329           immediately after creating the recording session.
330
331       -D URL, --data-url=URL
332           Set the trace data path URL to URL.
333
334           You must also use the --ctrl-url option.
335
336           Not available in local mode (see the “Recording session modes”
337           section above).
338
339           In snapshot mode, this is equivalent to using the --data-url option
340           of the add-output action of the lttng-snapshot(1) command
341           immediately after creating the recording session.
342
343       -U URL, --set-url=URL
344           Set the destination URL of the control path and trace data to URL.
345
346           This URL remains unchanged as long as the recording session exists.
347
348           Depending on the recording session mode (see the “Recording session
349           modes” section above):
350
351           Local mode
352               URL must start with file://, followed with the destination
353               directory path on the local file system.
354
355           Network streaming and live modes
356               Equivalent to using both the --ctrl-url and --data-url options.
357
358           Snapshot mode (--snapshot option)
359               Equivalent to using the URL non-option argument of the add-
360               output action of the lttng-snapshot(1) command immediately
361               after creating the recording session.
362
363   Program information
364       -h, --help
365           Show help.
366
367           This option attempts to launch /usr/bin/man to view this manual
368           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
369           environment variable.
370
371       --list-options
372           List available command options and quit.
373

EXIT STATUS

375       0
376           Success
377
378       1
379           Command error
380
381       2
382           Undefined command
383
384       3
385           Fatal error
386
387       4
388           Command warning (something went wrong during the command)
389

ENVIRONMENT

391       LTTNG_ABORT_ON_ERROR
392           Set to 1 to abort the process after the first error is encountered.
393
394       LTTNG_HOME
395           Path to the LTTng home directory.
396
397           Defaults to $HOME.
398
399           Useful when the Unix user running the commands has a non-writable
400           home directory.
401
402       LTTNG_MAN_BIN_PATH
403           Absolute path to the manual pager to use to read the LTTng
404           command-line help (with lttng-help(1) or with the --help option)
405           instead of /usr/bin/man.
406
407       LTTNG_SESSION_CONFIG_XSD_PATH
408           Path to the directory containing the session.xsd recording session
409           configuration XML schema.
410
411       LTTNG_SESSIOND_PATH
412           Absolute path to the LTTng session daemon binary (see lttng-
413           sessiond(8)) to spawn from the lttng-create(1) command.
414
415           The --sessiond-path general option overrides this environment
416           variable.
417

FILES

419       $LTTNG_HOME/.lttngrc
420           Unix user’s LTTng runtime configuration.
421
422           This is where LTTng stores the name of the Unix user’s current
423           recording session between executions of lttng(1).  lttng-create(1)
424           and lttng-set-session(1) set the current recording session.
425
426       $LTTNG_HOME/lttng-traces
427           Default output directory of LTTng traces in local and snapshot
428           modes.
429
430           Override this path with the --output option of the lttng-create(1)
431           command.
432
433       $LTTNG_HOME/.lttng
434           Unix user’s LTTng runtime and configuration directory.
435
436       $LTTNG_HOME/.lttng/sessions
437           Default directory containing the Unix user’s saved recording
438           session configurations (see lttng-save(1) and lttng-load(1)).
439
440       /usr/local/etc/lttng/sessions
441           Directory containing the system-wide saved recording session
442           configurations (see lttng-save(1) and lttng-load(1)).
443
444       Note
445           $LTTNG_HOME defaults to the value of the HOME environment variable.
446

EXAMPLES

448       Example 1. Create a normal mode recording session with a generated
449       name.
450
451               $ lttng create
452
453       Example 2. Create a normal mode recording session with a custom name.
454
455               $ lttng create my-session
456
457       Example 3. Create a normal mode recording session with a specific
458       output directory.
459
460           See the --output option.
461
462               $ lttng create --output=/path/to/traces
463
464       Example 4. Create a network streaming mode recording session.
465
466           See the “Output directory” section of lttng-relayd(8) to understand
467           where the relay daemon to connect to (10.0.0.242) writes the
468           received traces.
469
470           See the --set-url option.
471
472               $ lttng create --set-url=net://10.0.0.242/inv4
473
474       Example 5. Create a snapshot mode recording session with a default
475       snapshot output.
476
477           See the --snapshot option.
478
479               $ lttng create --snapshot
480
481       Example 6. Create a snapshot mode recording session with a custom
482       snapshot output.
483
484           See the --snapshot and --set-url options.
485
486               $ lttng create --snapshot \
487                       --set-url=tcp://192.168.1.102:1234:5678/my-snapshots
488
489       Example 7. Create a snapshot mode recording session with no snapshot
490       output.
491
492           See the --snapshot and --no-output options.
493
494               $ lttng create --snapshot --no-output
495
496       Example 8. Create an LTTng live mode recording session with a default
497       relay daemon URL.
498
499           See the --live option.
500
501               $ lttng create --live
502
503       Example 9. Create an LTTng live mode recording session with a custom
504       live timer period and relay daemon URL.
505
506           See the --live and --set-url options.
507
508               $ lttng create --live=250000 \
509                              --set-url=tcp://relayd34:4885:4886
510
511       Example 10. Create a normal mode recording session with a custom
512       directory containing the ring buffer shared memory files.
513
514           See the --shm-path option.
515
516               $ lttng create my-session --shm-path=/mnt/nvram2/lttng
517

RESOURCES

519       •   LTTng project website <https://lttng.org>
520
521       •   LTTng documentation <https://lttng.org/docs>
522
523       •   LTTng bug tracker <https://bugs.lttng.org>
524
525       •   Git repositories <https://git.lttng.org>
526
527       •   GitHub organization <https://github.com/lttng>
528
529       •   Continuous integration <https://ci.lttng.org/>
530
531       •   Mailing list <https://lists.lttng.org/> for support and
532           development: lttng-dev@lists.lttng.org
533
534       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
535

COPYRIGHT

537       This program is part of the LTTng-tools project.
538
539       LTTng-tools is distributed under the GNU General Public License
540       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
541       See the LICENSE <https://github.com/lttng/lttng-
542       tools/blob/master/LICENSE> file for details.
543

THANKS

545       Special thanks to Michel Dagenais and the DORSAL laboratory
546       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
547       the LTTng journey.
548
549       Also thanks to the Ericsson teams working on tracing which helped us
550       greatly with detailed bug reports and unusual test cases.
551