doc/man: create lttng-calibrate(1) and update/fix content
[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* ['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'
21
22 Create a user space channel:
23
24 [verse]
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'
31
32 Enable existing channel(s):
33
34 [verse]
35 *lttng* ['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 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.
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 linklttng: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 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.
62
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).
66
67 As of this version of LTTng, it is not possible to:
68
69 * Reconfigure a channel once it is created.
70 * Re-enable a disabled channel once its tracing session has been active
71 at least once.
72 * Create a channel once its tracing session has been active
73 at least once.
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
77 same tracing session.
78
79
80 Event loss modes
81 ~~~~~~~~~~~~~~~~
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.
85
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.
89
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:
93
94 Discard::
95 Drop the newest events until a sub-buffer is released.
96
97 Overwrite::
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.
102
103 Which mechanism to choose depends on the context: prioritize the newest
104 or the oldest events in the ring buffer?
105
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.
110
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
114 committed.
115
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).
119
120
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
125 a new channel.
126
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):
133
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
140 are left unaltered.
141
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.
147
148 Low memory system::
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.
153
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.
157
158
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.
164
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.
167
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.
173
174
175 Buffering scheme
176 ~~~~~~~~~~~~~~~~
177 In the user space tracing domain, two buffering schemes are available
178 when creating a channel:
179
180 Per-process buffering (option:--buffers-pid option)::
181 Keep one ring buffer per process.
182
183 Per-user buffering (option:--buffers-uid option)::
184 Keep one ring buffer for all the processes of a single user.
185
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.
190
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).
194
195
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
203 name in this case.
204
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.
209
210 For example, consider this command:
211
212 -----------------------------------------------------
213 lttng enable-channel --kernel --tracefile-size=4096 \
214 --tracefile-count=32 my-channel
215 -----------------------------------------------------
216
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.
221
222
223 include::common-cmd-options-head.txt[]
224
225
226 Domain
227 ~~~~~~
228 One of:
229
230 option:-k, option:--kernel::
231 Enable channel in the Linux kernel domain.
232
233 option:-u, option:--userspace::
234 Enable channel in the user space domain.
235
236
237 Target
238 ~~~~~~
239 option:-s, option:--session='SESSION'::
240 Create or enable channel in the tracing session named 'SESSION'
241 instead of the current tracing session.
242
243
244 Event loss mode
245 ~~~~~~~~~~~~~~~
246 One of:
247
248 option:--discard::
249 Discard events when sub-buffers are full (default).
250
251 option:--overwrite::
252 Flight recorder mode: always keep a fixed amount of the latest
253 data.
254
255
256 Sub-buffers
257 ~~~~~~~~~~~
258 option:--num-subbuf='COUNT'::
259 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
260 +
261 Default values:
262 +
263 * `metadata` channel: 2
264 * Everything else: 4
265
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.
270 +
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`.
274 +
275 Default values:
276 +
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`
281
282 option:--output='TYPE'::
283 Set channel's output type to 'TYPE'.
284 +
285 Available types: `mmap` (always available) and `splice` (only available
286 with the option:--kernel option).
287 +
288 Default values:
289 +
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`
294
295 Buffering scheme
296 ~~~~~~~~~~~~~~~~
297 One of:
298
299 option:--buffers-global::
300 Use shared sub-buffers for the whole system (only available with the
301 option:--kernel option).
302
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.
307
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).
311
312
313 Trace files
314 ~~~~~~~~~~~
315 option:--tracefile-count='COUNT'::
316 Limit the number of trace files created by this channel to
317 'COUNT'. 0 means unlimited. Default: 0.
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: 0.
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: 0
343 * option:--userspace and option:--buffers-pid options: 0
344 * option:--kernel option: 200000
345 * `metadata` channel: 0
346
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.
350
351
352 include::common-cmd-help-options.txt[]
353
354
355 include::common-cmd-footer.txt[]
356
357
358 SEE ALSO
359 --------
360 linklttng:lttng-disable-channel(1),
361 linklttng:lttng(1)
This page took 0.045831 seconds and 4 git commands to generate.