Commit | Line | Data |
---|---|---|
b4867b3b PP |
1 | lttng-enable-channel(1) |
2 | ======================= | |
3 | ||
4 | ||
5 | NAME | |
6 | ---- | |
7 | lttng-enable-channel - Create or enable LTTng channels | |
8 | ||
9 | ||
10 | SYNOPSIS | |
11 | -------- | |
12 | Create a Linux kernel channel: | |
13 | ||
14 | [verse] | |
ce19b9ed | 15 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel |
240311ba | 16 | [option:--overwrite] [option:--output=(`mmap` | `splice`)] |
b4867b3b PP |
17 | [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] |
18 | [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] | |
961df0d0 | 19 | [option:--monitor-timer='PERIODUS'] |
b4867b3b PP |
20 | [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] |
21 | [option:--session='SESSION'] 'CHANNEL' | |
22 | ||
23 | Create a user space channel: | |
24 | ||
25 | [verse] | |
ce19b9ed | 26 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace |
7197e9ec | 27 | [option:--overwrite | option:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid] |
b4867b3b PP |
28 | [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT'] |
29 | [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS'] | |
7197e9ec | 30 | [option:--monitor-timer='PERIODUS'] |
b4867b3b PP |
31 | [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT'] |
32 | [option:--session='SESSION'] 'CHANNEL' | |
33 | ||
34 | Enable existing channel(s): | |
35 | ||
36 | [verse] | |
ce19b9ed | 37 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel) |
b4867b3b PP |
38 | [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']... |
39 | ||
40 | ||
41 | DESCRIPTION | |
42 | ----------- | |
43 | The `lttng enable-channel` command can create a new channel, or enable | |
44 | one or more existing and disabled ones. | |
45 | ||
46 | A channel is the owner of sub-buffers holding recorded events. Event, | |
7c1a4458 | 47 | rules, when created using man:lttng-enable-event(1), are always |
b4867b3b PP |
48 | assigned to a channel. When creating a new channel, many parameters |
49 | related to those sub-buffers can be fine-tuned. They are described in | |
50 | the subsections below. | |
51 | ||
52 | When 'CHANNEL' does not name an existing channel, a channel named | |
53 | 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL' | |
54 | is enabled. | |
55 | ||
7c1a4458 | 56 | Note that the man:lttng-enable-event(1) command can automatically |
b4867b3b PP |
57 | create default channels when no channel exist. |
58 | ||
59 | A channel is always contained in a tracing session | |
7c1a4458 | 60 | (see man:lttng-create(1) for creating a tracing session). The |
b4867b3b PP |
61 | session in which a channel is created using `lttng enable-channel` can |
62 | be specified using the option:--session option. If the option:--session | |
63 | option is omitted, the current tracing session is targeted. | |
64 | ||
65 | Existing enabled channels can be disabled using | |
7c1a4458 PP |
66 | man:lttng-disable-channel(1). Channels of a given session can be |
67 | listed using man:lttng-list(1). | |
b4867b3b | 68 | |
1076f2b7 PP |
69 | See the <<limitations,LIMITATIONS>> section below for a list of |
70 | limitations of this command to consider. | |
b4867b3b PP |
71 | |
72 | ||
73 | Event loss modes | |
74 | ~~~~~~~~~~~~~~~~ | |
7197e9ec PP |
75 | LTTng tracers are non-blocking by default: when no empty sub-buffer |
76 | exists, losing events is acceptable when the alternative would be to | |
77 | cause substantial delays in the instrumented application's execution. | |
b4867b3b PP |
78 | |
79 | LTTng privileges performance over integrity, aiming at perturbing the | |
80 | traced system as little as possible in order to make tracing of subtle | |
81 | race conditions and rare interrupt cascades possible. | |
82 | ||
7197e9ec PP |
83 | You can allow the user space tracer to block with a |
84 | option:--blocking-timeout option set to a positive value or to `inf`, | |
85 | and with an application which is instrumented with LTTng-UST started | |
86 | with a set `LTTNG_UST_ALLOW_BLOCKING` environment variable. See | |
87 | man:lttng-ust(3) for more details. | |
88 | ||
b4867b3b PP |
89 | When it comes to losing events because no empty sub-buffer is available, |
90 | the channel's event loss mode, specified by one of the option:--discard | |
91 | and option:--overwrite options, determines what to do amongst: | |
92 | ||
93 | Discard:: | |
94 | Drop the newest events until a sub-buffer is released. | |
95 | ||
96 | Overwrite:: | |
97 | Clear the sub-buffer containing the oldest recorded events and start | |
98 | recording the newest events there. This mode is sometimes called | |
99 | _flight recorder mode_ because it behaves like a flight recorder: | |
100 | always keep a fixed amount of the latest data. | |
101 | ||
102 | Which mechanism to choose depends on the context: prioritize the newest | |
103 | or the oldest events in the ring buffer? | |
104 | ||
105 | Beware that, in overwrite mode (option:--overwrite option), a whole | |
106 | sub-buffer is abandoned as soon as a new event doesn't find an empty | |
107 | sub-buffer, whereas in discard mode (option:--discard option), only the | |
108 | event that doesn't fit is discarded. | |
109 | ||
110 | Also note that a count of lost events is incremented and saved in the | |
111 | trace itself when an event is lost in discard mode, whereas no | |
112 | information is kept when a sub-buffer gets overwritten before being | |
113 | committed. | |
114 | ||
115 | The probability of losing events, if it is experience in a given | |
116 | context, can be reduced by fine-tuning the sub-buffers count and size | |
117 | (see next subsection). | |
118 | ||
119 | ||
120 | Sub-buffers count and size | |
121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
122 | The option:--num-subbuf and option:--subbuf-size options respectively | |
123 | set the number of sub-buffers and their individual size when creating | |
124 | a new channel. | |
125 | ||
126 | Note that there is a noticeable tracer's CPU overhead introduced when | |
127 | switching sub-buffers (marking a full one as consumable and switching | |
128 | to an empty one for the following events to be recorded). Knowing this, | |
129 | the following list presents a few practical situations along with how | |
130 | to configure sub-buffers for them when creating a channel in overwrite | |
131 | mode (option:--overwrite option): | |
132 | ||
133 | High event throughput:: | |
134 | In general, prefer bigger sub-buffers to lower the risk of losing | |
135 | events. Having bigger sub-buffers also ensures a lower sub-buffer | |
136 | switching frequency. The number of sub-buffers is only meaningful | |
137 | if the channel is enabled in overwrite mode: in this case, if a | |
138 | sub-buffer overwrite happens, the other sub-buffers | |
139 | are left unaltered. | |
140 | ||
141 | Low event throughput:: | |
142 | In general, prefer smaller sub-buffers since the risk of losing | |
143 | events is already low. Since events happen less frequently, the | |
144 | sub-buffer switching frequency should remain low and thus the | |
145 | tracer's overhead should not be a problem. | |
146 | ||
147 | Low memory system:: | |
148 | If the target system has a low memory limit, prefer fewer first, | |
149 | then smaller sub-buffers. Even if the system is limited in memory, | |
150 | it is recommended to keep the sub-buffers as big as possible to | |
151 | avoid a high sub-buffer switching frequency. | |
152 | ||
153 | In discard mode (option:--discard option), the sub-buffers count | |
154 | parameter is pointless: using two sub-buffers and setting their size | |
155 | according to the requirements of the context is fine. | |
156 | ||
157 | ||
961df0d0 PP |
158 | Switch timer |
159 | ~~~~~~~~~~~~ | |
b4867b3b PP |
160 | When a channel's switch timer fires, a sub-buffer switch happens. This |
161 | timer may be used to ensure that event data is consumed and committed | |
162 | to trace files periodically in case of a low event throughput. | |
163 | ||
164 | It's also convenient when big sub-buffers are used to cope with sporadic | |
165 | high event throughput, even if the throughput is normally lower. | |
166 | ||
961df0d0 PP |
167 | Use the option:--switch-timer option to control the switch timer's |
168 | period of the channel to create. | |
169 | ||
170 | ||
171 | Read timer | |
172 | ~~~~~~~~~~ | |
173 | By default, an internal notification mechanism is used to signal a full | |
174 | sub-buffer so that it can be consumed. When such notifications must be | |
175 | avoided, for example in real-time applications, the channel's read timer | |
176 | can be used instead. When the read timer fires, sub-buffers are checked | |
177 | for consumption when they are full. | |
178 | ||
179 | Use the option:--read-timer option to control the read timer's period of | |
180 | the channel to create. | |
181 | ||
182 | ||
183 | Monitor timer | |
184 | ~~~~~~~~~~~~~ | |
185 | When a channel's monitor timer fires, its registered trigger conditions | |
186 | are evaluated using the current values of its properties (for example, | |
187 | the current usage of its sub-buffers). When a trigger condition is true, | |
188 | LTTng executes its associated action. The only type of action currently | |
189 | supported is to notify one or more user applications. | |
190 | ||
191 | See the installed $$C/C++$$ headers in `lttng/action`, | |
192 | `lttng/condition`, `lttng/notification`, and `lttng/trigger` to learn | |
193 | more about application notifications and triggers. | |
194 | ||
195 | Use the option:--monitor-timer option to control the monitor timer's | |
196 | period of the channel to create. | |
b4867b3b PP |
197 | |
198 | ||
199 | Buffering scheme | |
200 | ~~~~~~~~~~~~~~~~ | |
201 | In the user space tracing domain, two buffering schemes are available | |
202 | when creating a channel: | |
203 | ||
204 | Per-process buffering (option:--buffers-pid option):: | |
205 | Keep one ring buffer per process. | |
206 | ||
207 | Per-user buffering (option:--buffers-uid option):: | |
208 | Keep one ring buffer for all the processes of a single user. | |
209 | ||
210 | The per-process buffering scheme consumes more memory than the per-user | |
211 | option if more than one process is instrumented for LTTng-UST. | |
212 | However, per-process buffering ensures that one process having a high | |
213 | event throughput won't fill all the shared sub-buffers, only its own. | |
214 | ||
215 | The Linux kernel tracing domain only has one available buffering scheme | |
216 | which is to use a single ring buffer for the whole system | |
217 | (option:--buffers-global option). | |
218 | ||
219 | ||
220 | Trace files limit and size | |
221 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
222 | By default, trace files can grow as large as needed. The maximum size | |
223 | of each trace file written by a channel can be set on creation using the | |
224 | option:--tracefile-size option. When such a trace file's size reaches | |
225 | the channel's fixed maximum size, another trace file is created to hold | |
226 | the next recorded events. A file count is appended to each trace file | |
227 | name in this case. | |
228 | ||
229 | If the option:--tracefile-size option is used, the maximum number of | |
230 | created trace files is unlimited. To limit them, the | |
231 | option:--tracefile-count option can be used. This option is always used | |
232 | in conjunction with the option:--tracefile-size option. | |
233 | ||
234 | For example, consider this command: | |
235 | ||
d4f093aa | 236 | [role="term"] |
03c5529d PP |
237 | ---- |
238 | $ lttng enable-channel --kernel --tracefile-size=4096 \ | |
b4867b3b | 239 | --tracefile-count=32 my-channel |
03c5529d | 240 | ---- |
b4867b3b PP |
241 | |
242 | Here, for each stream, the maximum size of each trace file is | |
243 | 4 kiB and there can be a maximum of 32 different files. When there is | |
244 | no space left in the last file, _trace file rotation_ happens: the first | |
245 | file is cleared and new sub-buffers containing events are written there. | |
246 | ||
247 | ||
248 | include::common-cmd-options-head.txt[] | |
249 | ||
250 | ||
251 | Domain | |
252 | ~~~~~~ | |
253 | One of: | |
254 | ||
255 | option:-k, option:--kernel:: | |
256 | Enable channel in the Linux kernel domain. | |
257 | ||
258 | option:-u, option:--userspace:: | |
259 | Enable channel in the user space domain. | |
260 | ||
261 | ||
262 | Target | |
263 | ~~~~~~ | |
59b19c3c | 264 | option:-s 'SESSION', option:--session='SESSION':: |
b4867b3b PP |
265 | Create or enable channel in the tracing session named 'SESSION' |
266 | instead of the current tracing session. | |
267 | ||
268 | ||
269 | Event loss mode | |
270 | ~~~~~~~~~~~~~~~ | |
7197e9ec PP |
271 | option:--blocking-timeout='TIMEOUTUS':: |
272 | Set the channel's blocking timeout value to 'TIMEOUTUS' µs for | |
273 | instrumented applications executed with a set | |
274 | `LTTNG_UST_ALLOW_BLOCKING` environment variable: | |
275 | + | |
276 | -- | |
277 | 0 (default):: | |
278 | Do not block (non-blocking mode). | |
279 | ||
280 | `inf`:: | |
281 | Block forever until room is available in the sub-buffer to write the | |
282 | event record. | |
283 | ||
284 | __n__, a positive value:: | |
285 | Wait for at most __n__ µs when trying to write into a sub-buffer. | |
286 | After __n__ µs, discard the event record. | |
287 | -- | |
288 | + | |
289 | This option is only available with the option:--userspace option and | |
290 | without the option:--overwrite option. | |
291 | ||
b4867b3b PP |
292 | One of: |
293 | ||
294 | option:--discard:: | |
295 | Discard events when sub-buffers are full (default). | |
296 | ||
297 | option:--overwrite:: | |
298 | Flight recorder mode: always keep a fixed amount of the latest | |
299 | data. | |
300 | ||
301 | ||
302 | Sub-buffers | |
303 | ~~~~~~~~~~~ | |
304 | option:--num-subbuf='COUNT':: | |
305 | Use 'COUNT' sub-buffers. Rounded up to the next power of two. | |
306 | + | |
307 | Default values: | |
308 | + | |
c93eadad PP |
309 | * option:--userspace and option:--buffers-uid options: |
310 | {default_ust_uid_channel_subbuf_num} | |
311 | * option:--userspace and option:--buffers-pid options: | |
312 | {default_ust_pid_channel_subbuf_num} | |
313 | * option:--kernel option: {default_kernel_channel_subbuf_num} | |
314 | * `metadata` channel: {default_metadata_subbuf_num} | |
b4867b3b | 315 | |
55d7bb02 PP |
316 | option:--output='TYPE':: |
317 | Set channel's output type to 'TYPE'. | |
318 | + | |
319 | Available types: `mmap` (always available) and `splice` (only available | |
320 | with the option:--kernel option). | |
321 | + | |
322 | Default values: | |
323 | + | |
324 | * option:--userspace and option:--buffers-uid options: `mmap` | |
325 | * option:--userspace and option:--buffers-pid options: `mmap` | |
326 | * option:--kernel option: `splice` | |
327 | * `metadata` channel: `mmap` | |
328 | ||
b4867b3b PP |
329 | option:--subbuf-size='SIZE':: |
330 | Set the individual size of sub-buffers to 'SIZE' bytes. | |
331 | The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported. | |
332 | Rounded up to the next power of two. | |
333 | + | |
334 | The minimum sub-buffer size, for each tracer, is the maximum value | |
335 | between the default below and the system's page size. The following | |
336 | command shows the current system's page size: `getconf PAGE_SIZE`. | |
337 | + | |
338 | Default values: | |
339 | + | |
c93eadad PP |
340 | * option:--userspace and option:--buffers-uid options: |
341 | {default_ust_uid_channel_subbuf_size} | |
342 | * option:--userspace and option:--buffers-pid options: | |
343 | {default_ust_pid_channel_subbuf_size} | |
344 | * option:--kernel option: {default_kernel_channel_subbuf_size} | |
345 | * `metadata` channel: {default_metadata_subbuf_size} | |
b4867b3b | 346 | |
b4867b3b PP |
347 | |
348 | Buffering scheme | |
349 | ~~~~~~~~~~~~~~~~ | |
350 | One of: | |
351 | ||
352 | option:--buffers-global:: | |
353 | Use shared sub-buffers for the whole system (only available with the | |
354 | option:--kernel option). | |
355 | ||
356 | option:--buffers-pid:: | |
357 | Use different sub-buffers for each traced process (only available | |
358 | with the the option:--userspace option). This is the default | |
359 | buffering scheme for user space channels. | |
360 | ||
361 | option:--buffers-uid:: | |
362 | Use shared sub-buffers for all the processes of the user running | |
363 | the command (only available with the option:--userspace option). | |
364 | ||
365 | ||
366 | Trace files | |
367 | ~~~~~~~~~~~ | |
368 | option:--tracefile-count='COUNT':: | |
369 | Limit the number of trace files created by this channel to | |
c93eadad PP |
370 | 'COUNT'. 0 means unlimited. Default: |
371 | {default_channel_tracefile_count}. | |
b4867b3b PP |
372 | + |
373 | Use this option in conjunction with the option:--tracefile-size option. | |
374 | + | |
375 | The file count within a stream is appended to each created trace | |
376 | file. If 'COUNT' files are created and more events need to be recorded, | |
377 | the first trace file of the stream is cleared and used again. | |
378 | ||
379 | option:--tracefile-size='SIZE':: | |
380 | Set the maximum size of each trace file written by | |
381 | this channel within a stream to 'SIZE' bytes. 0 means unlimited. | |
c93eadad | 382 | Default: {default_channel_tracefile_size}. |
b4867b3b PP |
383 | + |
384 | Note: traces generated with this option may inaccurately report | |
385 | discarded events as of CTF 1.8. | |
386 | ||
387 | ||
388 | Timers | |
389 | ~~~~~~ | |
961df0d0 PP |
390 | option:--monitor-timer:: |
391 | Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a | |
392 | disabled monitor timer. | |
393 | + | |
394 | Default values: | |
395 | + | |
396 | * option:--userspace and option:--buffers-uid options: | |
397 | {default_ust_uid_channel_monitor_timer} | |
398 | * option:--userspace and option:--buffers-pid options: | |
399 | {default_ust_pid_channel_monitor_timer} | |
400 | * option:--kernel option: {default_kernel_channel_monitor_timer} | |
401 | ||
b4867b3b PP |
402 | option:--read-timer:: |
403 | Set the channel's read timer's period to 'PERIODUS' µs. 0 means a | |
404 | disabled read timer. | |
405 | + | |
406 | Default values: | |
407 | + | |
c93eadad PP |
408 | * option:--userspace and option:--buffers-uid options: |
409 | {default_ust_uid_channel_read_timer} | |
410 | * option:--userspace and option:--buffers-pid options: | |
411 | {default_ust_pid_channel_read_timer} | |
412 | * option:--kernel option: {default_kernel_channel_read_timer} | |
413 | * `metadata` channel: {default_metadata_read_timer} | |
b4867b3b PP |
414 | |
415 | option:--switch-timer='PERIODUS':: | |
416 | Set the channel's switch timer's period to 'PERIODUS' µs. 0 means | |
c93eadad PP |
417 | a disabled switch timer. |
418 | + | |
419 | Default values: | |
420 | + | |
421 | * option:--userspace and option:--buffers-uid options: | |
422 | {default_ust_uid_channel_switch_timer} | |
423 | * option:--userspace and option:--buffers-pid options: | |
424 | {default_ust_pid_channel_switch_timer} | |
425 | * option:--kernel option: {default_kernel_channel_switch_timer} | |
426 | * `metadata` channel: {default_metadata_switch_timer} | |
b4867b3b PP |
427 | |
428 | ||
429 | include::common-cmd-help-options.txt[] | |
430 | ||
431 | ||
1076f2b7 PP |
432 | [[limitations]] |
433 | LIMITATIONS | |
434 | ----------- | |
435 | As of this version of LTTng, it is not possible to perform the following | |
436 | actions with the `lttng enable-channel` command: | |
437 | ||
438 | * Reconfigure a channel once it is created. | |
439 | * Re-enable a disabled channel once its tracing session has been active | |
440 | at least once. | |
441 | * Create a channel once its tracing session has been active | |
442 | at least once. | |
443 | * Create a user space channel with a given buffering scheme | |
444 | (option:--buffers-uid or option:--buffers-pid options) and create | |
445 | a second user space channel with a different buffering scheme in the | |
446 | same tracing session. | |
447 | ||
448 | ||
b4867b3b PP |
449 | include::common-cmd-footer.txt[] |
450 | ||
451 | ||
452 | SEE ALSO | |
453 | -------- | |
7c1a4458 | 454 | man:lttng-disable-channel(1), |
491d1539 MD |
455 | man:lttng(1), |
456 | man:lttng-ust(3) |