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:--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'] [option:--blocking-timeout='TIMEOUTUS']
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: when no empty sub-buffer exists,
76 losing events is acceptable when the alternative would be to cause
77 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 When it comes to losing events because no empty sub-buffer is available,
84 the channel's event loss mode, specified by one of the option:--discard
85 and option:--overwrite options, determines what to do amongst:
88 Drop the newest events until a sub-buffer is released.
91 Clear the sub-buffer containing the oldest recorded events and start
92 recording the newest events there. This mode is sometimes called
93 _flight recorder mode_ because it behaves like a flight recorder:
94 always keep a fixed amount of the latest data.
96 Which mechanism to choose depends on the context: prioritize the newest
97 or the oldest events in the ring buffer?
99 Beware that, in overwrite mode (option:--overwrite option), a whole
100 sub-buffer is abandoned as soon as a new event doesn't find an empty
101 sub-buffer, whereas in discard mode (option:--discard option), only the
102 event that doesn't fit is discarded.
104 Also note that a count of lost events is incremented and saved in the
105 trace itself when an event is lost in discard mode, whereas no
106 information is kept when a sub-buffer gets overwritten before being
109 The probability of losing events, if it is experience in a given
110 context, can be reduced by fine-tuning the sub-buffers count and size
111 (see next subsection).
114 Sub-buffers count and size
115 ~~~~~~~~~~~~~~~~~~~~~~~~~~
116 The option:--num-subbuf and option:--subbuf-size options respectively
117 set the number of sub-buffers and their individual size when creating
120 Note that there is a noticeable tracer's CPU overhead introduced when
121 switching sub-buffers (marking a full one as consumable and switching
122 to an empty one for the following events to be recorded). Knowing this,
123 the following list presents a few practical situations along with how
124 to configure sub-buffers for them when creating a channel in overwrite
125 mode (option:--overwrite option):
127 High event throughput::
128 In general, prefer bigger sub-buffers to lower the risk of losing
129 events. Having bigger sub-buffers also ensures a lower sub-buffer
130 switching frequency. The number of sub-buffers is only meaningful
131 if the channel is enabled in overwrite mode: in this case, if a
132 sub-buffer overwrite happens, the other sub-buffers
135 Low event throughput::
136 In general, prefer smaller sub-buffers since the risk of losing
137 events is already low. Since events happen less frequently, the
138 sub-buffer switching frequency should remain low and thus the
139 tracer's overhead should not be a problem.
142 If the target system has a low memory limit, prefer fewer first,
143 then smaller sub-buffers. Even if the system is limited in memory,
144 it is recommended to keep the sub-buffers as big as possible to
145 avoid a high sub-buffer switching frequency.
147 In discard mode (option:--discard option), the sub-buffers count
148 parameter is pointless: using two sub-buffers and setting their size
149 according to the requirements of the context is fine.
154 When a channel's switch timer fires, a sub-buffer switch happens. This
155 timer may be used to ensure that event data is consumed and committed
156 to trace files periodically in case of a low event throughput.
158 It's also convenient when big sub-buffers are used to cope with sporadic
159 high event throughput, even if the throughput is normally lower.
161 Use the option:--switch-timer option to control the switch timer's
162 period of the channel to create.
167 By default, an internal notification mechanism is used to signal a full
168 sub-buffer so that it can be consumed. When such notifications must be
169 avoided, for example in real-time applications, the channel's read timer
170 can be used instead. When the read timer fires, sub-buffers are checked
171 for consumption when they are full.
173 Use the option:--read-timer option to control the read timer's period of
174 the channel to create.
179 When a channel's monitor timer fires, its registered trigger conditions
180 are evaluated using the current values of its properties (for example,
181 the current usage of its sub-buffers). When a trigger condition is true,
182 LTTng executes its associated action. The only type of action currently
183 supported is to notify one or more user applications.
185 See the installed $$C/C++$$ headers in `lttng/action`,
186 `lttng/condition`, `lttng/notification`, and `lttng/trigger` to learn
187 more about application notifications and triggers.
189 Use the option:--monitor-timer option to control the monitor timer's
190 period of the channel to create.
195 In the user space tracing domain, two buffering schemes are available
196 when creating a channel:
198 Per-process buffering (option:--buffers-pid option)::
199 Keep one ring buffer per process.
201 Per-user buffering (option:--buffers-uid option)::
202 Keep one ring buffer for all the processes of a single user.
204 The per-process buffering scheme consumes more memory than the per-user
205 option if more than one process is instrumented for LTTng-UST.
206 However, per-process buffering ensures that one process having a high
207 event throughput won't fill all the shared sub-buffers, only its own.
209 The Linux kernel tracing domain only has one available buffering scheme
210 which is to use a single ring buffer for the whole system
211 (option:--buffers-global option).
214 Trace files limit and size
215 ~~~~~~~~~~~~~~~~~~~~~~~~~~
216 By default, trace files can grow as large as needed. The maximum size
217 of each trace file written by a channel can be set on creation using the
218 option:--tracefile-size option. When such a trace file's size reaches
219 the channel's fixed maximum size, another trace file is created to hold
220 the next recorded events. A file count is appended to each trace file
223 If the option:--tracefile-size option is used, the maximum number of
224 created trace files is unlimited. To limit them, the
225 option:--tracefile-count option can be used. This option is always used
226 in conjunction with the option:--tracefile-size option.
228 For example, consider this command:
232 $ lttng enable-channel --kernel --tracefile-size=4096 \
233 --tracefile-count=32 my-channel
236 Here, for each stream, the maximum size of each trace file is
237 4 kiB and there can be a maximum of 32 different files. When there is
238 no space left in the last file, _trace file rotation_ happens: the first
239 file is cleared and new sub-buffers containing events are written there.
242 include::common-cmd-options-head.txt[]
249 option:-k, option:--kernel::
250 Enable channel in the Linux kernel domain.
252 option:-u, option:--userspace::
253 Enable channel in the user space domain.
258 option:-s 'SESSION', option:--session='SESSION'::
259 Create or enable channel in the tracing session named 'SESSION'
260 instead of the current tracing session.
268 Discard events when sub-buffers are full (default).
271 Flight recorder mode: always keep a fixed amount of the latest
277 option:--num-subbuf='COUNT'::
278 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
282 * option:--userspace and option:--buffers-uid options:
283 {default_ust_uid_channel_subbuf_num}
284 * option:--userspace and option:--buffers-pid options:
285 {default_ust_pid_channel_subbuf_num}
286 * option:--kernel option: {default_kernel_channel_subbuf_num}
287 * `metadata` channel: {default_metadata_subbuf_num}
289 option:--output='TYPE'::
290 Set channel's output type to 'TYPE'.
292 Available types: `mmap` (always available) and `splice` (only available
293 with the option:--kernel option).
297 * option:--userspace and option:--buffers-uid options: `mmap`
298 * option:--userspace and option:--buffers-pid options: `mmap`
299 * option:--kernel option: `splice`
300 * `metadata` channel: `mmap`
302 option:--subbuf-size='SIZE'::
303 Set the individual size of sub-buffers to 'SIZE' bytes.
304 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
305 Rounded up to the next power of two.
307 The minimum sub-buffer size, for each tracer, is the maximum value
308 between the default below and the system's page size. The following
309 command shows the current system's page size: `getconf PAGE_SIZE`.
313 * option:--userspace and option:--buffers-uid options:
314 {default_ust_uid_channel_subbuf_size}
315 * option:--userspace and option:--buffers-pid options:
316 {default_ust_pid_channel_subbuf_size}
317 * option:--kernel option: {default_kernel_channel_subbuf_size}
318 * `metadata` channel: {default_metadata_subbuf_size}
325 option:--buffers-global::
326 Use shared sub-buffers for the whole system (only available with the
327 option:--kernel option).
329 option:--buffers-pid::
330 Use different sub-buffers for each traced process (only available
331 with the the option:--userspace option). This is the default
332 buffering scheme for user space channels.
334 option:--buffers-uid::
335 Use shared sub-buffers for all the processes of the user running
336 the command (only available with the option:--userspace option).
341 option:--tracefile-count='COUNT'::
342 Limit the number of trace files created by this channel to
343 'COUNT'. 0 means unlimited. Default:
344 {default_channel_tracefile_count}.
346 Use this option in conjunction with the option:--tracefile-size option.
348 The file count within a stream is appended to each created trace
349 file. If 'COUNT' files are created and more events need to be recorded,
350 the first trace file of the stream is cleared and used again.
352 option:--tracefile-size='SIZE'::
353 Set the maximum size of each trace file written by
354 this channel within a stream to 'SIZE' bytes. 0 means unlimited.
355 Default: {default_channel_tracefile_size}.
357 Note: traces generated with this option may inaccurately report
358 discarded events as of CTF 1.8.
363 option:--monitor-timer::
364 Set the channel's monitor timer's period to 'PERIODUS' µs. 0 means a
365 disabled monitor timer.
369 * option:--userspace and option:--buffers-uid options:
370 {default_ust_uid_channel_monitor_timer}
371 * option:--userspace and option:--buffers-pid options:
372 {default_ust_pid_channel_monitor_timer}
373 * option:--kernel option: {default_kernel_channel_monitor_timer}
375 option:--read-timer::
376 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
381 * option:--userspace and option:--buffers-uid options:
382 {default_ust_uid_channel_read_timer}
383 * option:--userspace and option:--buffers-pid options:
384 {default_ust_pid_channel_read_timer}
385 * option:--kernel option: {default_kernel_channel_read_timer}
386 * `metadata` channel: {default_metadata_read_timer}
388 option:--switch-timer='PERIODUS'::
389 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
390 a disabled switch timer.
394 * option:--userspace and option:--buffers-uid options:
395 {default_ust_uid_channel_switch_timer}
396 * option:--userspace and option:--buffers-pid options:
397 {default_ust_pid_channel_switch_timer}
398 * option:--kernel option: {default_kernel_channel_switch_timer}
399 * `metadata` channel: {default_metadata_switch_timer}
403 option:--blocking-timeout='TIMEOUTUS'::
404 Set the channel's blocking timeout value to 'TIMEOUTUS' µs
405 for applications executed with a set `LTTNG_UST_ALLOW_BLOCKING`
406 environment variable:
413 Block forever until room is available in the sub-buffer to write the
416 __n__, a positive value::
417 Wait for at most __n__ µs when trying to write into a sub-buffer.
421 include::common-cmd-help-options.txt[]
427 As of this version of LTTng, it is not possible to perform the following
428 actions with the `lttng enable-channel` command:
430 * Reconfigure a channel once it is created.
431 * Re-enable a disabled channel once its tracing session has been active
433 * Create a channel once its tracing session has been active
435 * Create a user space channel with a given buffering scheme
436 (option:--buffers-uid or option:--buffers-pid options) and create
437 a second user space channel with a different buffering scheme in the
438 same tracing session.
441 include::common-cmd-footer.txt[]
446 man:lttng-disable-channel(1),