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