315f1c54e30e5334df1c7348238418d8d516ccf5
[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:--tracefile-size='SIZE'] [option:--tracefile-count='COUNT']
30 [option:--session='SESSION'] 'CHANNEL'
31
32 Enable existing channel(s):
33
34 [verse]
35 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-channel* (option:--userspace | option:--kernel)
36 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
37
38
39 DESCRIPTION
40 -----------
41 The `lttng enable-channel` command can create a new channel, or enable
42 one or more existing and disabled ones.
43
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.
49
50 When 'CHANNEL' does not name an existing channel, a channel named
51 'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
52 is enabled.
53
54 Note that the man:lttng-enable-event(1) command can automatically
55 create default channels when no channel exist.
56
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.
62
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).
66
67 See the <<limitations,LIMITATIONS>> section below for a list of
68 limitations of this command to consider.
69
70
71 Event loss modes
72 ~~~~~~~~~~~~~~~~
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.
76
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.
80
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:
84
85 Discard::
86 Drop the newest events until a sub-buffer is released.
87
88 Overwrite::
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.
93
94 Which mechanism to choose depends on the context: prioritize the newest
95 or the oldest events in the ring buffer?
96
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.
101
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
105 committed.
106
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).
110
111
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
116 a new channel.
117
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):
124
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
131 are left unaltered.
132
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.
138
139 Low memory system::
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.
144
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.
148
149
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.
155
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.
158
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.
164
165
166 Buffering scheme
167 ~~~~~~~~~~~~~~~~
168 In the user space tracing domain, two buffering schemes are available
169 when creating a channel:
170
171 Per-process buffering (option:--buffers-pid option)::
172 Keep one ring buffer per process.
173
174 Per-user buffering (option:--buffers-uid option)::
175 Keep one ring buffer for all the processes of a single user.
176
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.
181
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).
185
186
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
194 name in this case.
195
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.
200
201 For example, consider this command:
202
203 [role="term"]
204 -----------------------------------------------------
205 lttng enable-channel --kernel --tracefile-size=4096 \
206 --tracefile-count=32 my-channel
207 -----------------------------------------------------
208
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.
213
214
215 include::common-cmd-options-head.txt[]
216
217
218 Domain
219 ~~~~~~
220 One of:
221
222 option:-k, option:--kernel::
223 Enable channel in the Linux kernel domain.
224
225 option:-u, option:--userspace::
226 Enable channel in the user space domain.
227
228
229 Target
230 ~~~~~~
231 option:-s 'SESSION', option:--session='SESSION'::
232 Create or enable channel in the tracing session named 'SESSION'
233 instead of the current tracing session.
234
235
236 Event loss mode
237 ~~~~~~~~~~~~~~~
238 One of:
239
240 option:--discard::
241 Discard events when sub-buffers are full (default).
242
243 option:--overwrite::
244 Flight recorder mode: always keep a fixed amount of the latest
245 data.
246
247
248 Sub-buffers
249 ~~~~~~~~~~~
250 option:--num-subbuf='COUNT'::
251 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
252 +
253 Default values:
254 +
255 * option:--userspace and option:--buffers-uid options:
256 {default_ust_uid_channel_subbuf_num}
257 * option:--userspace and option:--buffers-pid options:
258 {default_ust_pid_channel_subbuf_num}
259 * option:--kernel option: {default_kernel_channel_subbuf_num}
260 * `metadata` channel: {default_metadata_subbuf_num}
261
262 option:--subbuf-size='SIZE'::
263 Set the individual size of sub-buffers to 'SIZE' bytes.
264 The `k` (kiB), `M` (MiB), and `G` (GiB) suffixes are supported.
265 Rounded up to the next power of two.
266 +
267 The minimum sub-buffer size, for each tracer, is the maximum value
268 between the default below and the system's page size. The following
269 command shows the current system's page size: `getconf PAGE_SIZE`.
270 +
271 Default values:
272 +
273 * option:--userspace and option:--buffers-uid options:
274 {default_ust_uid_channel_subbuf_size}
275 * option:--userspace and option:--buffers-pid options:
276 {default_ust_pid_channel_subbuf_size}
277 * option:--kernel option: {default_kernel_channel_subbuf_size}
278 * `metadata` channel: {default_metadata_subbuf_size}
279
280 option:--output='TYPE'::
281 Set channel's output type to 'TYPE'.
282 +
283 Available types: `mmap` (always available) and `splice` (only available
284 with the option:--kernel option).
285 +
286 Default values:
287 +
288 * option:--userspace and option:--buffers-uid options: `mmap`
289 * option:--userspace and option:--buffers-pid options: `mmap`
290 * option:--kernel option: `splice`
291 * `metadata` channel: `mmap`
292
293 Buffering scheme
294 ~~~~~~~~~~~~~~~~
295 One of:
296
297 option:--buffers-global::
298 Use shared sub-buffers for the whole system (only available with the
299 option:--kernel option).
300
301 option:--buffers-pid::
302 Use different sub-buffers for each traced process (only available
303 with the the option:--userspace option). This is the default
304 buffering scheme for user space channels.
305
306 option:--buffers-uid::
307 Use shared sub-buffers for all the processes of the user running
308 the command (only available with the option:--userspace option).
309
310
311 Trace files
312 ~~~~~~~~~~~
313 option:--tracefile-count='COUNT'::
314 Limit the number of trace files created by this channel to
315 'COUNT'. 0 means unlimited. Default:
316 {default_channel_tracefile_count}.
317 +
318 Use this option in conjunction with the option:--tracefile-size option.
319 +
320 The file count within a stream is appended to each created trace
321 file. If 'COUNT' files are created and more events need to be recorded,
322 the first trace file of the stream is cleared and used again.
323
324 option:--tracefile-size='SIZE'::
325 Set the maximum size of each trace file written by
326 this channel within a stream to 'SIZE' bytes. 0 means unlimited.
327 Default: {default_channel_tracefile_size}.
328 +
329 Note: traces generated with this option may inaccurately report
330 discarded events as of CTF 1.8.
331
332
333 Timers
334 ~~~~~~
335 option:--read-timer::
336 Set the channel's read timer's period to 'PERIODUS' µs. 0 means a
337 disabled read timer.
338 +
339 Default values:
340 +
341 * option:--userspace and option:--buffers-uid options:
342 {default_ust_uid_channel_read_timer}
343 * option:--userspace and option:--buffers-pid options:
344 {default_ust_pid_channel_read_timer}
345 * option:--kernel option: {default_kernel_channel_read_timer}
346 * `metadata` channel: {default_metadata_read_timer}
347
348 option:--switch-timer='PERIODUS'::
349 Set the channel's switch timer's period to 'PERIODUS' µs. 0 means
350 a disabled switch timer.
351 +
352 Default values:
353 +
354 * option:--userspace and option:--buffers-uid options:
355 {default_ust_uid_channel_switch_timer}
356 * option:--userspace and option:--buffers-pid options:
357 {default_ust_pid_channel_switch_timer}
358 * option:--kernel option: {default_kernel_channel_switch_timer}
359 * `metadata` channel: {default_metadata_switch_timer}
360
361
362 include::common-cmd-help-options.txt[]
363
364
365 [[limitations]]
366 LIMITATIONS
367 -----------
368 As of this version of LTTng, it is not possible to perform the following
369 actions with the `lttng enable-channel` command:
370
371 * Reconfigure a channel once it is created.
372 * Re-enable a disabled channel once its tracing session has been active
373 at least once.
374 * Create a channel once its tracing session has been active
375 at least once.
376 * Create a user space channel with a given buffering scheme
377 (option:--buffers-uid or option:--buffers-pid options) and create
378 a second user space channel with a different buffering scheme in the
379 same tracing session.
380
381
382 include::common-cmd-footer.txt[]
383
384
385 SEE ALSO
386 --------
387 man:lttng-disable-channel(1),
388 man:lttng(1)
This page took 0.056612 seconds and 3 git commands to generate.