Commit | Line | Data |
---|---|---|
ba50d967 PP |
1 | lttng-create(1) |
2 | =============== | |
484b2a0c | 3 | :revdate: 8 April 2021 |
ba50d967 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-create - Create an LTTng tracing session | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
484b2a0c | 13 | Create a local mode tracing session: |
ba50d967 PP |
14 | |
15 | [verse] | |
484b2a0c PP |
16 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] [option:--shm-path='DIR'] |
17 | [option:--no-output | option:--output='DIR' | option:--set-url=file://'DIR'] | |
f87c4756 | 18 | |
484b2a0c | 19 | Create 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 | 25 | Create a snapshot mode tracing session: |
ba50d967 PP |
26 | |
27 | [verse] | |
1f3c3a24 | 28 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--snapshot |
484b2a0c | 29 | [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] |
ba50d967 | 30 | |
484b2a0c | 31 | Create a live mode tracing session: |
ba50d967 PP |
32 | |
33 | [verse] | |
1f3c3a24 | 34 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *create* ['SESSION'] option:--live[='DELAYUS'] |
484b2a0c | 35 | [option:--shm-path='DIR'] [option:--set-url='URL' | option:--ctrl-url='URL' option:--data-url='URL'] |
ba50d967 PP |
36 | |
37 | DESCRIPTION | |
38 | ----------- | |
484b2a0c PP |
39 | The `lttng create` command creates a new tracing session for your Unix |
40 | user. | |
41 | ||
42 | A tracing session is a stateful dialogue between you and a | |
43 | session daemon (see man:lttng-sessiond(8)) for everything related to | |
44 | event recording. | |
45 | ||
46 | Everything that you do when you control LTTng tracers to record events | |
47 | happens within a tracing session. In particular, a tracing session: | |
48 | ||
49 | * Has its own name. | |
50 | ||
51 | * Has its own set of trace files, if any. | |
52 | ||
53 | * Has its own state of activity (started or stopped). | |
54 | ||
55 | * Has its own mode (local, network streaming, | |
56 | snapshot, or live). | |
57 | + | |
58 | See the <<modes,Tracing session modes>> section below to learn more. | |
59 | ||
60 | * Has its own channels (see man:lttng-enable-channel(1)) to which are | |
61 | attached their own recording event rules (see | |
62 | man:lttng-enable-event(1)). | |
63 | ||
64 | * Has its own process attribute tracking inclusion sets (see | |
65 | man:lttng-track(1)). | |
66 | ||
67 | Without the 'SESSION' argument, LTTng automatically generates a tracing | |
68 | session name having the ++auto-++__YYYYmmdd__++-++__HHMMSS__ form, where | |
69 | 'YYYYmmdd' and 'HHMMSS' are the creation date and time. 'SESSION' may | |
70 | :not: contain the character `/`. | |
71 | ||
72 | Specify the path of the directory containing the shared memory files | |
73 | holding the channel ring buffers with the option:--shm-path option. | |
74 | Specifying a location on an NVRAM file system makes it possible to | |
75 | recover the latest recorded trace data when the system reboots after a | |
76 | crash with the man:lttng-crash(1) utility. | |
77 | ||
78 | By default, the `create` command automatically spawns a session daemon | |
79 | for your Unix user if none is currently running. Override the path of | |
80 | the session daemon binary to spawn with the general | |
81 | genoption:--sessiond-path option. Avoid automatically spawning a session | |
82 | daemon with the general genoption:--no-sessiond option. | |
83 | ||
84 | List the tracing sessions of your Unix user with the man:lttng-list(1) | |
ba50d967 PP |
85 | command. |
86 | ||
484b2a0c PP |
87 | Start and stop a tracing session with the man:lttng-start(1) and |
88 | man:lttng-stop(1) commands. | |
ba50d967 | 89 | |
484b2a0c PP |
90 | Save and load a tracing session with the man:lttng-save(1) and |
91 | man:lttng-load(1) commands. | |
92 | ||
93 | Archive the current trace chunk (rotate) a tracing session with the | |
94 | man:lttng-rotate(1) command. | |
95 | ||
96 | Destroy a tracing session with the man:lttng-destroy(1) command. | |
97 | ||
98 | ||
99 | Current tracing session | |
100 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
101 | When you run the `create` command, LTTng creates the | |
102 | `$LTTNG_HOME/.lttngrc` file if it doesn't exist (`$LTTNG_HOME` defaults | |
103 | to `$HOME`). | |
104 | ||
105 | `$LTTNG_HOME/.lttngrc` contains the name of the _current tracing | |
106 | session_. | |
107 | ||
108 | When you create a new tracing session with the `create` command, LTTng | |
109 | updates the current tracing session. | |
110 | ||
111 | The following man:lttng(1) commands select the current tracing session | |
112 | if you don't specify one: | |
113 | ||
114 | * man:lttng-add-context(1) | |
115 | * man:lttng-clear(1) | |
116 | * man:lttng-destroy(1) | |
117 | * man:lttng-disable-channel(1) | |
118 | * man:lttng-disable-event(1) | |
119 | * man:lttng-disable-rotation(1) | |
120 | * man:lttng-enable-channel(1) | |
121 | * man:lttng-enable-event(1) | |
122 | * man:lttng-enable-rotation(1) | |
123 | * man:lttng-regenerate(1) | |
124 | * man:lttng-rotate(1) | |
125 | * man:lttng-save(1) | |
126 | * man:lttng-snapshot(1) | |
127 | * man:lttng-start(1) | |
128 | * man:lttng-status(1) | |
129 | * man:lttng-stop(1) | |
130 | * man:lttng-track(1) | |
131 | * man:lttng-untrack(1) | |
132 | * man:lttng-view(1) | |
133 | ||
134 | Set the current tracing session manually with the | |
135 | man:lttng-set-session(1) command, without having to edit the `.lttngrc` | |
136 | file. | |
137 | ||
138 | ||
139 | [[modes]] | |
140 | Tracing session modes | |
141 | ~~~~~~~~~~~~~~~~~~~~~ | |
142 | LTTng offers four tracing session modes: | |
ba50d967 | 143 | |
948f0a2e | 144 | [[local-mode]]Local mode:: |
484b2a0c PP |
145 | Write the trace data to the local file system. |
146 | + | |
147 | The option:--output option specifies the trace path. Using | |
148 | option:--set-url=++file://++__DIR__ is equivalent to using | |
149 | option:--output='DIR'. | |
f87c4756 | 150 | + |
484b2a0c PP |
151 | Disable the file system output with the |
152 | option:--no-output option. | |
153 | + | |
154 | If you don't use any of the option:--output, option:--set-url, or | |
155 | option:--no-output options, then LTTng writes the trace data locally to | |
156 | the `$LTTNG_HOME/lttng-traces` directory (`$LTTNG_HOME` defaults to | |
157 | `$HOME`). | |
f87c4756 | 158 | |
948f0a2e | 159 | [[network-streaming-mode]]Network streaming mode:: |
484b2a0c PP |
160 | Send the trace data over the network to a listening relay daemon |
161 | (see man:lttng-relayd(8)). | |
162 | + | |
163 | Set the trace output destination with the option:--set-url option, or | |
164 | with the option:--ctrl-url and option:--data-url options (see the | |
165 | <<url-format,URL format>> section below). | |
166 | ||
167 | [[snapshot-mode]]Snapshot mode (option:--snapshot option):: | |
168 | Don't write the trace data to the local file system by default | |
169 | (implicit option:--no-output option): only write the trace data to | |
170 | the local file system or send it to a listening relay daemon | |
171 | (man:lttng-relayd(8)) when LTTng takes a snapshot. | |
172 | + | |
173 | LTTng automatically configures the channels of such a tracing session to | |
174 | be snapshot-ready on creation (see man:lttng-enable-channel(1)). | |
175 | + | |
176 | LTTng takes a snapshot of such a tracing session when: | |
177 | + | |
178 | -- | |
179 | * You run the man:lttng-snapshot(1) command. | |
180 | * LTTng executes a `snapshot-session` trigger action (see | |
181 | man:lttng-add-trigger(1)). | |
182 | -- | |
183 | + | |
184 | Set the default snapshot output destination with the | |
185 | option:--set-url option, or with the option:--ctrl-url and | |
186 | option:--data-url options (see the <<url-format,URL format>> section | |
187 | below). | |
188 | ||
189 | [[live-mode]]Live mode (option:--live option):: | |
190 | Send the trace data over the network to a listening relay daemon | |
191 | (see man:lttng-relayd(8)) for live reading. | |
192 | + | |
193 | Set the trace output destination with the option:--set-url='URL' option, | |
194 | or with the option:--ctrl-url='URL' and option:--data-url='URL' options | |
195 | (see the <<url-format,URL format>> section below). 'URL' may :not: start | |
196 | with `file://`. | |
ba50d967 PP |
197 | |
198 | ||
199 | [[url-format]] | |
200 | URL format | |
201 | ~~~~~~~~~~ | |
484b2a0c PP |
202 | The argument of the option:--set-url, option:--ctrl-url, and |
203 | option:--data-url options is an URL. | |
ba50d967 | 204 | |
484b2a0c | 205 | There are two available URL formats. |
ba50d967 | 206 | |
484b2a0c PP |
207 | Local format:: |
208 | + | |
ba50d967 | 209 | [verse] |
484b2a0c PP |
210 | file://'TRACEDIR' |
211 | {nbsp} | |
212 | + | |
213 | The `file://` protocol targets the *local file system*: you may only use | |
214 | such an URL with the option:--set-url option when you create the tracing | |
215 | session in local or snapshot mode (see the <<modes,Tracing session | |
216 | modes>> section above). | |
217 | + | |
218 | 'TRACEDIR'::: | |
219 | Absolute path to the directory containing the trace data on the | |
220 | local file system. | |
ba50d967 | 221 | |
484b2a0c PP |
222 | Network format:: |
223 | + | |
224 | [verse] | |
225 | 'NETPROTO'://('HOST' | 'IPADDR')[:__CTRLPORT__[:__DATAPORT__]][/'TRACEDIR'] | |
226 | {nbsp} | |
227 | + | |
228 | This format is only available when you create the tracing session in | |
229 | network streaming, snapshot, or live mode (see the <<modes,Tracing | |
230 | session modes>> section above). | |
231 | + | |
232 | 'NETPROTO'::: | |
ba50d967 PP |
233 | Network protocol, amongst: |
234 | + | |
36574617 PP |
235 | -- |
236 | `net`:: | |
484b2a0c PP |
237 | TCP over IPv4. |
238 | + | |
239 | The default values of 'CTRLPORT' and 'DATAPORT' | |
240 | are respectively {default_network_control_port} and | |
241 | {default_network_data_port}. | |
36574617 PP |
242 | |
243 | `net6`:: | |
484b2a0c PP |
244 | TCP over IPv6. |
245 | + | |
246 | The default values of 'CTRLPORT' and 'DATAPORT' | |
247 | are respectively {default_network_control_port} and | |
248 | {default_network_data_port}. | |
36574617 PP |
249 | |
250 | `tcp`:: | |
484b2a0c PP |
251 | Same as the `net` protocol. |
252 | + | |
253 | You may only use this with the option:--ctrl-url and option:--data-url | |
254 | options together. | |
36574617 PP |
255 | |
256 | `tcp6`:: | |
484b2a0c PP |
257 | Same as the `net6` protocol. |
258 | + | |
259 | You can only be use this with the option:--ctrl-url and | |
260 | option:--data-url options together. | |
36574617 | 261 | -- |
484b2a0c PP |
262 | + |
263 | ('HOST' | 'IPADDR')::: | |
264 | Hostname or IP address (IPv6 address *must* be enclosed in square | |
265 | brackets (`[` and{nbsp}`]`); see | |
266 | https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]). | |
ba50d967 | 267 | |
484b2a0c PP |
268 | 'CTRLPORT'::: |
269 | Control TCP port. | |
ba50d967 | 270 | |
484b2a0c PP |
271 | 'DATAPORT'::: |
272 | Data TCP port. | |
ba50d967 | 273 | |
484b2a0c PP |
274 | 'TRACEDIR'::: |
275 | Path of the directory containing the trace data on the remote file | |
276 | system. | |
277 | + | |
278 | This path is relative to the base output directory of the LTTng relay | |
279 | daemon (see the nloption:--output option of man:lttng-relayd(8)). | |
ba50d967 PP |
280 | |
281 | ||
282 | include::common-cmd-options-head.txt[] | |
283 | ||
284 | ||
f87c4756 PP |
285 | Mode selection |
286 | ~~~~~~~~~~~~~~ | |
484b2a0c PP |
287 | See the <<modes,Tracing session modes>> section above. |
288 | ||
289 | At most one of: | |
290 | ||
ba50d967 | 291 | option:--live[='DELAYUS']:: |
484b2a0c | 292 | Create the tracing session in live mode. |
948f0a2e | 293 | + |
484b2a0c PP |
294 | The optional 'DELAYUS' argument is the maximum time (in µs) you can wait |
295 | for the data to be flushed (sent to the connected LTTng relay daemon). | |
296 | The default value of 'DELAYUS' is {default_lttng_live_timer}. | |
ba50d967 | 297 | + |
484b2a0c PP |
298 | Set the URL of the relay daemon to connect to with the option:--set-url |
299 | option, or with the option:--ctrl-url and option:--data-url options, | |
300 | instead of using `net://127.0.0.1`. | |
301 | + | |
302 | The session daemon must be able to connect to a listening relay daemon | |
303 | (see man:lttng-relayd(8)). | |
ba50d967 PP |
304 | |
305 | option:--snapshot:: | |
484b2a0c PP |
306 | Create the tracing session in snapshot mode. |
307 | + | |
308 | This is equivalent to using the option:--no-output option and creating | |
309 | all the channels of this new tracing session with the | |
310 | nloption:--override and nloption:--output=++mmap++ options (see | |
311 | man:lttng-enable-channel(1)). | |
ba50d967 PP |
312 | |
313 | ||
314 | Output | |
315 | ~~~~~~ | |
316 | option:--no-output:: | |
484b2a0c PP |
317 | In local mode (see the <<modes,Tracing session modes>> section |
318 | above), do :not: write any trace data. | |
319 | + | |
320 | You may :not: use this option with the option:--output option. | |
ba50d967 | 321 | |
484b2a0c PP |
322 | option:-o 'DIR', option:--output='DIR':: |
323 | In local mode, set the trace output path to 'DIR'. | |
324 | + | |
325 | You may :not: use this option with the option:--no-output option. | |
ba50d967 | 326 | |
484b2a0c PP |
327 | option:--shm-path='DIR':: |
328 | Set the path of the directory containing the shared memory files | |
329 | holding the channel ring buffers to 'DIR' on the local file sytem. | |
ba50d967 PP |
330 | |
331 | ||
332 | URL | |
333 | ~~~ | |
484b2a0c PP |
334 | See the <<url-format,URL format>> section above to learn more about the |
335 | syntax of the 'URL' argument of the following options. | |
ba50d967 | 336 | |
59b19c3c | 337 | option:-C 'URL', option:--ctrl-url='URL':: |
484b2a0c PP |
338 | Set the control path URL to 'URL'. |
339 | + | |
340 | You must also use the option:--data-url option. | |
ba50d967 | 341 | |
59b19c3c | 342 | option:-D 'URL', option:--data-url='URL':: |
484b2a0c PP |
343 | Set the trace data path URL to 'URL'. |
344 | + | |
345 | You must also use the option:--ctrl-url option. | |
ba50d967 | 346 | |
59b19c3c | 347 | option:-U 'URL', option:--set-url='URL':: |
484b2a0c PP |
348 | Set the destination URL of the control path and trace data to 'URL'. |
349 | + | |
350 | This URL stays the same as long as the tracing session exists. | |
948f0a2e | 351 | + |
484b2a0c PP |
352 | In local mode (see the <<modes,Tracing session modes>> section above), |
353 | 'URL' must start with `file://`, followed with the destination directory | |
354 | path on the local file system. | |
ba50d967 PP |
355 | |
356 | ||
357 | include::common-cmd-help-options.txt[] | |
358 | ||
359 | ||
360 | include::common-cmd-footer.txt[] | |
361 | ||
362 | ||
363 | SEE ALSO | |
364 | -------- | |
484b2a0c | 365 | man:lttng(1), |
7c1a4458 | 366 | man:lttng-destroy(1), |
484b2a0c PP |
367 | man:lttng-enable-channel(1), |
368 | man:lttng-relayd(8), | |
369 | man:lttng-rotate(1), | |
370 | man:lttng-sessiond(8), | |
7c1a4458 | 371 | man:lttng-set-session(1), |
484b2a0c PP |
372 | man:lttng-start(1), |
373 | man:lttng-stop(1), | |
374 | man:lttng-track(1) |