doc/man: create lttng-enable-channel(1) and update/fix content
[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]
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
22Create 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
32Enable existing channel(s):
33
34[verse]
35*lttng* ['GENERAL OPTIONS'] *enable-channel* (option:--userspace | option:--kernel)
36 [option:--session='SESSION'] 'CHANNEL'[,'CHANNEL']...
37
38
39DESCRIPTION
40-----------
41The `lttng enable-channel` command can create a new channel, or enable
42one or more existing and disabled ones.
43
44A channel is the owner of sub-buffers holding recorded events. Event,
45rules, when created using linklttng:lttng-enable-event(1), are always
46assigned to a channel. When creating a new channel, many parameters
47related to those sub-buffers can be fine-tuned. They are described in
48the subsections below.
49
50When 'CHANNEL' does not name an existing channel, a channel named
51'CHANNEL' is created. Otherwise, the disabled channel named 'CHANNEL'
52is enabled.
53
54Note that the linklttng:lttng-enable-event(1) command can automatically
55create default channels when no channel exist.
56
57A channel is always contained in a tracing session
58(see linklttng:lttng-create(1) for creating a tracing session). The
59session in which a channel is created using `lttng enable-channel` can
60be specified using the option:--session option. If the option:--session
61option is omitted, the current tracing session is targeted.
62
63Existing enabled channels can be disabled using
64linklttng:lttng-disable-channel(1). Channels of a given session can be
65listed using linklttng:lttng-list(1).
66
67As 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
80Event loss modes
81~~~~~~~~~~~~~~~~
82LTTng tracers are non-blocking: when no empty sub-buffer exists,
83losing events is acceptable when the alternative would be to cause
84substantial delays in the instrumented application's execution.
85
86LTTng privileges performance over integrity, aiming at perturbing the
87traced system as little as possible in order to make tracing of subtle
88race conditions and rare interrupt cascades possible.
89
90When it comes to losing events because no empty sub-buffer is available,
91the channel's event loss mode, specified by one of the option:--discard
92and option:--overwrite options, determines what to do amongst:
93
94Discard::
95 Drop the newest events until a sub-buffer is released.
96
97Overwrite::
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
103Which mechanism to choose depends on the context: prioritize the newest
104or the oldest events in the ring buffer?
105
106Beware that, in overwrite mode (option:--overwrite option), a whole
107sub-buffer is abandoned as soon as a new event doesn't find an empty
108sub-buffer, whereas in discard mode (option:--discard option), only the
109event that doesn't fit is discarded.
110
111Also note that a count of lost events is incremented and saved in the
112trace itself when an event is lost in discard mode, whereas no
113information is kept when a sub-buffer gets overwritten before being
114committed.
115
116The probability of losing events, if it is experience in a given
117context, can be reduced by fine-tuning the sub-buffers count and size
118(see next subsection).
119
120
121Sub-buffers count and size
122~~~~~~~~~~~~~~~~~~~~~~~~~~
123The option:--num-subbuf and option:--subbuf-size options respectively
124set the number of sub-buffers and their individual size when creating
125a new channel.
126
127Note that there is a noticeable tracer's CPU overhead introduced when
128switching sub-buffers (marking a full one as consumable and switching
129to an empty one for the following events to be recorded). Knowing this,
130the following list presents a few practical situations along with how
131to configure sub-buffers for them when creating a channel in overwrite
132mode (option:--overwrite option):
133
134High 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
142Low 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
148Low 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
154In discard mode (option:--discard option), the sub-buffers count
155parameter is pointless: using two sub-buffers and setting their size
156according to the requirements of the context is fine.
157
158
159Switch and read timers
160~~~~~~~~~~~~~~~~~~~~~~
161When a channel's switch timer fires, a sub-buffer switch happens. This
162timer may be used to ensure that event data is consumed and committed
163to trace files periodically in case of a low event throughput.
164
165It's also convenient when big sub-buffers are used to cope with sporadic
166high event throughput, even if the throughput is normally lower.
167
168By default, a notification mechanism is used to signal a full sub-buffer
169so that it can be consumed. When such notifications must be avoided,
170for example in real-time applications, the channel's read timer can be
171used instead. When the read timer fires, sub-buffers are checked for
172consumption when they are full.
173
174
175Buffering scheme
176~~~~~~~~~~~~~~~~
177In the user space tracing domain, two buffering schemes are available
178when creating a channel:
179
180Per-process buffering (option:--buffers-pid option)::
181 Keep one ring buffer per process.
182
183Per-user buffering (option:--buffers-uid option)::
184 Keep one ring buffer for all the processes of a single user.
185
186The per-process buffering scheme consumes more memory than the per-user
187option if more than one process is instrumented for LTTng-UST.
188However, per-process buffering ensures that one process having a high
189event throughput won't fill all the shared sub-buffers, only its own.
190
191The Linux kernel tracing domain only has one available buffering scheme
192which is to use a single ring buffer for the whole system
193(option:--buffers-global option).
194
195
196Trace files limit and size
197~~~~~~~~~~~~~~~~~~~~~~~~~~
198By default, trace files can grow as large as needed. The maximum size
199of each trace file written by a channel can be set on creation using the
200option:--tracefile-size option. When such a trace file's size reaches
201the channel's fixed maximum size, another trace file is created to hold
202the next recorded events. A file count is appended to each trace file
203name in this case.
204
205If the option:--tracefile-size option is used, the maximum number of
206created trace files is unlimited. To limit them, the
207option:--tracefile-count option can be used. This option is always used
208in conjunction with the option:--tracefile-size option.
209
210For example, consider this command:
211
212-----------------------------------------------------
213lttng enable-channel --kernel --tracefile-size=4096 \
214 --tracefile-count=32 my-channel
215-----------------------------------------------------
216
217Here, for each stream, the maximum size of each trace file is
2184 kiB and there can be a maximum of 32 different files. When there is
219no space left in the last file, _trace file rotation_ happens: the first
220file is cleared and new sub-buffers containing events are written there.
221
222
223include::common-cmd-options-head.txt[]
224
225
226Domain
227~~~~~~
228One of:
229
230option:-k, option:--kernel::
231 Enable channel in the Linux kernel domain.
232
233option:-u, option:--userspace::
234 Enable channel in the user space domain.
235
236
237Target
238~~~~~~
239option:-s, option:--session='SESSION'::
240 Create or enable channel in the tracing session named 'SESSION'
241 instead of the current tracing session.
242
243
244Event loss mode
245~~~~~~~~~~~~~~~
246One of:
247
248option:--discard::
249 Discard events when sub-buffers are full (default).
250
251option:--overwrite::
252 Flight recorder mode: always keep a fixed amount of the latest
253 data.
254
255
256Sub-buffers
257~~~~~~~~~~~
258option:--num-subbuf='COUNT'::
259 Use 'COUNT' sub-buffers. Rounded up to the next power of two.
260+
261Default values:
262+
263* `metadata` channel: 2
264* Everything else: 4
265
266option:--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+
271The minimum sub-buffer size, for each tracer, is the maximum value
272between the default below and the system's page size. The following
273command shows the current system's page size: `getconf PAGE_SIZE`.
274+
275Default 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
282option:--output='TYPE'::
283 Set channel's output type to 'TYPE'.
284+
285Available types: `mmap` (always available) and `splice` (only available
286with the option:--kernel option).
287+
288Default 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
295Buffering scheme
296~~~~~~~~~~~~~~~~
297One of:
298
299option:--buffers-global::
300 Use shared sub-buffers for the whole system (only available with the
301 option:--kernel option).
302
303option:--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
308option:--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
313Trace files
314~~~~~~~~~~~
315option:--tracefile-count='COUNT'::
316 Limit the number of trace files created by this channel to
317 'COUNT'. 0 means unlimited. Default: 0.
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.
328 Default: 0.
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+
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
347option:--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
352include::common-cmd-help-options.txt[]
353
354
355include::common-cmd-footer.txt[]
356
357
358SEE ALSO
359--------
360linklttng:lttng-disable-channel(1),
361linklttng:lttng(1)
This page took 0.035726 seconds and 4 git commands to generate.