lttng-create(1): use the correct DATAPORT/CTRLPORT variables
[lttng-tools.git] / doc / man / lttng-create.1.txt
CommitLineData
ba50d967
PP
1lttng-create(1)
2===============
3
4
5NAME
6----
7lttng-create - Create an LTTng tracing session
8
9
10SYNOPSIS
11--------
f87c4756 12Local mode:
ba50d967
PP
13
14[verse]
f87c4756
PP
15*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
16 [option:--no-output | option:--output='PATH' | option:--set-url=file://'PATH'] ['SESSION']
17
18Network streaming mode:
19
20[verse]
21*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* [option:--shm-path='PATH']
22 (option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL') ['SESSION']
ba50d967
PP
23
24Snapshot mode:
25
26[verse]
f87c4756
PP
27*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--snapshot [option:--shm-path='PATH']
28 [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
ba50d967
PP
29
30Live mode:
31
32[verse]
f87c4756
PP
33*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* option:--live[='DELAYUS'] [option:--shm-path='PATH']
34 [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] ['SESSION']
ba50d967
PP
35
36
37DESCRIPTION
38-----------
39The `lttng create` command creates a new tracing session.
40
41A tracing session is a named container of channels, which in turn
42contain event rules. It is domain-agnostic, in that channels and event
43rules can be enabled for the user space tracer and/or the Linux
44kernel tracer.
45
46On execution, an `.lttngrc` file is created, if it does not exist, in the
47user's home directory. This file contains the name of the current tracing
48session. When creating a new tracing session with `lttng create`, the
49current tracing session is set to this new tracing session. The
7c1a4458 50man:lttng-set-session(1) command can be used to set the current
ba50d967
PP
51tracing session without manually editing the `.lttngrc` file.
52
53If 'SESSION' is omitted, a session name is automatically created having
54this form: `auto-YYYYmmdd-HHMMSS`. 'SESSION' *must not* contain the
55character `/`.
56
57The option:--shm-path option can be used to specify the path to the
58shared memory holding the ring buffers. Specifying a location on an
59NVRAM file system makes it possible to retrieve the latest recorded
60trace data when the system reboots after a crash. To view the events
61of ring buffer files after a system crash, use the
7c1a4458 62man:lttng-crash(1) utility.
ba50d967 63
7c1a4458 64Tracing sessions are destroyed using the man:lttng-destroy(1)
ba50d967
PP
65command.
66
67
68Creation modes
69~~~~~~~~~~~~~~
f87c4756 70There are four tracing session modes:
ba50d967 71
f87c4756 72Local mode::
ba50d967
PP
73 Traces the local system and writes the trace to the local
74 file system. The option:--output option specifies the trace path.
f87c4756
PP
75 Using option:--set-url=file://'PATH' is the equivalent of using
76 option:--output='PATH'. The file system output can be disabled using
77 the option:--no-output option.
78+
79If none of the options mentioned above are used, then the trace is
80written locally in the `$LTTNG_HOME/lttng-traces` directory
81(`$LTTNG_HOME` defaults to `$HOME`).
82
83Network streaming mode::
84 Traces the local system and sends the trace over the network to
85 a listening relay daemon (see man:lttng-relayd(8)).
86 The option:--set-url, or option:--ctrl-url and option:--data-url
87 options set the trace output destination (see the
88 <<url-format,URL format>> section below).
ba50d967
PP
89
90Snapshot mode::
91 Traces the local system without writing the trace to the local file
92 system (implicit option:--no-output option). Channels are automatically
93 configured to be snapshot-ready on creation (see
7c1a4458 94 man:lttng-enable-channel(1)). The man:lttng-snapshot(1)
ba50d967
PP
95 command is used to take snapshots of the current ring buffers.
96 The option:--set-url, or option:--ctrl-url and option:--data-url
97 options set the default snapshot output destination.
98
99Live mode::
100 Traces the local system, sending trace data to an LTTng relay daemon
7c1a4458 101 over the network (see man:lttng-relayd(8)). The
ba50d967
PP
102 option:--set-url, or option:--ctrl-url and option:--data-url options
103 set the trace output destination. The live output URLs cannot use
f87c4756
PP
104 the `file://` protocol (see the <<url-format,URL format>>
105 section below).
ba50d967
PP
106
107
108[[url-format]]
109URL format
110~~~~~~~~~~
f87c4756
PP
111The option:--set-url, option:--ctrl-url, and option:--data-url options'
112arguments are URLs.
ba50d967
PP
113
114The format of those URLs is one of:
115
116[verse]
117file://'TRACEPATH'
118'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEPATH']
119
f87c4756
PP
120The `file://` protocol targets the *local file system* and can only
121be used as the option:--set-url option's argument in _local mode_.
ba50d967
PP
122
123'TRACEPATH'::
124 Absolute path to trace files on the local file system.
125
f87c4756 126The other version is used for the _network streaming mode_.
ba50d967
PP
127
128'NETPROTO'::
129 Network protocol, amongst:
130+
36574617
PP
131--
132`net`::
1f5cd9d5 133 TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT'
36574617
PP
134 are resp. 5342 and 5343.
135
136`net6`::
137 TCP over IPv6: same default ports as the `net` protocol.
138
139`tcp`::
140 Same as the `net` protocol; can only be used with the
141 option:--ctrl-url and option:--data-url options together.
142
143`tcp6`::
144 Same as the `net6` protocol; can only be used with the
145 option:--ctrl-url and option:--data-url options together.
146--
ba50d967
PP
147
148('HOST' | 'IPADDR')::
149 Hostname or IP address (IPv6 address *must* be enclosed in brackets
150 (`[` and `]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
151
152'CTRLPORT'::
153 Control port.
154
155'DATAPORT'::
156 Data port.
157
158'TRACEPATH'::
159 Path of trace files on the remote file system. This path is relative
160 to the base output directory set on the relay daemon side;
7c1a4458 161 see man:lttng-relayd(8).
ba50d967
PP
162
163
164include::common-cmd-options-head.txt[]
165
166
f87c4756
PP
167Mode selection
168~~~~~~~~~~~~~~
ba50d967
PP
169option:--live[='DELAYUS']::
170 Create the session in live mode. The optional 'DELAYUS' parameter,
171 given in microseconds, is the maximum time the user can wait for
172 the data to be flushed. This mode can be set with a network URL
173 (options option:--set-url, or option:--ctrl-url and option:--data-url)
7c1a4458 174 and must have a relay daemon listening (see man:lttng-relayd(8)).
ba50d967 175+
c93eadad
PP
176By default, 'DELAYUS' is {default_lttng_live_timer} and the network URL
177is set to `net://127.0.0.1`.
ba50d967
PP
178
179option:--snapshot::
180 Create the session in snapshot mode. This is the equivalent of using
181 the option:--no-output option and creating all the channels of this
182 new tracing session in overwrite mode with an `mmap` output type.
183
184
185Output
186~~~~~~
187option:--no-output::
188 Do not output any trace data.
189
190option:-o, option:--output='PATH'::
191 Set trace output path to 'PATH'.
192
193option:--shm-path='PATH'::
194 Create shared memory holding buffers at 'PATH'.
195
196
197URL
198~~~
199See the <<url-format,URL format>> section above for more information
200about the syntax of the following options' 'URL' argument.
201
202option:-C, option:--ctrl-url='URL'::
203 Set control path URL to 'URL' (must use option:--data-url option
204 also).
205
206option:-D, option:--data-url='URL'::
207 Set data path URL to 'URL' (must use option:--ctrl-url option
208 also).
209
210option:-U, option:--set-url='URL'::
211 Set URL destination of the trace data to 'URL'. It is persistent for
212 the session lifetime. This option sets both data
213 (option:--data-url option) and control (option:--ctrl-url option)
214 URLs at the same time.
215
216
217include::common-cmd-help-options.txt[]
218
219
220include::common-cmd-footer.txt[]
221
222
223SEE ALSO
224--------
7c1a4458
PP
225man:lttng-destroy(1),
226man:lttng-set-session(1),
227man:lttng(1)
This page took 0.046751 seconds and 4 git commands to generate.