1 lttng-enable-channel(1)
2 =======================
7 lttng-enable-channel - Create or enable LTTng channels
12 Create a Linux kernel channel:
15 *lttng* ['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* ['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* ['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 linklttng: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 linklttng: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 linklttng: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 linklttng:lttng-disable-channel(1). Channels of a given session can be
65 listed using linklttng:lttng-list(1).
67 As of this version of LTTng, it is not possible to:
69 * Reconfigure a channel once it is created.
70 * Re-enable a disabled channel once its tracing session has been active
72 * Create a channel once its tracing session has been active
74 * Create a user space channel with a given buffering scheme
75 (option:--buffers-uid or option:--buffers-pid options) and create
76 a second user space channel with a different buffering scheme in the
82 LTTng tracers are non-blocking: when no empty sub-buffer exists,
83 losing events is acceptable when the alternative would be to cause
84 substantial delays in the instrumented application's execution.
86 LTTng privileges performance over integrity, aiming at perturbing the
87 traced system as little as possible in order to make tracing of subtle
88 race conditions and rare interrupt cascades possible.
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:
95 Drop the newest events until a sub-buffer is released.
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.
103 Which mechanism to choose depends on the context: prioritize the newest
104 or the oldest events in the ring buffer?
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.
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
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).
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
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):
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
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.
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.
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.
159 Switch and read timers
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.
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.
168 By default, a notification mechanism is used to signal a full sub-buffer
169 so that it can be consumed. When such notifications must be avoided,
170 for example in real-time applications, the channel's read timer can be
171 used instead. When the read timer fires, sub-buffers are checked for
172 consumption when they are full.
177 In the user space tracing domain, two buffering schemes are available
178 when creating a channel:
180 Per-process buffering (option:--buffers-pid option)::
181 Keep one ring buffer per process.
183 Per-user buffering (option:--buffers-uid option)::
184 Keep one ring buffer for all the processes of a single user.
186 The per-process buffering scheme consumes more memory than the per-user
187 option if more than one process is instrumented for LTTng-UST.
188 However, per-process buffering ensures that one process having a high
189 event throughput won't fill all the shared sub-buffers, only its own.
191 The Linux kernel tracing domain only has one available buffering scheme
192 which is to use a single ring buffer for the whole system
193 (option:--buffers-global option).
196 Trace files limit and size
197 ~~~~~~~~~~~~~~~~~~~~~~~~~~
198 By default, trace files can grow as large as needed. The maximum size
199 of each trace file written by a channel can be set on creation using the
200 option:--tracefile-size option. When such a trace file's size reaches
201 the channel's fixed maximum size, another trace file is created to hold
202 the next recorded events. A file count is appended to each trace file
205 If the option:--tracefile-size option is used, the maximum number of
206 created trace files is unlimited. To limit them, the
207 option:--tracefile-count option can be used. This option is always used
208 in conjunction with the option:--tracefile-size option.
210 For example, consider this command:
212 -----------------------------------------------------
213 lttng enable-channel --kernel --tracefile-size=4096 \
214 --tracefile-count=32 my-channel
215 -----------------------------------------------------
217 Here, for each stream, the maximum size of each trace file is
218 4 kiB and there can be a maximum of 32 different files. When there is
219 no space left in the last file, _trace file rotation_ happens: the first
220 file is cleared and new sub-buffers containing events are written there.
223 include::common-cmd-options-head.txt[]
230 option:-k, option:--kernel::
231 Enable channel in the Linux kernel domain.
233 option:-u, option:--userspace::
234 Enable channel in the user space domain.
239 option:-s, option:--session='SESSION'::
240 Create or enable channel in the tracing session named 'SESSION'
241 instead of the current tracing session.
249 Discard events when sub-buffers are full (default).
252 Flight recorder mode: always keep a fixed amount of the latest
258 option:--num-subbuf='COUNT'::
259 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
263 * `metadata` channel: 2
266 option:--subbuf-size='SIZE'::
267 Set the individual size of sub-buffers to 'SIZE' bytes.
268 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
269 Rounded up to the next power of two.
271 The minimum sub-buffer size, for each tracer, is the maximum value
272 between the default below and the system's page size. The following
273 command shows the current system's page size: `getconf PAGE_SIZE`.
277 * option:--userspace and option:--buffers-uid options: `128k`
278 * option:--userspace and option:--buffers-pid options: `4k`
279 * option:--kernel option: `256k`
280 * `metadata` channel: `4k`
282 option:--output='TYPE'::
283 Set channel's output type to 'TYPE'.
285 Available types: `mmap` (always available) and `splice` (only available
286 with the option:--kernel option).
290 * option:--userspace and option:--buffers-uid options: `mmap`
291 * option:--userspace and option:--buffers-pid options: `mmap`
292 * option:--kernel option: `splice`
293 * `metadata` channel: `mmap`
299 option:--buffers-global::
300 Use shared sub-buffers for the whole system (only available with the
301 option:--kernel option).
303 option:--buffers-pid::
304 Use different sub-buffers for each traced process (only available
305 with the the option:--userspace option). This is the default
306 buffering scheme for user space channels.
308 option:--buffers-uid::
309 Use shared sub-buffers for all the processes of the user running
310 the command (only available with the option:--userspace option).
315 option:--tracefile-count='COUNT'::
316 Limit the number of trace files created by this channel to
317 'COUNT'. 0 means unlimited. Default: 0.
319 Use this option in conjunction with the option:--tracefile-size option.
321 The file count within a stream is appended to each created trace
322 file. If 'COUNT' files are created and more events need to be recorded,
323 the first trace file of the stream is cleared and used again.
325 option:--tracefile-size='SIZE'::
326 Set the maximum size of each trace file written by
327 this channel within a stream to 'SIZE' bytes. 0 means unlimited.
330 Note: traces generated with this option may inaccurately report
331 discarded events as of CTF 1.8.
336 option:--read-timer::
337 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
342 * option:--userspace and option:--buffers-uid options: 0
343 * option:--userspace and option:--buffers-pid options: 0
344 * option:--kernel option: 200000
345 * `metadata` channel: 0
347 option:--switch-timer='PERIODUS'::
348 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
349 a disabled switch timer. Default: 0.
352 include::common-cmd-help-options.txt[]
355 include::common-cmd-footer.txt[]
360 linklttng:lttng-disable-channel(1),