8 lttng-create - Create an LTTng tracing session
13 Create a local mode tracing session:
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
17 [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
19 Create a network streaming mode tracing session:
22 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
23 (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
25 Create a snapshot mode tracing session:
28 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot [option:--shm-path='DIR']
29 [option:--no-output | option:--output='DIR' | option:--set-url='URL' |
30 option:--ctrl-url='URL' option:--data-url='URL']
32 Create a live mode tracing session:
35 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
36 [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
40 The `lttng create` command creates a new tracing session for your Unix
41 user within the connected session daemon (see the ``Session daemon
42 connection'' section of man:lttng(1) to learn how a user application
43 connects to a session daemon).
45 See man:lttng-concepts(7) to learn more about tracing sessions.
47 Without the 'SESSION' argument, LTTng automatically generates a tracing
48 session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where
49 'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may
50 :not: contain the character `/`.
52 Specify the path of the directory containing the shared memory files
53 holding the channel ring buffers with the option:--shm-path option.
54 Specifying a location on an NVRAM file system makes it possible to
55 recover the latest recorded trace data when the system reboots after a
56 crash with the man:lttng-crash(1) utility.
58 By default, the `create` command automatically spawns:
60 * A session daemon for your Unix user if none is currently running.
62 Override the path of the session daemon binary to spawn with the
63 general genoption:--sessiond-path option.
65 Avoid automatically spawning a session daemon with the general
66 genoption:--no-sessiond option.
68 * A relay daemon (see man:lttng-relayd(8)) if all the following
72 * You specify the option:--live option.
74 * You don't specify any of the option:--set-url, option:--ctrl-url, or
75 option:--data-url options.
77 * No relay daemon is currently listening for TCP connections on
78 +127.0.0.1:{default_network_viewer_port}+ (default LTTng live reader
79 connection address and port).
82 In this case, the `create` command spawns a relay daemon as such:
85 *lttng-relayd* nloption:--live-port=**tcp://localhost:{default_network_viewer_port}**
88 Override the path of the relay daemon binary to spawn with the general
89 genoption:--relayd-path option.
91 On success, the `create` command sets the current tracing session (see
92 man:lttng-concepts(7) to learn more) to the created tracing session.
94 See the <<examples,EXAMPLES>> section below for usage examples.
96 Show the status of the current tracing session with the
97 man:lttng-status(1) command.
99 List the tracing sessions of your Unix user, or of all users if
100 your Unix user is `root`, within the connected session daemon with the
101 man:lttng-list(1) command.
103 Start and stop a tracing session with the man:lttng-start(1) and
104 man:lttng-stop(1) commands.
106 Save and load a tracing session with the man:lttng-save(1) and
107 man:lttng-load(1) commands.
109 Allow and disallow specific processes to record events with the
110 man:lttng-track(1) and man:lttng-untrack(1) commands.
112 Archive the current trace chunk of (rotate) a tracing session with the
113 man:lttng-rotate(1) command.
115 Destroy a tracing session with the man:lttng-destroy(1) command.
119 Tracing session modes
120 ~~~~~~~~~~~~~~~~~~~~~
121 As documented in man:lttng-concepts(7), LTTng offers four tracing
124 [[local-mode]]Local mode::
125 Write the trace data to the local file system.
127 The trace data output directory is:
129 With the option:--no-output option:::
130 None: the file system output is disabled.
132 With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
136 A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
137 defaults to `$HOME`) directory, of which the name contains the
138 tracing session name and the date/time.
140 [[network-streaming-mode]]Network streaming mode::
141 Send the trace data over the network to a listening relay daemon
142 (see man:lttng-relayd(8)).
144 Set the trace output destination with the option:--set-url option, or
145 with the option:--ctrl-url and option:--data-url options (see the
146 <<url-format,URL format>> section below).
148 [[snapshot-mode]]Snapshot mode (option:--snapshot option)::
149 Only write the trace data to the local file system or send it to a
150 listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
151 snapshot (see the man:lttng-snapshot(1) command).
153 With this mode, LTTng:
155 With the option:--no-output option:::
156 Does :not: add any snapshot output to the created tracing
159 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
160 Adds a snapshot output named `snapshot-1` using the provided
161 path or URL(s) to the created tracing session.
164 Adds an automatic snapshot output named `snapshot-1` to the created
167 The automatic snapshot output is a subdirectory, under the
168 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
169 directory, of which the name contains the tracing session name and the
172 [[live-mode]]Live mode (option:--live option)::
173 Send the trace data over the network to a listening relay daemon
174 (see man:lttng-relayd(8)) for live reading.
176 Set the trace output destination with the option:--set-url='URL' option,
177 or with the option:--ctrl-url='URL' and option:--data-url='URL' options
178 (see the <<url-format,URL format>> section below). 'URL' may :not: start
185 The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
186 option:--data-url='URL' options is an URL.
188 There are two available 'URL' formats.
196 The `file://` protocol targets the *local file system*: you may only use
197 such an URL with the option:--set-url option when you create the tracing
198 session in local or snapshot mode (see the <<modes,Tracing session
199 modes>> section above).
202 Absolute path to the directory containing the trace data on the
208 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
211 This format is only available when you create the tracing session in
212 network streaming, snapshot (option:--snapshot), or live (option:--live)
213 mode (see the <<modes,Tracing session modes>> section above).
216 Network protocol, amongst:
222 The default values of 'CTRLPORT' and 'DATAPORT'
223 are respectively {default_network_control_port} and
224 {default_network_data_port}.
229 The default values of 'CTRLPORT' and 'DATAPORT'
230 are respectively {default_network_control_port} and
231 {default_network_data_port}.
234 Same as the `net` protocol.
236 You may only use this with the option:--ctrl-url and option:--data-url
240 Same as the `net6` protocol.
242 You can only be use this with the option:--ctrl-url and
243 option:--data-url options together.
246 ('HOST' | 'IPADDR'):::
247 Hostname or IP address.
249 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
250 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
259 Path of the directory containing the trace data on the remote file
262 This path is relative to the base output directory of the LTTng relay
263 daemon (see the nloption:--output option of man:lttng-relayd(8)).
266 include::common-lttng-cmd-options-head.txt[]
271 See the <<modes,Tracing session modes>> section above.
275 option:--live[='DELAYUS']::
276 Create the tracing session in live mode.
278 The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
279 for the data to be flushed (sent to the connected LTTng relay daemon).
280 The default value of 'DELAYUS' is {default_lttng_live_timer}.
282 Set the URL of the relay daemon to connect to with the option:--set-url
283 option, or with the option:--ctrl-url and option:--data-url options,
284 instead of using `net://127.0.0.1`.
286 The session daemon must be able to connect to a listening relay daemon
287 (see man:lttng-relayd(8)).
290 Create the tracing session in snapshot mode.
292 This is equivalent to:
297 With the option:--no-output option::
298 Not adding any snapshot output after LTTng creates the tracing
301 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
302 Adding a snapshot output named `snapshot-1` using the provided path
303 or URL(s) immediately after LTTng creates the tracing session.
306 Adding an automatic snapshot output named `snapshot-1` immediately
307 after LTTng creates the tracing session.
309 The automatic snapshot output is a subdirectory, under the
310 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
311 directory, of which the name contains the tracing session name and the
315 * Forcing all the channels to be created for the tracing session to be
316 configured with the nloption:--override and nloption:--output=++mmap++
317 options (see man:lttng-enable-channel(1)).
323 Depending on the tracing session mode (see the <<modes,Tracing
324 session modes>> section above):
327 Disable the file system output.
329 Snapshot mode (option:--snapshot option):::
330 Do :not: add a snapshot output after creating the tracing session.
332 option:-o 'DIR', option:--output='DIR'::
333 Equivalent to option:--set-url=++file://++__DIR__.
335 option:--shm-path='DIR'::
336 Set the path of the directory containing the shared memory files
337 holding the channel ring buffers to 'DIR' on the local file sytem.
342 See the <<url-format,URL format>> section above to learn more about the
343 syntax of the 'URL' argument of the following options.
345 option:-C 'URL', option:--ctrl-url='URL'::
346 Set the control path URL to 'URL'.
348 You must also use the option:--data-url option.
350 Not available in local mode (see the <<modes,Tracing session modes>>
353 In snapshot mode, this is equivalent to using the nloption:--ctrl-url
354 option of the `add-output` action of the man:lttng-snapshot(1) command
355 immediately after creating the tracing session.
357 option:-D 'URL', option:--data-url='URL'::
358 Set the trace data path URL to 'URL'.
360 You must also use the option:--ctrl-url option.
362 Not available in local mode (see the <<modes,Tracing session modes>>
365 In snapshot mode, this is equivalent to using the nloption:--data-url
366 option of the `add-output` action of the man:lttng-snapshot(1) command
367 immediately after creating the tracing session.
369 option:-U 'URL', option:--set-url='URL'::
370 Set the destination URL of the control path and trace data to 'URL'.
372 This URL remains unchanged as long as the tracing session exists.
374 Depending on the tracing session mode (see the <<modes,Tracing session
375 modes>> section above):
378 'URL' must start with `file://`, followed with the destination
379 directory path on the local file system.
381 Network streaming and live modes:::
382 Equivalent to using both the option:--ctrl-url and option:--data-url
385 Snapshot mode (option:--snapshot option):::
386 Equivalent to using the 'URL' non-option argument of the
387 `add-output` action of the man:lttng-snapshot(1) command immediately
388 after creating the tracing session.
391 include::common-lttng-cmd-help-options.txt[]
394 include::common-lttng-cmd-after-options.txt[]
400 .Create a normal mode tracing session with a generated name.
408 .Create a normal mode tracing session with a custom name.
412 $ lttng create my-session
416 .Create a normal mode tracing session with a specific output directory.
418 See the option:--output option.
422 $ lttng create --output=/path/to/traces
426 .Create a network streaming mode tracing session.
428 See the ``Output directory'' section of man:lttng-relayd(8) to
429 understand where the relay daemon to connect to (`10.0.0.242`) writes
432 See the option:--set-url option.
436 $ lttng create --set-url=net://10.0.0.242/inv4
440 .Create a snapshot mode tracing session with a default snapshot output.
442 See the option:--snapshot option.
446 $ lttng create --snapshot
450 .Create a snapshot mode tracing session with a custom snapshot output.
452 See the option:--snapshot and option:--set-url options.
456 $ lttng create --snapshot \
457 --set-url=tcp://192.168.1.102:1234:5678/my-snapshots
461 .Create a snapshot mode tracing session with no snapshot output.
463 See the option:--snapshot and option:--no-output options.
467 $ lttng create --snapshot --no-output
471 .Create an LTTng live mode tracing session with a default relay daemon URL.
473 See the option:--live option.
477 $ lttng create --live
481 .Create an LTTng live mode tracing session with a custom live timer period and relay daemon URL.
483 See the option:--live and option:--set-url options.
487 $ lttng create --live=250000 \
488 --set-url=tcp://relayd34:4885:4886
492 .Create a normal mode tracing session with a custom directory containing the ring buffer shared memory files.
494 See the option:--shm-path option.
498 $ lttng create my-session --shm-path=/mnt/nvram2/lttng
503 include::common-footer.txt[]
509 man:lttng-destroy(1),
510 man:lttng-enable-channel(1),
514 man:lttng-set-session(1),
518 man:lttng-concepts(7),
520 man:lttng-sessiond(8)