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 a session daemon
59 for your Unix user if none is currently running. Override the path of
60 the session daemon binary to spawn with the general
61 genoption:--sessiond-path option. Avoid automatically spawning a session
62 daemon with the general genoption:--no-sessiond option.
64 On success, the `create` command sets the current tracing session (see
65 man:lttng-concepts(7) to learn more) to the created tracing session.
67 Show the status of the current tracing session with the
68 man:lttng-status(1) command.
70 List the tracing sessions of your Unix user, or of all users if
71 your Unix user is `root`, within the connected session daemon with the
72 man:lttng-list(1) command.
74 Start and stop a tracing session with the man:lttng-start(1) and
75 man:lttng-stop(1) commands.
77 Save and load a tracing session with the man:lttng-save(1) and
78 man:lttng-load(1) commands.
80 Allow and disallow specific processes to record events with the
81 man:lttng-track(1) and man:lttng-untrack(1) commands.
83 Archive the current trace chunk of (rotate) a tracing session with the
84 man:lttng-rotate(1) command.
86 Destroy a tracing session with the man:lttng-destroy(1) command.
92 As documented in man:lttng-concepts(7), LTTng offers four tracing
95 [[local-mode]]Local mode::
96 Write the trace data to the local file system.
98 The trace data output directory is:
100 With the option:--no-output option:::
101 None: the file system output is disabled.
103 With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
107 A subdirectory, under the `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME`
108 defaults to `$HOME`) directory, of which the name contains the
109 tracing session name and the date/time.
111 [[network-streaming-mode]]Network streaming mode::
112 Send the trace data over the network to a listening relay daemon
113 (see man:lttng-relayd(8)).
115 Set the trace output destination with the option:--set-url option, or
116 with the option:--ctrl-url and option:--data-url options (see the
117 <<url-format,URL format>> section below).
119 [[snapshot-mode]]Snapshot mode (option:--snapshot option)::
120 Only write the trace data to the local file system or send it to a
121 listening relay daemon (man:lttng-relayd(8)) when LTTng takes a
122 snapshot (see the man:lttng-snapshot(1) command).
124 With this mode, LTTng:
126 With the option:--no-output option:::
127 Does :not: add any snapshot output to the created tracing
130 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options:::
131 Adds a snapshot output named `snapshot-1` using the provided
132 path or URL(s) to the created tracing session.
135 Adds an automatic snapshot output named `snapshot-1` to the created
138 The automatic snapshot output is a subdirectory, under the
139 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
140 directory, of which the name contains the tracing session name and the
143 [[live-mode]]Live mode (option:--live option)::
144 Send the trace data over the network to a listening relay daemon
145 (see man:lttng-relayd(8)) for live reading.
147 Set the trace output destination with the option:--set-url='URL' option,
148 or with the option:--ctrl-url='URL' and option:--data-url='URL' options
149 (see the <<url-format,URL format>> section below). 'URL' may :not: start
156 The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
157 option:--data-url='URL' options is an URL.
159 There are two available 'URL' formats.
167 The `file://` protocol targets the *local file system*: you may only use
168 such an URL with the option:--set-url option when you create the tracing
169 session in local or snapshot mode (see the <<modes,Tracing session
170 modes>> section above).
173 Absolute path to the directory containing the trace data on the
179 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
182 This format is only available when you create the tracing session in
183 network streaming, snapshot (option:--snapshot), or live (option:--live)
184 mode (see the <<modes,Tracing session modes>> section above).
187 Network protocol, amongst:
193 The default values of 'CTRLPORT' and 'DATAPORT'
194 are respectively {default_network_control_port} and
195 {default_network_data_port}.
200 The default values of 'CTRLPORT' and 'DATAPORT'
201 are respectively {default_network_control_port} and
202 {default_network_data_port}.
205 Same as the `net` protocol.
207 You may only use this with the option:--ctrl-url and option:--data-url
211 Same as the `net6` protocol.
213 You can only be use this with the option:--ctrl-url and
214 option:--data-url options together.
217 ('HOST' | 'IPADDR'):::
218 Hostname or IP address.
220 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
221 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
230 Path of the directory containing the trace data on the remote file
233 This path is relative to the base output directory of the LTTng relay
234 daemon (see the nloption:--output option of man:lttng-relayd(8)).
237 include::common-cmd-options-head.txt[]
242 See the <<modes,Tracing session modes>> section above.
246 option:--live[='DELAYUS']::
247 Create the tracing session in live mode.
249 The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
250 for the data to be flushed (sent to the connected LTTng relay daemon).
251 The default value of 'DELAYUS' is {default_lttng_live_timer}.
253 Set the URL of the relay daemon to connect to with the option:--set-url
254 option, or with the option:--ctrl-url and option:--data-url options,
255 instead of using `net://127.0.0.1`.
257 The session daemon must be able to connect to a listening relay daemon
258 (see man:lttng-relayd(8)).
261 Create the tracing session in snapshot mode.
263 This is equivalent to:
268 With the option:--no-output option::
269 Not adding any snapshot output after LTTng creates the tracing
272 With the option:--output option, the option:--set-url option, or the option:--ctrl-url and option:--data-url options::
273 Adding a snapshot output named `snapshot-1` using the provided path
274 or URL(s) immediately after LTTng creates the tracing session.
277 Adding an automatic snapshot output named `snapshot-1` immediately
278 after LTTng creates the tracing session.
280 The automatic snapshot output is a subdirectory, under the
281 `$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
282 directory, of which the name contains the tracing session name and the
286 * Forcing all the channels to be created for the tracing session to be
287 configured with the nloption:--override and nloption:--output=++mmap++
288 options (see man:lttng-enable-channel(1)).
294 Depending on the tracing session mode (see the <<modes,Tracing
295 session modes>> section above):
298 Disable the file system output.
300 Snapshot mode (option:--snapshot option):::
301 Do :not: add a snapshot output after creating the tracing session.
303 option:-o 'DIR', option:--output='DIR'::
304 Equivalent to option:--set-url=++file://++__DIR__.
306 option:--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.
313 See the <<url-format,URL format>> section above to learn more about the
314 syntax of the 'URL' argument of the following options.
316 option:-C 'URL', option:--ctrl-url='URL'::
317 Set the control path URL to 'URL'.
319 You must also use the option:--data-url option.
321 Not available in local mode (see the <<modes,Tracing session modes>>
324 In snapshot mode, this is equivalent to using the nloption:--ctrl-url
325 option of the `add-output` action of the man:lttng-snapshot(1) command
326 immediately after creating the tracing session.
328 option:-D 'URL', option:--data-url='URL'::
329 Set the trace data path URL to 'URL'.
331 You must also use the option:--ctrl-url option.
333 Not available in local mode (see the <<modes,Tracing session modes>>
336 In snapshot mode, this is equivalent to using the nloption:--data-url
337 option of the `add-output` action of the man:lttng-snapshot(1) command
338 immediately after creating the tracing session.
340 option:-U 'URL', option:--set-url='URL'::
341 Set the destination URL of the control path and trace data to 'URL'.
343 This URL remains unchanged as long as the tracing session exists.
345 Depending on the tracing session mode (see the <<modes,Tracing session
346 modes>> section above):
349 'URL' must start with `file://`, followed with the destination
350 directory path on the local file system.
352 Network streaming and live modes:::
353 Equivalent to using both the option:--ctrl-url and option:--data-url
356 Snapshot mode (option:--snapshot option):::
357 Equivalent to using the 'URL' non-option argument of the
358 `add-output` action of the man:lttng-snapshot(1) command immediately
359 after creating the tracing session.
362 include::common-cmd-help-options.txt[]
365 include::common-cmd-footer.txt[]
371 man:lttng-concepts(7),
372 man:lttng-destroy(1),
373 man:lttng-enable-channel(1),
378 man:lttng-sessiond(8),
379 man:lttng-set-session(1),