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