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:--discard | 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:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
20 [option:--session='SESSION'] 'CHANNEL'
22 Create a user space channel:
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
26 [option:--discard | option:--overwrite] [option:--buffers-pid]
27 [option:--subbuf-size='SIZE'] [option:--num-subbuf='COUNT']
28 [option:--switch-timer='PERIODUS'] [option:--read-timer='PERIODUS']
29 [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
30 [option:--session='SESSION'] 'CHANNEL'
32 Enable existing channel(s):
35 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
36 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
41 The `lttng enable-channel` command can create a new channel, or enable
42 one or more existing and disabled ones.
44 A channel is the owner of sub-buffers holding recorded events. Event,
45 rules, when created using man:lttng-enable-event(1), are always
46 assigned to a channel. When creating a new channel, many parameters
47 related to those sub-buffers can be fine-tuned. They are described in
48 the subsections below.
50 When 'CHANNEL' does not name an existing channel, a channel named
51 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
54 Note that the man:lttng-enable-event(1) command can automatically
55 create default channels when no channel exist.
57 A channel is always contained in a tracing session
58 (see man:lttng-create(1) for creating a tracing session). The
59 session in which a channel is created using `lttng enable-channel` can
60 be specified using the option:--session option. If the option:--session
61 option is omitted, the current tracing session is targeted.
63 Existing enabled channels can be disabled using
64 man:lttng-disable-channel(1). Channels of a given session can be
65 listed using man:lttng-list(1).
67 See the <<limitations,LIMITATIONS>> section below for a list of
68 limitations of this command to consider.
73 LTTng tracers are non-blocking: when no empty sub-buffer exists,
74 losing events is acceptable when the alternative would be to cause
75 substantial delays in the instrumented application's execution.
77 LTTng privileges performance over integrity, aiming at perturbing the
78 traced system as little as possible in order to make tracing of subtle
79 race conditions and rare interrupt cascades possible.
81 When it comes to losing events because no empty sub-buffer is available,
82 the channel's event loss mode, specified by one of the option:--discard
83 and option:--overwrite options, determines what to do amongst:
86 Drop the newest events until a sub-buffer is released.
89 Clear the sub-buffer containing the oldest recorded events and start
90 recording the newest events there. This mode is sometimes called
91 _flight recorder mode_ because it behaves like a flight recorder:
92 always keep a fixed amount of the latest data.
94 Which mechanism to choose depends on the context: prioritize the newest
95 or the oldest events in the ring buffer?
97 Beware that, in overwrite mode (option:--overwrite option), a whole
98 sub-buffer is abandoned as soon as a new event doesn't find an empty
99 sub-buffer, whereas in discard mode (option:--discard option), only the
100 event that doesn't fit is discarded.
102 Also note that a count of lost events is incremented and saved in the
103 trace itself when an event is lost in discard mode, whereas no
104 information is kept when a sub-buffer gets overwritten before being
107 The probability of losing events, if it is experience in a given
108 context, can be reduced by fine-tuning the sub-buffers count and size
109 (see next subsection).
112 Sub-buffers count and size
113 ~~~~~~~~~~~~~~~~~~~~~~~~~~
114 The option:--num-subbuf and option:--subbuf-size options respectively
115 set the number of sub-buffers and their individual size when creating
118 Note that there is a noticeable tracer's CPU overhead introduced when
119 switching sub-buffers (marking a full one as consumable and switching
120 to an empty one for the following events to be recorded). Knowing this,
121 the following list presents a few practical situations along with how
122 to configure sub-buffers for them when creating a channel in overwrite
123 mode (option:--overwrite option):
125 High event throughput::
126 In general, prefer bigger sub-buffers to lower the risk of losing
127 events. Having bigger sub-buffers also ensures a lower sub-buffer
128 switching frequency. The number of sub-buffers is only meaningful
129 if the channel is enabled in overwrite mode: in this case, if a
130 sub-buffer overwrite happens, the other sub-buffers
133 Low event throughput::
134 In general, prefer smaller sub-buffers since the risk of losing
135 events is already low. Since events happen less frequently, the
136 sub-buffer switching frequency should remain low and thus the
137 tracer's overhead should not be a problem.
140 If the target system has a low memory limit, prefer fewer first,
141 then smaller sub-buffers. Even if the system is limited in memory,
142 it is recommended to keep the sub-buffers as big as possible to
143 avoid a high sub-buffer switching frequency.
145 In discard mode (option:--discard option), the sub-buffers count
146 parameter is pointless: using two sub-buffers and setting their size
147 according to the requirements of the context is fine.
150 Switch and read timers
151 ~~~~~~~~~~~~~~~~~~~~~~
152 When a channel's switch timer fires, a sub-buffer switch happens. This
153 timer may be used to ensure that event data is consumed and committed
154 to trace files periodically in case of a low event throughput.
156 It's also convenient when big sub-buffers are used to cope with sporadic
157 high event throughput, even if the throughput is normally lower.
159 By default, a notification mechanism is used to signal a full sub-buffer
160 so that it can be consumed. When such notifications must be avoided,
161 for example in real-time applications, the channel's read timer can be
162 used instead. When the read timer fires, sub-buffers are checked for
163 consumption when they are full.
168 In the user space tracing domain, two buffering schemes are available
169 when creating a channel:
171 Per-process buffering (option:--buffers-pid option)::
172 Keep one ring buffer per process.
174 Per-user buffering (option:--buffers-uid option)::
175 Keep one ring buffer for all the processes of a single user.
177 The per-process buffering scheme consumes more memory than the per-user
178 option if more than one process is instrumented for LTTng-UST.
179 However, per-process buffering ensures that one process having a high
180 event throughput won't fill all the shared sub-buffers, only its own.
182 The Linux kernel tracing domain only has one available buffering scheme
183 which is to use a single ring buffer for the whole system
184 (option:--buffers-global option).
187 Trace files limit and size
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~
189 By default, trace files can grow as large as needed. The maximum size
190 of each trace file written by a channel can be set on creation using the
191 option:--tracefile-size option. When such a trace file's size reaches
192 the channel's fixed maximum size, another trace file is created to hold
193 the next recorded events. A file count is appended to each trace file
196 If the option:--tracefile-size option is used, the maximum number of
197 created trace files is unlimited. To limit them, the
198 option:--tracefile-count option can be used. This option is always used
199 in conjunction with the option:--tracefile-size option.
201 For example, consider this command:
204 -----------------------------------------------------
205 lttng enable-channel --kernel --tracefile-size=4096 \
206 --tracefile-count=32 my-channel
207 -----------------------------------------------------
209 Here, for each stream, the maximum size of each trace file is
210 4 kiB and there can be a maximum of 32 different files. When there is
211 no space left in the last file, _trace file rotation_ happens: the first
212 file is cleared and new sub-buffers containing events are written there.
215 include::common-cmd-options-head.txt[]
222 option:-k, option:--kernel::
223 Enable channel in the Linux kernel domain.
225 option:-u, option:--userspace::
226 Enable channel in the user space domain.
231 option:-s, option:--session='SESSION'::
232 Create or enable channel in the tracing session named 'SESSION'
233 instead of the current tracing session.
241 Discard events when sub-buffers are full (default).
244 Flight recorder mode: always keep a fixed amount of the latest
250 option:--num-subbuf='COUNT'::
251 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
255 * `metadata` channel: 2
258 option:--subbuf-size='SIZE'::
259 Set the individual size of sub-buffers to 'SIZE' bytes.
260 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
261 Rounded up to the next power of two.
263 The minimum sub-buffer size, for each tracer, is the maximum value
264 between the default below and the system's page size. The following
265 command shows the current system's page size: `getconf PAGE_SIZE`.
269 * option:--userspace and option:--buffers-uid options: `128k`
270 * option:--userspace and option:--buffers-pid options: `4k`
271 * option:--kernel option: `256k`
272 * `metadata` channel: `4k`
274 option:--output='TYPE'::
275 Set channel's output type to 'TYPE'.
277 Available types: `mmap` (always available) and `splice` (only available
278 with the option:--kernel option).
282 * option:--userspace and option:--buffers-uid options: `mmap`
283 * option:--userspace and option:--buffers-pid options: `mmap`
284 * option:--kernel option: `splice`
285 * `metadata` channel: `mmap`
291 option:--buffers-global::
292 Use shared sub-buffers for the whole system (only available with the
293 option:--kernel option).
295 option:--buffers-pid::
296 Use different sub-buffers for each traced process (only available
297 with the the option:--userspace option). This is the default
298 buffering scheme for user space channels.
300 option:--buffers-uid::
301 Use shared sub-buffers for all the processes of the user running
302 the command (only available with the option:--userspace option).
307 option:--tracefile-count='COUNT'::
308 Limit the number of trace files created by this channel to
309 'COUNT'. 0 means unlimited. Default: 0.
311 Use this option in conjunction with the option:--tracefile-size option.
313 The file count within a stream is appended to each created trace
314 file. If 'COUNT' files are created and more events need to be recorded,
315 the first trace file of the stream is cleared and used again.
317 option:--tracefile-size='SIZE'::
318 Set the maximum size of each trace file written by
319 this channel within a stream to 'SIZE' bytes. 0 means unlimited.
322 Note: traces generated with this option may inaccurately report
323 discarded events as of CTF 1.8.
328 option:--read-timer::
329 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
334 * option:--userspace and option:--buffers-uid options: 0
335 * option:--userspace and option:--buffers-pid options: 0
336 * option:--kernel option: 200000
337 * `metadata` channel: 0
339 option:--switch-timer='PERIODUS'::
340 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
341 a disabled switch timer. Default: 0.
344 include::common-cmd-help-options.txt[]
350 As of this version of LTTng, it is not possible to perform the following
351 actions with the `lttng enable-channel` command:
353 * Reconfigure a channel once it is created.
354 * Re-enable a disabled channel once its tracing session has been active
356 * Create a channel once its tracing session has been active
358 * Create a user space channel with a given buffering scheme
359 (option:--buffers-uid or option:--buffers-pid options) and create
360 a second user space channel with a different buffering scheme in the
361 same tracing session.
364 include::common-cmd-footer.txt[]
369 man:lttng-disable-channel(1),