1 lttng-enable-channel(1)
2 =======================
7 lttng-enable-channel - Create or enable LTTng channels
12 Create a Linux kernel channel:
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'
23 Create a user space channel:
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'
34 Enable existing channel(s):
37 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
38 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
43 The `lttng enable-channel` command can create a new channel, or enable
44 one or more existing and disabled ones.
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.
52 When 'CHANNEL' does not name an existing channel, a channel named
53 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
56 Note that the man:lttng-enable-event(1) command can automatically
57 create default channels when no channel exist.
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.
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).
69 See the <<limitations,LIMITATIONS>> section below for a list of
70 limitations of this command to consider.
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.
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.
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.
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:
94 Drop the newest events until a sub-buffer is released.
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.
102 Which mechanism to choose depends on the context: prioritize the newest
103 or the oldest events in the ring buffer?
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.
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
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).
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
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):
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
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.
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.
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.
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.
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.
167 Use the option:--switch-timer option to control the switch timer's
168 period of the channel to create.
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.
179 Use the option:--read-timer option to control the read timer's period of
180 the channel to create.
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.
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.
195 Use the option:--monitor-timer option to control the monitor timer's
196 period of the channel to create.
201 In the user space tracing domain, two buffering schemes are available
202 when creating a channel:
204 Per-process buffering (option:--buffers-pid option)::
205 Keep one ring buffer per process.
207 Per-user buffering (option:--buffers-uid option)::
208 Keep one ring buffer for all the processes of a single user.
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.
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).
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
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.
234 For example, consider this command:
238 $ lttng enable-channel --kernel --tracefile-size=4096 \
239 --tracefile-count=32 my-channel
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.
248 include::common-cmd-options-head.txt[]
255 option:-k, option:--kernel::
256 Enable channel in the Linux kernel domain.
258 option:-u, option:--userspace::
259 Enable channel in the user space domain.
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.
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:
278 Do not block (non-blocking mode).
281 Block forever until room is available in the sub-buffer to write the
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.
289 This option is only available with the option:--userspace option and
290 without the option:--overwrite option.
295 Discard events when sub-buffers are full (default).
298 Flight recorder mode: always keep a fixed amount of the latest
304 option:--num-subbuf='COUNT'::
305 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
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}
316 option:--output='TYPE'::
317 Set channel's output type to 'TYPE'.
319 Available types: `mmap` (always available) and `splice` (only available
320 with the option:--kernel option).
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`
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.
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`.
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}
352 option:--buffers-global::
353 Use shared sub-buffers for the whole system (only available with the
354 option:--kernel option).
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.
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).
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}.
373 Use this option in conjunction with the option:--tracefile-size option.
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.
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}.
384 Note: traces generated with this option may inaccurately report
385 discarded events as of CTF 1.8.
390 option:--monitor-timer::
391 Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
392 disabled monitor timer.
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}
402 option:--read-timer::
403 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
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}
415 option:--switch-timer='PERIODUS'::
416 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
417 a disabled switch timer.
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}
429 include::common-cmd-help-options.txt[]
435 As of this version of LTTng, it is not possible to perform the following
436 actions with the `lttng enable-channel` command:
438 * Reconfigure a channel once it is created.
439 * Re-enable a disabled channel once its tracing session has been active
441 * Create a channel once its tracing session has been active
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.
449 include::common-cmd-footer.txt[]
454 man:lttng-disable-channel(1),