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:
213 -----------------------------------------------------
214 lttng enable-channel --kernel --tracefile-size=4096 \
215 --tracefile-count=32 my-channel
216 -----------------------------------------------------
218 Here, for each stream, the maximum size of each trace file is
219 4 kiB and there can be a maximum of 32 different files. When there is
220 no space left in the last file, _trace file rotation_ happens: the first
221 file is cleared and new sub-buffers containing events are written there.
224 include::common-cmd-options-head.txt[]
231 option:-k, option:--kernel::
232 Enable channel in the Linux kernel domain.
234 option:-u, option:--userspace::
235 Enable channel in the user space domain.
240 option:-s, option:--session='SESSION'::
241 Create or enable channel in the tracing session named 'SESSION'
242 instead of the current tracing session.
250 Discard events when sub-buffers are full (default).
253 Flight recorder mode: always keep a fixed amount of the latest
259 option:--num-subbuf='COUNT'::
260 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
264 * `metadata` channel: 2
267 option:--subbuf-size='SIZE'::
268 Set the individual size of sub-buffers to 'SIZE' bytes.
269 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
270 Rounded up to the next power of two.
272 The minimum sub-buffer size, for each tracer, is the maximum value
273 between the default below and the system's page size. The following
274 command shows the current system's page size: `getconf PAGE_SIZE`.
278 * option:--userspace and option:--buffers-uid options: `128k`
279 * option:--userspace and option:--buffers-pid options: `4k`
280 * option:--kernel option: `256k`
281 * `metadata` channel: `4k`
283 option:--output='TYPE'::
284 Set channel's output type to 'TYPE'.
286 Available types: `mmap` (always available) and `splice` (only available
287 with the option:--kernel option).
291 * option:--userspace and option:--buffers-uid options: `mmap`
292 * option:--userspace and option:--buffers-pid options: `mmap`
293 * option:--kernel option: `splice`
294 * `metadata` channel: `mmap`
300 option:--buffers-global::
301 Use shared sub-buffers for the whole system (only available with the
302 option:--kernel option).
304 option:--buffers-pid::
305 Use different sub-buffers for each traced process (only available
306 with the the option:--userspace option). This is the default
307 buffering scheme for user space channels.
309 option:--buffers-uid::
310 Use shared sub-buffers for all the processes of the user running
311 the command (only available with the option:--userspace option).
316 option:--tracefile-count='COUNT'::
317 Limit the number of trace files created by this channel to
318 'COUNT'. 0 means unlimited. Default: 0.
320 Use this option in conjunction with the option:--tracefile-size option.
322 The file count within a stream is appended to each created trace
323 file. If 'COUNT' files are created and more events need to be recorded,
324 the first trace file of the stream is cleared and used again.
326 option:--tracefile-size='SIZE'::
327 Set the maximum size of each trace file written by
328 this channel within a stream to 'SIZE' bytes. 0 means unlimited.
331 Note: traces generated with this option may inaccurately report
332 discarded events as of CTF 1.8.
337 option:--read-timer::
338 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
343 * option:--userspace and option:--buffers-uid options: 0
344 * option:--userspace and option:--buffers-pid options: 0
345 * option:--kernel option: 200000
346 * `metadata` channel: 0
348 option:--switch-timer='PERIODUS'::
349 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
350 a disabled switch timer. Default: 0.
353 include::common-cmd-help-options.txt[]
356 include::common-cmd-footer.txt[]
361 linklttng:lttng-disable-channel(1),