Update the remaining manual pages for LTTng-tools 2.13
[lttng-tools.git] / doc / man / lttng-create.1.txt
1 lttng-create(1)
2 ===============
3 :revdate: 3 May 2021
4
5
6 NAME
7 ----
8 lttng-create - Create an LTTng tracing session
9
10
11 SYNOPSIS
12 --------
13 Create a local mode tracing session:
14
15 [verse]
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
17 [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
18
19 Create a network streaming mode tracing session:
20
21 [verse]
22 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
23 (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
24
25 Create a snapshot mode tracing session:
26
27 [verse]
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']
31
32 Create a live mode tracing session:
33
34 [verse]
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']
37
38 DESCRIPTION
39 -----------
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).
44
45 See man:lttng-concepts(7) to learn more about tracing sessions.
46
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 `/`.
51
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.
57
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.
63
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.
66
67 Show the status of the current tracing session with the
68 man:lttng-status(1) command.
69
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.
73
74 Start and stop a tracing session with the man:lttng-start(1) and
75 man:lttng-stop(1) commands.
76
77 Save and load a tracing session with the man:lttng-save(1) and
78 man:lttng-load(1) commands.
79
80 Allow and disallow specific processes to record events with the
81 man:lttng-track(1) and man:lttng-untrack(1) commands.
82
83 Archive the current trace chunk of (rotate) a tracing session with the
84 man:lttng-rotate(1) command.
85
86 Destroy a tracing session with the man:lttng-destroy(1) command.
87
88
89 [[modes]]
90 Tracing session modes
91 ~~~~~~~~~~~~~~~~~~~~~
92 As documented in man:lttng-concepts(7), LTTng offers four tracing
93 session modes:
94
95 [[local-mode]]Local mode::
96 Write the trace data to the local file system.
97 +
98 The trace data output directory is:
99 +
100 With the option:--no-output option:::
101 None: the file system output is disabled.
102
103 With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
104 The directory 'DIR'.
105
106 Otherwise:::
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.
110
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)).
114 +
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).
118
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).
123 +
124 With this mode, LTTng:
125 +
126 With the option:--no-output option:::
127 Does :not: add any snapshot output to the created tracing
128 session.
129
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.
133
134 Otherwise:::
135 Adds an automatic snapshot output named `snapshot-1` to the created
136 tracing session.
137 +
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
141 date/time.
142
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.
146 +
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
150 with `file://`.
151
152
153 [[url-format]]
154 URL format
155 ~~~~~~~~~~
156 The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
157 option:--data-url='URL' options is an URL.
158
159 There are two available 'URL' formats.
160
161 Local format::
162 +
163 [verse]
164 file://'TRACEDIR'
165 {nbsp}
166 +
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).
171 +
172 'TRACEDIR':::
173 Absolute path to the directory containing the trace data on the
174 local file system.
175
176 Network format::
177 +
178 [verse]
179 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
180 {nbsp}
181 +
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).
185 +
186 'NETPROTO':::
187 Network protocol, amongst:
188 +
189 --
190 `net`::
191 TCP over IPv4.
192 +
193 The default values of 'CTRLPORT' and 'DATAPORT'
194 are respectively {default_network_control_port} and
195 {default_network_data_port}.
196
197 `net6`::
198 TCP over IPv6.
199 +
200 The default values of 'CTRLPORT' and 'DATAPORT'
201 are respectively {default_network_control_port} and
202 {default_network_data_port}.
203
204 `tcp`::
205 Same as the `net` protocol.
206 +
207 You may only use this with the option:--ctrl-url and option:--data-url
208 options together.
209
210 `tcp6`::
211 Same as the `net6` protocol.
212 +
213 You can only be use this with the option:--ctrl-url and
214 option:--data-url options together.
215 --
216 +
217 ('HOST' | 'IPADDR'):::
218 Hostname or IP address.
219 +
220 IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
221 see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
222
223 'CTRLPORT':::
224 Control TCP port.
225
226 'DATAPORT':::
227 Data TCP port.
228
229 'TRACEDIR':::
230 Path of the directory containing the trace data on the remote file
231 system.
232 +
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)).
235
236
237 include::common-cmd-options-head.txt[]
238
239
240 Mode selection
241 ~~~~~~~~~~~~~~
242 See the <<modes,Tracing session modes>> section above.
243
244 At most one of:
245
246 option:--live[='DELAYUS']::
247 Create the tracing session in live mode.
248 +
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}.
252 +
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`.
256 +
257 The session daemon must be able to connect to a listening relay daemon
258 (see man:lttng-relayd(8)).
259
260 option:--snapshot::
261 Create the tracing session in snapshot mode.
262 +
263 This is equivalent to:
264 +
265 * One of:
266 +
267 --
268 With the option:--no-output option::
269 Not adding any snapshot output after LTTng creates the tracing
270 session.
271
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.
275
276 Otherwise::
277 Adding an automatic snapshot output named `snapshot-1` immediately
278 after LTTng creates the tracing session.
279 +
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
283 date/time.
284 --
285
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)).
289
290
291 Output
292 ~~~~~~
293 option:--no-output::
294 Depending on the tracing session mode (see the <<modes,Tracing
295 session modes>> section above):
296 +
297 Local mode:::
298 Disable the file system output.
299
300 Snapshot mode (option:--snapshot option):::
301 Do :not: add a snapshot output after creating the tracing session.
302
303 option:-o 'DIR', option:--output='DIR'::
304 Equivalent to option:--set-url=++file://++__DIR__.
305
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.
309
310
311 URL
312 ~~~
313 See the <<url-format,URL format>> section above to learn more about the
314 syntax of the 'URL' argument of the following options.
315
316 option:-C 'URL', option:--ctrl-url='URL'::
317 Set the control path URL to 'URL'.
318 +
319 You must also use the option:--data-url option.
320 +
321 Not available in local mode (see the <<modes,Tracing session modes>>
322 section above).
323 +
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.
327
328 option:-D 'URL', option:--data-url='URL'::
329 Set the trace data path URL to 'URL'.
330 +
331 You must also use the option:--ctrl-url option.
332 +
333 Not available in local mode (see the <<modes,Tracing session modes>>
334 section above).
335 +
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.
339
340 option:-U 'URL', option:--set-url='URL'::
341 Set the destination URL of the control path and trace data to 'URL'.
342 +
343 This URL remains unchanged as long as the tracing session exists.
344 +
345 Depending on the tracing session mode (see the <<modes,Tracing session
346 modes>> section above):
347 +
348 Local mode:::
349 'URL' must start with `file://`, followed with the destination
350 directory path on the local file system.
351
352 Network streaming and live modes:::
353 Equivalent to using both the option:--ctrl-url and option:--data-url
354 options.
355
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.
360
361
362 include::common-cmd-help-options.txt[]
363
364
365 include::common-cmd-footer.txt[]
366
367
368 SEE ALSO
369 --------
370 man:lttng(1),
371 man:lttng-concepts(7),
372 man:lttng-destroy(1),
373 man:lttng-enable-channel(1),
374 man:lttng-list(8),
375 man:lttng-relayd(8),
376 man:lttng-rotate(1),
377 man:lttng-save(1),
378 man:lttng-sessiond(8),
379 man:lttng-set-session(1),
380 man:lttng-start(1),
381 man:lttng-status(8),
382 man:lttng-track(1)
This page took 0.039241 seconds and 6 git commands to generate.