95e62e6f1ec069f0438033725433502ad173d2d9
[lttng-tools.git] / doc / man / lttng-enable-channel.1.txt
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]
15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--kernel
16 [option:--overwrite] [option:--output=(`mmap` | `splice`)]
17 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
18 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
19 [option:--monitor-timer='PERIODUS']
20 [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
21 [option:--session='SESSION'] 'CHANNEL'
22
23 Create a user space channel:
24
25 [verse]
26 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
27 [option:--overwrite | option:--blocking-timeout='TIMEOUTUS'] [option:--buffers-pid]
28 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
29 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
30 [option:--monitor-timer='PERIODUS']
31 [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
32 [option:--session='SESSION'] 'CHANNEL'
33
34 Enable existing channel(s):
35
36 [verse]
37 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
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,
47 rules, when created using man:lttng-enable-event(1), are always
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
56 Note that the man:lttng-enable-event(1) command can automatically
57 create default channels when no channel exist.
58
59 A channel is always contained in a tracing session
60 (see man:lttng-create(1) for creating a tracing session). The
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
66 man:lttng-disable-channel(1). Channels of a given session can be
67 listed using man:lttng-list(1).
68
69 See the <<limitations,LIMITATIONS>> section below for a list of
70 limitations of this command to consider.
71
72
73 Event loss modes
74 ~~~~~~~~~~~~~~~~
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.
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
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
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
158 Switch timer
159 ~~~~~~~~~~~~
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
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.
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
236 [role="term"]
237 ----
238 $ lttng enable-channel --kernel --tracefile-size=4096 \
239 --tracefile-count=32 my-channel
240 ----
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 LTTng does not guarantee that you can view the trace of an active
248 tracing session (before you run the man:lttng-stop(1) command), even
249 with multiple trace files, because LTTng could overwrite them at any
250 moment, or some of them could be incomplete. You can archive a
251 tracing session's current trace chunk while the tracing session is
252 active to obtain an unmanaged and self-contained LTTng trace: see
253 man:lttng-rotate(1) and man:lttng-enable-rotation(1).
254
255
256 include::common-cmd-options-head.txt[]
257
258
259 Domain
260 ~~~~~~
261 One of:
262
263 option:-k, option:--kernel::
264 Enable channel in the Linux kernel domain.
265
266 option:-u, option:--userspace::
267 Enable channel in the user space domain.
268
269
270 Target
271 ~~~~~~
272 option:-s 'SESSION', option:--session='SESSION'::
273 Create or enable channel in the tracing session named 'SESSION'
274 instead of the current tracing session.
275
276
277 Event loss mode
278 ~~~~~~~~~~~~~~~
279 option:--blocking-timeout='TIMEOUTUS'::
280 Set the channel's blocking timeout value to 'TIMEOUTUS' µs for
281 instrumented applications executed with a set
282 `LTTNG_UST_ALLOW_BLOCKING` environment variable:
283 +
284 --
285 0 (default)::
286 Do not block (non-blocking mode).
287
288 `inf`::
289 Block forever until room is available in the sub-buffer to write the
290 event record.
291
292 __n__, a positive value::
293 Wait for at most __n__ µs when trying to write into a sub-buffer.
294 After __n__ µs, discard the event record.
295 --
296 +
297 This option is only available with the option:--userspace option and
298 without the option:--overwrite option.
299
300 One of:
301
302 option:--discard::
303 Discard events when sub-buffers are full (default).
304
305 option:--overwrite::
306 Flight recorder mode: always keep a fixed amount of the latest
307 data.
308
309
310 Sub-buffers
311 ~~~~~~~~~~~
312 option:--num-subbuf='COUNT'::
313 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
314 +
315 Default values:
316 +
317 * option:--userspace and option:--buffers-uid options:
318 {default_ust_uid_channel_subbuf_num}
319 * option:--userspace and option:--buffers-pid options:
320 {default_ust_pid_channel_subbuf_num}
321 * option:--kernel option: {default_kernel_channel_subbuf_num}
322 * `metadata` channel: {default_metadata_subbuf_num}
323
324 option:--output='TYPE'::
325 Set channel's output type to 'TYPE'.
326 +
327 Available types: `mmap` (always available) and `splice` (only available
328 with the option:--kernel option).
329 +
330 Default values:
331 +
332 * option:--userspace and option:--buffers-uid options: `mmap`
333 * option:--userspace and option:--buffers-pid options: `mmap`
334 * option:--kernel option: `splice`
335 * `metadata` channel: `mmap`
336
337 option:--subbuf-size='SIZE'::
338 Set the individual size of sub-buffers to 'SIZE' bytes.
339 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
340 Rounded up to the next power of two.
341 +
342 The minimum sub-buffer size, for each tracer, is the maximum value
343 between the default below and the system's page size. The following
344 command shows the current system's page size: `getconf PAGE_SIZE`.
345 +
346 Default values:
347 +
348 * option:--userspace and option:--buffers-uid options:
349 {default_ust_uid_channel_subbuf_size}
350 * option:--userspace and option:--buffers-pid options:
351 {default_ust_pid_channel_subbuf_size}
352 * option:--kernel option: {default_kernel_channel_subbuf_size}
353 * `metadata` channel: {default_metadata_subbuf_size}
354
355
356 Buffering scheme
357 ~~~~~~~~~~~~~~~~
358 One of:
359
360 option:--buffers-global::
361 Use shared sub-buffers for the whole system (only available with the
362 option:--kernel option).
363
364 option:--buffers-pid::
365 Use different sub-buffers for each traced process (only available
366 with the the option:--userspace option). This is the default
367 buffering scheme for user space channels.
368
369 option:--buffers-uid::
370 Use shared sub-buffers for all the processes of the user running
371 the command (only available with the option:--userspace option).
372
373
374 Trace files
375 ~~~~~~~~~~~
376 option:--tracefile-count='COUNT'::
377 Limit the number of trace files created by this channel to
378 'COUNT'. 0 means unlimited. Default:
379 {default_channel_tracefile_count}.
380 +
381 Use this option in conjunction with the option:--tracefile-size option.
382 +
383 The file count within a stream is appended to each created trace
384 file. If 'COUNT' files are created and more events need to be recorded,
385 the first trace file of the stream is cleared and used again.
386
387 option:--tracefile-size='SIZE'::
388 Set the maximum size of each trace file written by
389 this channel within a stream to 'SIZE' bytes. 0 means unlimited.
390 Default: {default_channel_tracefile_size}.
391 +
392 Note: traces generated with this option may inaccurately report
393 discarded events as of CTF 1.8.
394
395
396 Timers
397 ~~~~~~
398 option:--monitor-timer::
399 Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
400 disabled monitor timer.
401 +
402 Default values:
403 +
404 * option:--userspace and option:--buffers-uid options:
405 {default_ust_uid_channel_monitor_timer}
406 * option:--userspace and option:--buffers-pid options:
407 {default_ust_pid_channel_monitor_timer}
408 * option:--kernel option: {default_kernel_channel_monitor_timer}
409
410 option:--read-timer::
411 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
412 disabled read timer.
413 +
414 Default values:
415 +
416 * option:--userspace and option:--buffers-uid options:
417 {default_ust_uid_channel_read_timer}
418 * option:--userspace and option:--buffers-pid options:
419 {default_ust_pid_channel_read_timer}
420 * option:--kernel option: {default_kernel_channel_read_timer}
421 * `metadata` channel: {default_metadata_read_timer}
422
423 option:--switch-timer='PERIODUS'::
424 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
425 a disabled switch timer.
426 +
427 Default values:
428 +
429 * option:--userspace and option:--buffers-uid options:
430 {default_ust_uid_channel_switch_timer}
431 * option:--userspace and option:--buffers-pid options:
432 {default_ust_pid_channel_switch_timer}
433 * option:--kernel option: {default_kernel_channel_switch_timer}
434 * `metadata` channel: {default_metadata_switch_timer}
435
436
437 include::common-cmd-help-options.txt[]
438
439
440 [[limitations]]
441 LIMITATIONS
442 -----------
443 As of this version of LTTng, it is not possible to perform the following
444 actions with the `lttng enable-channel` command:
445
446 * Reconfigure a channel once it is created.
447 * Re-enable a disabled channel once its tracing session has been active
448 at least once.
449 * Create a channel once its tracing session has been active
450 at least once.
451 * Create a user space channel with a given buffering scheme
452 (option:--buffers-uid or option:--buffers-pid options) and create
453 a second user space channel with a different buffering scheme in the
454 same tracing session.
455
456
457 include::common-cmd-footer.txt[]
458
459
460 SEE ALSO
461 --------
462 man:lttng-disable-channel(1),
463 man:lttng(1),
464 man:lttng-ust(3)
This page took 0.039466 seconds and 5 git commands to generate.