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