Fix: build: libcommon fd-tracker dependency is not available
[lttng-tools.git] / doc / man / lttng-create.1.txt
CommitLineData
ba50d967
PP
1lttng-create(1)
2===============
ebbd679f 3:revdate: 17 May 2021
ba50d967
PP
4
5
6NAME
7----
8lttng-create - Create an LTTng tracing session
9
10
11SYNOPSIS
12--------
484b2a0c 13Create a local mode tracing session:
ba50d967
PP
14
15[verse]
484b2a0c 16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
26f0c779 17 [option:--no-output | option:--output='DIR' | option:--set-url=**file://**__DIR__]
f87c4756 18
484b2a0c 19Create a network streaming mode tracing session:
f87c4756
PP
20
21[verse]
484b2a0c 22*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR']
1f3c3a24 23 (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL')
980bb5fd 24
484b2a0c 25Create a snapshot mode tracing session:
ba50d967
PP
26
27[verse]
26f0c779
PP
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']
ba50d967 31
484b2a0c 32Create a live mode tracing session:
ba50d967
PP
33
34[verse]
1f3c3a24 35*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS']
484b2a0c 36 [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL']
ba50d967
PP
37
38DESCRIPTION
39-----------
484b2a0c 40The `lttng create` command creates a new tracing session for your Unix
26f0c779
PP
41user within the connected session daemon (see the ``Session daemon
42connection'' section of man:lttng(1) to learn how a user application
43connects to a session daemon).
484b2a0c 44
26f0c779 45See man:lttng-concepts(7) to learn more about tracing sessions.
484b2a0c
PP
46
47Without the 'SESSION' argument, LTTng automatically generates a tracing
48session 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
52Specify the path of the directory containing the shared memory files
53holding the channel ring buffers with the option:--shm-path option.
54Specifying a location on an NVRAM file system makes it possible to
55recover the latest recorded trace data when the system reboots after a
56crash with the man:lttng-crash(1) utility.
57
efacf910
PP
58By default, the `create` command automatically spawns:
59
60* A session daemon for your Unix user if none is currently running.
61+
62Override the path of the session daemon binary to spawn with the
63general genoption:--sessiond-path option.
64+
65Avoid automatically spawning a session daemon with the general
66genoption:--no-sessiond option.
67
68* A relay daemon (see man:lttng-relayd(8)) if all the following
69 statements are true:
70+
71--
72* You specify the option:--live option.
73
74* You don't specify any of the option:--set-url, option:--ctrl-url, or
75 option:--data-url options.
76
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).
80--
81+
82In this case, the `create` command spawns a relay daemon as such:
83+
84[verse]
85*lttng-relayd* nloption:--live-port=**tcp://localhost:{default_network_viewer_port}**
86{nbsp}
87+
88Override the path of the relay daemon binary to spawn with the general
89genoption:--relayd-path option.
484b2a0c 90
26f0c779
PP
91On success, the `create` command sets the current tracing session (see
92man:lttng-concepts(7) to learn more) to the created tracing session.
93
ebbd679f
PP
94See the <<examples,EXAMPLES>> section below for usage examples.
95
26f0c779
PP
96Show the status of the current tracing session with the
97man:lttng-status(1) command.
98
99List the tracing sessions of your Unix user, or of all users if
100your Unix user is `root`, within the connected session daemon with the
101man:lttng-list(1) command.
ba50d967 102
484b2a0c
PP
103Start and stop a tracing session with the man:lttng-start(1) and
104man:lttng-stop(1) commands.
ba50d967 105
484b2a0c
PP
106Save and load a tracing session with the man:lttng-save(1) and
107man:lttng-load(1) commands.
108
26f0c779
PP
109Allow and disallow specific processes to record events with the
110man:lttng-track(1) and man:lttng-untrack(1) commands.
111
112Archive the current trace chunk of (rotate) a tracing session with the
484b2a0c
PP
113man:lttng-rotate(1) command.
114
115Destroy a tracing session with the man:lttng-destroy(1) command.
116
117
484b2a0c
PP
118[[modes]]
119Tracing session modes
120~~~~~~~~~~~~~~~~~~~~~
26f0c779
PP
121As documented in man:lttng-concepts(7), LTTng offers four tracing
122session modes:
ba50d967 123
948f0a2e 124[[local-mode]]Local mode::
484b2a0c
PP
125 Write the trace data to the local file system.
126+
26f0c779 127The trace data output directory is:
484b2a0c 128+
26f0c779
PP
129With the option:--no-output option:::
130 None: the file system output is disabled.
131
132With the option:--output='DIR' or option:--set-url=++file://++__DIR__ option:::
133 The directory 'DIR'.
134
135Otherwise:::
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.
f87c4756 139
948f0a2e 140[[network-streaming-mode]]Network streaming mode::
484b2a0c
PP
141 Send the trace data over the network to a listening relay daemon
142 (see man:lttng-relayd(8)).
143+
144Set the trace output destination with the option:--set-url option, or
145with the option:--ctrl-url and option:--data-url options (see the
146<<url-format,URL format>> section below).
147
148[[snapshot-mode]]Snapshot mode (option:--snapshot option)::
26f0c779
PP
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).
484b2a0c 152+
26f0c779 153With this mode, LTTng:
484b2a0c 154+
26f0c779
PP
155With the option:--no-output option:::
156 Does :not: add any snapshot output to the created tracing
157 session.
158
159With 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.
162
163Otherwise:::
164 Adds an automatic snapshot output named `snapshot-1` to the created
165 tracing session.
484b2a0c 166+
26f0c779
PP
167The automatic snapshot output is a subdirectory, under the
168`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
169directory, of which the name contains the tracing session name and the
170date/time.
484b2a0c
PP
171
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.
175+
176Set the trace output destination with the option:--set-url='URL' option,
177or 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
179with `file://`.
ba50d967
PP
180
181
182[[url-format]]
183URL format
184~~~~~~~~~~
26f0c779
PP
185The argument of the option:--set-url='URL', option:--ctrl-url='URL', and
186option:--data-url='URL' options is an URL.
ba50d967 187
26f0c779 188There are two available 'URL' formats.
ba50d967 189
484b2a0c
PP
190Local format::
191+
ba50d967 192[verse]
484b2a0c
PP
193file://'TRACEDIR'
194{nbsp}
195+
196The `file://` protocol targets the *local file system*: you may only use
197such an URL with the option:--set-url option when you create the tracing
198session in local or snapshot mode (see the <<modes,Tracing session
199modes>> section above).
200+
201'TRACEDIR':::
202 Absolute path to the directory containing the trace data on the
203 local file system.
ba50d967 204
484b2a0c
PP
205Network format::
206+
207[verse]
208'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR']
209{nbsp}
210+
211This format is only available when you create the tracing session in
26f0c779
PP
212network streaming, snapshot (option:--snapshot), or live (option:--live)
213mode (see the <<modes,Tracing session modes>> section above).
484b2a0c
PP
214+
215'NETPROTO':::
ba50d967
PP
216 Network protocol, amongst:
217+
36574617
PP
218--
219`net`::
484b2a0c
PP
220 TCP over IPv4.
221+
222The default values of 'CTRLPORT' and 'DATAPORT'
223are respectively {default_network_control_port} and
224{default_network_data_port}.
36574617
PP
225
226`net6`::
484b2a0c
PP
227 TCP over IPv6.
228+
229The default values of 'CTRLPORT' and 'DATAPORT'
230are respectively {default_network_control_port} and
231{default_network_data_port}.
36574617
PP
232
233`tcp`::
484b2a0c
PP
234 Same as the `net` protocol.
235+
236You may only use this with the option:--ctrl-url and option:--data-url
237options together.
36574617
PP
238
239`tcp6`::
484b2a0c
PP
240 Same as the `net6` protocol.
241+
242You can only be use this with the option:--ctrl-url and
243option:--data-url options together.
36574617 244--
484b2a0c
PP
245+
246('HOST' | 'IPADDR'):::
26f0c779
PP
247 Hostname or IP address.
248+
249IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`);
250see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732].
ba50d967 251
484b2a0c
PP
252'CTRLPORT':::
253 Control TCP port.
ba50d967 254
484b2a0c
PP
255'DATAPORT':::
256 Data TCP port.
ba50d967 257
484b2a0c
PP
258'TRACEDIR':::
259 Path of the directory containing the trace data on the remote file
260 system.
261+
262This path is relative to the base output directory of the LTTng relay
263daemon (see the nloption:--output option of man:lttng-relayd(8)).
ba50d967
PP
264
265
f5511eea 266include::common-lttng-cmd-options-head.txt[]
ba50d967
PP
267
268
f87c4756
PP
269Mode selection
270~~~~~~~~~~~~~~
484b2a0c
PP
271See the <<modes,Tracing session modes>> section above.
272
273At most one of:
274
ba50d967 275option:--live[='DELAYUS']::
484b2a0c 276 Create the tracing session in live mode.
948f0a2e 277+
484b2a0c
PP
278The optional 'DELAYUS' argument is the maximum time (in µs) you can wait
279for the data to be flushed (sent to the connected LTTng relay daemon).
280The default value of 'DELAYUS' is {default_lttng_live_timer}.
ba50d967 281+
484b2a0c
PP
282Set the URL of the relay daemon to connect to with the option:--set-url
283option, or with the option:--ctrl-url and option:--data-url options,
284instead of using `net://127.0.0.1`.
285+
286The session daemon must be able to connect to a listening relay daemon
287(see man:lttng-relayd(8)).
ba50d967
PP
288
289option:--snapshot::
484b2a0c
PP
290 Create the tracing session in snapshot mode.
291+
26f0c779
PP
292This is equivalent to:
293+
294* One of:
295+
296--
297With the option:--no-output option::
298 Not adding any snapshot output after LTTng creates the tracing
299 session.
300
301With 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.
304
305Otherwise::
306 Adding an automatic snapshot output named `snapshot-1` immediately
307 after LTTng creates the tracing session.
308+
309The automatic snapshot output is a subdirectory, under the
310`$LTTNG_HOME/lttng-traces` (`$LTTNG_HOME` defaults to `$HOME`)
311directory, of which the name contains the tracing session name and the
312date/time.
313--
314
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)).
ba50d967
PP
318
319
320Output
321~~~~~~
322option:--no-output::
26f0c779
PP
323 Depending on the tracing session mode (see the <<modes,Tracing
324 session modes>> section above):
484b2a0c 325+
26f0c779
PP
326Local mode:::
327 Disable the file system output.
328
329Snapshot mode (option:--snapshot option):::
330 Do :not: add a snapshot output after creating the tracing session.
ba50d967 331
484b2a0c 332option:-o 'DIR', option:--output='DIR'::
26f0c779 333 Equivalent to option:--set-url=++file://++__DIR__.
ba50d967 334
484b2a0c
PP
335option:--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.
ba50d967
PP
338
339
340URL
341~~~
484b2a0c
PP
342See the <<url-format,URL format>> section above to learn more about the
343syntax of the 'URL' argument of the following options.
ba50d967 344
59b19c3c 345option:-C 'URL', option:--ctrl-url='URL'::
484b2a0c
PP
346 Set the control path URL to 'URL'.
347+
348You must also use the option:--data-url option.
26f0c779
PP
349+
350Not available in local mode (see the <<modes,Tracing session modes>>
351section above).
352+
353In snapshot mode, this is equivalent to using the nloption:--ctrl-url
354option of the `add-output` action of the man:lttng-snapshot(1) command
355immediately after creating the tracing session.
ba50d967 356
59b19c3c 357option:-D 'URL', option:--data-url='URL'::
484b2a0c
PP
358 Set the trace data path URL to 'URL'.
359+
360You must also use the option:--ctrl-url option.
26f0c779
PP
361+
362Not available in local mode (see the <<modes,Tracing session modes>>
363section above).
364+
365In snapshot mode, this is equivalent to using the nloption:--data-url
366option of the `add-output` action of the man:lttng-snapshot(1) command
367immediately after creating the tracing session.
ba50d967 368
59b19c3c 369option:-U 'URL', option:--set-url='URL'::
484b2a0c
PP
370 Set the destination URL of the control path and trace data to 'URL'.
371+
26f0c779
PP
372This URL remains unchanged as long as the tracing session exists.
373+
374Depending on the tracing session mode (see the <<modes,Tracing session
375modes>> section above):
948f0a2e 376+
26f0c779
PP
377Local mode:::
378 'URL' must start with `file://`, followed with the destination
379 directory path on the local file system.
380
381Network streaming and live modes:::
382 Equivalent to using both the option:--ctrl-url and option:--data-url
383 options.
384
385Snapshot 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.
ba50d967
PP
389
390
f5511eea 391include::common-lttng-cmd-help-options.txt[]
ba50d967
PP
392
393
f5511eea
PP
394include::common-lttng-cmd-after-options.txt[]
395
396
ebbd679f
PP
397[[examples]]
398EXAMPLES
399--------
400.Create a normal mode tracing session with a generated name.
401====
402[role="term"]
403----
404$ lttng create
405----
406====
407
408.Create a normal mode tracing session with a custom name.
409====
410[role="term"]
411----
412$ lttng create my-session
413----
414====
415
416.Create a normal mode tracing session with a specific output directory.
417====
418See the option:--output option.
419
420[role="term"]
421----
422$ lttng create --output=/path/to/traces
423----
424====
425
426.Create a network streaming mode tracing session.
427====
428See the ``Output directory'' section of man:lttng-relayd(8) to
429understand where the relay daemon to connect to (`10.0.0.242`) writes
430the received traces.
431
432See the option:--set-url option.
433
434[role="term"]
435----
436$ lttng create --set-url=net://10.0.0.242/inv4
437----
438====
439
440.Create a snapshot mode tracing session with a default snapshot output.
441====
442See the option:--snapshot option.
443
444[role="term"]
445----
446$ lttng create --snapshot
447----
448====
449
450.Create a snapshot mode tracing session with a custom snapshot output.
451====
452See the option:--snapshot and option:--set-url options.
453
454[role="term"]
455----
456$ lttng create --snapshot \
457 --set-url=tcp://192.168.1.102:1234:5678/my-snapshots
458----
459====
460
461.Create a snapshot mode tracing session with no snapshot output.
462====
463See the option:--snapshot and option:--no-output options.
464
465[role="term"]
466----
467$ lttng create --snapshot --no-output
468----
469====
470
471.Create an LTTng live mode tracing session with a default relay daemon URL.
472====
473See the option:--live option.
474
475[role="term"]
476----
477$ lttng create --live
478----
479====
480
481.Create an LTTng live mode tracing session with a custom live timer period and relay daemon URL.
482====
483See the option:--live and option:--set-url options.
484
485[role="term"]
486----
487$ lttng create --live=250000 \
488 --set-url=tcp://relayd34:4885:4886
489----
490====
491
492.Create a normal mode tracing session with a custom directory containing the ring buffer shared memory files.
493====
494See the option:--shm-path option.
495
496[role="term"]
497----
498$ lttng create my-session --shm-path=/mnt/nvram2/lttng
499----
500====
501
502
f5511eea 503include::common-footer.txt[]
ba50d967
PP
504
505
506SEE ALSO
507--------
484b2a0c 508man:lttng(1),
7c1a4458 509man:lttng-destroy(1),
484b2a0c 510man:lttng-enable-channel(1),
af1c4164 511man:lttng-list(1),
484b2a0c 512man:lttng-rotate(1),
26f0c779 513man:lttng-save(1),
7c1a4458 514man:lttng-set-session(1),
484b2a0c 515man:lttng-start(1),
af1c4164
PP
516man:lttng-status(1),
517man:lttng-track(1),
518man:lttng-concepts(7),
519man:lttng-relayd(8),
520man:lttng-sessiond(8)
This page took 0.054198 seconds and 4 git commands to generate.