bec0906428c5bfba6e9f91ab3e8f783cd96b472e
[lttng-tools.git] / doc / man / lttng-enable-channel.1.txt
1 lttng-enable-channel(1)
2 =======================
3
4
5 NAME
6 ----
7 lttng-enable-channel - Create or enable LTTng channels
8
9
10 SYNOPSIS
11 --------
12 Create a Linux kernel channel:
13
14 [verse]
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:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
20 [option:--session='SESSION'] 'CHANNEL'
21
22 Create a user space channel:
23
24 [verse]
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* option:--userspace
26 [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:--blocking-timeout='TIMEOUTUS']
30 [option:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
31 [option:--session='SESSION'] 'CHANNEL'
32
33 Enable existing channel(s):
34
35 [verse]
36 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
37 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
38
39
40 DESCRIPTION
41 -----------
42 The `lttng enable-channel` command can create a new channel, or enable
43 one or more existing and disabled ones.
44
45 A channel is the owner of sub-buffers holding recorded events. Event,
46 rules, when created using man:lttng-enable-event(1), are always
47 assigned to a channel. When creating a new channel, many parameters
48 related to those sub-buffers can be fine-tuned. They are described in
49 the subsections below.
50
51 When 'CHANNEL' does not name an existing channel, a channel named
52 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
53 is enabled.
54
55 Note that the man:lttng-enable-event(1) command can automatically
56 create default channels when no channel exist.
57
58 A channel is always contained in a tracing session
59 (see man:lttng-create(1) for creating a tracing session). The
60 session in which a channel is created using `lttng enable-channel` can
61 be specified using the option:--session option. If the option:--session
62 option is omitted, the current tracing session is targeted.
63
64 Existing enabled channels can be disabled using
65 man:lttng-disable-channel(1). Channels of a given session can be
66 listed using man:lttng-list(1).
67
68 See the <<limitations,LIMITATIONS>> section below for a list of
69 limitations of this command to consider.
70
71
72 Event loss modes
73 ~~~~~~~~~~~~~~~~
74 LTTng tracers are non-blocking: when no empty sub-buffer exists,
75 losing events is acceptable when the alternative would be to cause
76 substantial delays in the instrumented application's execution.
77
78 LTTng privileges performance over integrity, aiming at perturbing the
79 traced system as little as possible in order to make tracing of subtle
80 race conditions and rare interrupt cascades possible.
81
82 When it comes to losing events because no empty sub-buffer is available,
83 the channel's event loss mode, specified by one of the option:--discard
84 and option:--overwrite options, determines what to do amongst:
85
86 Discard::
87 Drop the newest events until a sub-buffer is released.
88
89 Overwrite::
90 Clear the sub-buffer containing the oldest recorded events and start
91 recording the newest events there. This mode is sometimes called
92 _flight recorder mode_ because it behaves like a flight recorder:
93 always keep a fixed amount of the latest data.
94
95 Which mechanism to choose depends on the context: prioritize the newest
96 or the oldest events in the ring buffer?
97
98 Beware that, in overwrite mode (option:--overwrite option), a whole
99 sub-buffer is abandoned as soon as a new event doesn't find an empty
100 sub-buffer, whereas in discard mode (option:--discard option), only the
101 event that doesn't fit is discarded.
102
103 Also note that a count of lost events is incremented and saved in the
104 trace itself when an event is lost in discard mode, whereas no
105 information is kept when a sub-buffer gets overwritten before being
106 committed.
107
108 The probability of losing events, if it is experience in a given
109 context, can be reduced by fine-tuning the sub-buffers count and size
110 (see next subsection).
111
112
113 Sub-buffers count and size
114 ~~~~~~~~~~~~~~~~~~~~~~~~~~
115 The option:--num-subbuf and option:--subbuf-size options respectively
116 set the number of sub-buffers and their individual size when creating
117 a new channel.
118
119 Note that there is a noticeable tracer's CPU overhead introduced when
120 switching sub-buffers (marking a full one as consumable and switching
121 to an empty one for the following events to be recorded). Knowing this,
122 the following list presents a few practical situations along with how
123 to configure sub-buffers for them when creating a channel in overwrite
124 mode (option:--overwrite option):
125
126 High event throughput::
127 In general, prefer bigger sub-buffers to lower the risk of losing
128 events. Having bigger sub-buffers also ensures a lower sub-buffer
129 switching frequency. The number of sub-buffers is only meaningful
130 if the channel is enabled in overwrite mode: in this case, if a
131 sub-buffer overwrite happens, the other sub-buffers
132 are left unaltered.
133
134 Low event throughput::
135 In general, prefer smaller sub-buffers since the risk of losing
136 events is already low. Since events happen less frequently, the
137 sub-buffer switching frequency should remain low and thus the
138 tracer's overhead should not be a problem.
139
140 Low memory system::
141 If the target system has a low memory limit, prefer fewer first,
142 then smaller sub-buffers. Even if the system is limited in memory,
143 it is recommended to keep the sub-buffers as big as possible to
144 avoid a high sub-buffer switching frequency.
145
146 In discard mode (option:--discard option), the sub-buffers count
147 parameter is pointless: using two sub-buffers and setting their size
148 according to the requirements of the context is fine.
149
150
151 Switch and read timers
152 ~~~~~~~~~~~~~~~~~~~~~~
153 When a channel's switch timer fires, a sub-buffer switch happens. This
154 timer may be used to ensure that event data is consumed and committed
155 to trace files periodically in case of a low event throughput.
156
157 It's also convenient when big sub-buffers are used to cope with sporadic
158 high event throughput, even if the throughput is normally lower.
159
160 By default, a notification mechanism is used to signal a full sub-buffer
161 so that it can be consumed. When such notifications must be avoided,
162 for example in real-time applications, the channel's read timer can be
163 used instead. When the read timer fires, sub-buffers are checked for
164 consumption when they are full.
165
166
167 Buffering scheme
168 ~~~~~~~~~~~~~~~~
169 In the user space tracing domain, two buffering schemes are available
170 when creating a channel:
171
172 Per-process buffering (option:--buffers-pid option)::
173 Keep one ring buffer per process.
174
175 Per-user buffering (option:--buffers-uid option)::
176 Keep one ring buffer for all the processes of a single user.
177
178 The per-process buffering scheme consumes more memory than the per-user
179 option if more than one process is instrumented for LTTng-UST.
180 However, per-process buffering ensures that one process having a high
181 event throughput won't fill all the shared sub-buffers, only its own.
182
183 The Linux kernel tracing domain only has one available buffering scheme
184 which is to use a single ring buffer for the whole system
185 (option:--buffers-global option).
186
187
188 Trace files limit and size
189 ~~~~~~~~~~~~~~~~~~~~~~~~~~
190 By default, trace files can grow as large as needed. The maximum size
191 of each trace file written by a channel can be set on creation using the
192 option:--tracefile-size option. When such a trace file's size reaches
193 the channel's fixed maximum size, another trace file is created to hold
194 the next recorded events. A file count is appended to each trace file
195 name in this case.
196
197 If the option:--tracefile-size option is used, the maximum number of
198 created trace files is unlimited. To limit them, the
199 option:--tracefile-count option can be used. This option is always used
200 in conjunction with the option:--tracefile-size option.
201
202 For example, consider this command:
203
204 [role="term"]
205 ----
206 $ lttng enable-channel --kernel --tracefile-size=4096 \
207 --tracefile-count=32 my-channel
208 ----
209
210 Here, for each stream, the maximum size of each trace file is
211 4 kiB and there can be a maximum of 32 different files. When there is
212 no space left in the last file, _trace file rotation_ happens: the first
213 file is cleared and new sub-buffers containing events are written there.
214
215
216 include::common-cmd-options-head.txt[]
217
218
219 Domain
220 ~~~~~~
221 One of:
222
223 option:-k, option:--kernel::
224 Enable channel in the Linux kernel domain.
225
226 option:-u, option:--userspace::
227 Enable channel in the user space domain.
228
229
230 Target
231 ~~~~~~
232 option:-s 'SESSION', option:--session='SESSION'::
233 Create or enable channel in the tracing session named 'SESSION'
234 instead of the current tracing session.
235
236
237 Event loss mode
238 ~~~~~~~~~~~~~~~
239 One of:
240
241 option:--discard::
242 Discard events when sub-buffers are full (default).
243
244 option:--overwrite::
245 Flight recorder mode: always keep a fixed amount of the latest
246 data.
247
248
249 Sub-buffers
250 ~~~~~~~~~~~
251 option:--num-subbuf='COUNT'::
252 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
253 +
254 Default values:
255 +
256 * option:--userspace and option:--buffers-uid options:
257 {default_ust_uid_channel_subbuf_num}
258 * option:--userspace and option:--buffers-pid options:
259 {default_ust_pid_channel_subbuf_num}
260 * option:--kernel option: {default_kernel_channel_subbuf_num}
261 * `metadata` channel: {default_metadata_subbuf_num}
262
263 option:--subbuf-size='SIZE'::
264 Set the individual size of sub-buffers to 'SIZE' bytes.
265 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
266 Rounded up to the next power of two.
267 +
268 The minimum sub-buffer size, for each tracer, is the maximum value
269 between the default below and the system's page size. The following
270 command shows the current system's page size: `getconf PAGE_SIZE`.
271 +
272 Default values:
273 +
274 * option:--userspace and option:--buffers-uid options:
275 {default_ust_uid_channel_subbuf_size}
276 * option:--userspace and option:--buffers-pid options:
277 {default_ust_pid_channel_subbuf_size}
278 * option:--kernel option: {default_kernel_channel_subbuf_size}
279 * `metadata` channel: {default_metadata_subbuf_size}
280
281 option:--output='TYPE'::
282 Set channel's output type to 'TYPE'.
283 +
284 Available types: `mmap` (always available) and `splice` (only available
285 with the option:--kernel option).
286 +
287 Default values:
288 +
289 * option:--userspace and option:--buffers-uid options: `mmap`
290 * option:--userspace and option:--buffers-pid options: `mmap`
291 * option:--kernel option: `splice`
292 * `metadata` channel: `mmap`
293
294 Buffering scheme
295 ~~~~~~~~~~~~~~~~
296 One of:
297
298 option:--buffers-global::
299 Use shared sub-buffers for the whole system (only available with the
300 option:--kernel option).
301
302 option:--buffers-pid::
303 Use different sub-buffers for each traced process (only available
304 with the the option:--userspace option). This is the default
305 buffering scheme for user space channels.
306
307 option:--buffers-uid::
308 Use shared sub-buffers for all the processes of the user running
309 the command (only available with the option:--userspace option).
310
311
312 Trace files
313 ~~~~~~~~~~~
314 option:--tracefile-count='COUNT'::
315 Limit the number of trace files created by this channel to
316 'COUNT'. 0 means unlimited. Default:
317 {default_channel_tracefile_count}.
318 +
319 Use this option in conjunction with the option:--tracefile-size option.
320 +
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.
324
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.
328 Default: {default_channel_tracefile_size}.
329 +
330 Note: traces generated with this option may inaccurately report
331 discarded events as of CTF 1.8.
332
333
334 Timers
335 ~~~~~~
336 option:--read-timer::
337 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
338 disabled read timer.
339 +
340 Default values:
341 +
342 * option:--userspace and option:--buffers-uid options:
343 {default_ust_uid_channel_read_timer}
344 * option:--userspace and option:--buffers-pid options:
345 {default_ust_pid_channel_read_timer}
346 * option:--kernel option: {default_kernel_channel_read_timer}
347 * `metadata` channel: {default_metadata_read_timer}
348
349 option:--switch-timer='PERIODUS'::
350 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
351 a disabled switch timer.
352 +
353 Default values:
354 +
355 * option:--userspace and option:--buffers-uid options:
356 {default_ust_uid_channel_switch_timer}
357 * option:--userspace and option:--buffers-pid options:
358 {default_ust_pid_channel_switch_timer}
359 * option:--kernel option: {default_kernel_channel_switch_timer}
360 * `metadata` channel: {default_metadata_switch_timer}
361
362 Timeouts
363 ~~~~~~~~
364 option:--blocking-timeout='TIMEOUTUS'::
365 Set the channel's blocking timeout value to 'TIMEOUTUS' µs
366 for applications executed with a set `LTTNG_UST_ALLOW_BLOCKING`
367 environment variable:
368 +
369 --
370 0 (default)::
371 Do not block.
372
373 -1::
374 Block forever until room is available in the sub-buffer to write the
375 event record.
376
377 __n__, a positive value::
378 Wait for at most __n__ µs when trying to write into a sub-buffer.
379 --
380
381
382 include::common-cmd-help-options.txt[]
383
384
385 [[limitations]]
386 LIMITATIONS
387 -----------
388 As of this version of LTTng, it is not possible to perform the following
389 actions with the `lttng enable-channel` command:
390
391 * Reconfigure a channel once it is created.
392 * Re-enable a disabled channel once its tracing session has been active
393 at least once.
394 * Create a channel once its tracing session has been active
395 at least once.
396 * Create a user space channel with a given buffering scheme
397 (option:--buffers-uid or option:--buffers-pid options) and create
398 a second user space channel with a different buffering scheme in the
399 same tracing session.
400
401
402 include::common-cmd-footer.txt[]
403
404
405 SEE ALSO
406 --------
407 man:lttng-disable-channel(1),
408 man:lttng(1),
409 man:lttng-ust(3)
This page took 0.058189 seconds and 4 git commands to generate.