Check for pending notification on notification channel activity
[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
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 ~~~~~~
264 option:-s 'SESSION', option:--session='SESSION'::
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 ~~~~~~~~~~~~~~~
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
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 +
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}
315
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
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 +
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}
346
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
370 'COUNT'. 0 means unlimited. Default:
371 {default_channel_tracefile_count}.
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.
382 Default: {default_channel_tracefile_size}.
383 +
384 Note: traces generated with this option may inaccurately report
385 discarded events as of CTF 1.8.
386
387
388 Timers
389 ~~~~~~
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
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 +
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}
414
415 option:--switch-timer='PERIODUS'::
416 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
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}
427
428
429 include::common-cmd-help-options.txt[]
430
431
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
449 include::common-cmd-footer.txt[]
450
451
452 SEE ALSO
453 --------
454 man:lttng-disable-channel(1),
455 man:lttng(1),
456 man:lttng-ust(3)
This page took 0.039679 seconds and 5 git commands to generate.