1LTTNG-ENABLE-CHANN(1) LTTng Manual LTTNG-ENABLE-CHANN(1)
2
6 lttng-enable-channel - Create or enable LTTng channels
7
9 Create a Linux kernel channel:
10 lttng [GENERAL OPTIONS] enable-channel --kernel
12 [--overwrite] [--output=(mmap | splice)]
13 [--subbuf-size=SIZE] [--num-subbuf=COUNT]
14 [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
15 [--monitor-timer=PERIODUS]
16 [--tracefile-size=SIZE] [--tracefile-count=COUNT]
17 [--session=SESSION] CHANNEL
18 Create a user space channel:
20 lttng [GENERAL OPTIONS] enable-channel --userspace
22 [--overwrite | --blocking-timeout=TIMEOUTUS] [--buffers-pid]
23 [--subbuf-size=SIZE] [--num-subbuf=COUNT]
24 [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
25 [--monitor-timer=PERIODUS]
26 [--tracefile-size=SIZE] [--tracefile-count=COUNT]
27 [--session=SESSION] CHANNEL
28 Enable existing channel(s):
30 lttng [GENERAL OPTIONS] enable-channel (--userspace | --kernel)
32 [--session=SESSION] CHANNEL[,CHANNEL]...
33
35 The lttng enable-channel command can create a new channel, or enable
36 one or more existing and disabled ones.
37 A channel is the owner of sub-buffers holding recorded events. Event,
39 rules, when created using lttng-enable-event(1), are always assigned to
40 a channel. When creating a new channel, many parameters related to
41 those sub-buffers can be fine-tuned. They are described in the
42 subsections below.
43 When CHANNEL does not name an existing channel, a channel named CHANNEL
45 is created. Otherwise, the disabled channel named CHANNEL is enabled.
46 Note that the lttng-enable-event(1) command can automatically create
48 default channels when no channel exist.
49 A channel is always contained in a tracing session (see lttng-create(1)
51 for creating a tracing session). The session in which a channel is
52 created using lttng enable-channel can be specified using the --session
53 option. If the --session option is omitted, the current tracing session
54 is targeted.
55 Existing enabled channels can be disabled using lttng-disable-
57 channel(1). Channels of a given session can be listed using lttng-
58 list(1).
59 See the LIMITATIONS section below for a list of limitations of this
61 command to consider.
62 Event loss modes
64 LTTng tracers are non-blocking by default: when no empty sub-buffer
65 exists, losing events is acceptable when the alternative would be to
66 cause substantial delays in the instrumented application’s execution.
67 LTTng privileges performance over integrity, aiming at perturbing the
69 traced system as little as possible in order to make tracing of subtle
70 race conditions and rare interrupt cascades possible.
71 You can allow the user space tracer to block with a --blocking-timeout
73 option set to a positive value or to inf, and with an application which
74 is instrumented with LTTng-UST started with a set
75 LTTNG_UST_ALLOW_BLOCKING environment variable. See lttng-ust(3) for
76 more details.
77 When it comes to losing events because no empty sub-buffer is
79 available, the channel’s event loss mode, specified by one of the
80 --discard and --overwrite options, determines what to do amongst:
81 Discard
83 Drop the newest events until a sub-buffer is released.
84 Overwrite
86 Clear the sub-buffer containing the oldest recorded events and
87 start recording the newest events there. This mode is sometimes
88 called flight recorder mode because it behaves like a flight
89 recorder: always keep a fixed amount of the latest data.
90 Which mechanism to choose depends on the context: prioritize the newest
92 or the oldest events in the ring buffer?
93 Beware that, in overwrite mode (--overwrite option), a whole sub-buffer
95 is abandoned as soon as a new event doesn’t find an empty sub-buffer,
96 whereas in discard mode (--discard option), only the event that doesn’t
97 fit is discarded.
98 Also note that a count of lost events is incremented and saved in the
100 trace itself when an event is lost in discard mode, whereas no
101 information is kept when a sub-buffer gets overwritten before being
102 committed.
103 The probability of losing events, if it is experience in a given
105 context, can be reduced by fine-tuning the sub-buffers count and size
106 (see next subsection).
107 Sub-buffers count and size
109 The --num-subbuf and --subbuf-size options respectively set the number
110 of sub-buffers and their individual size when creating a new channel.
111 Note that there is a noticeable tracer’s CPU overhead introduced when
113 switching sub-buffers (marking a full one as consumable and switching
114 to an empty one for the following events to be recorded). Knowing this,
115 the following list presents a few practical situations along with how
116 to configure sub-buffers for them when creating a channel in overwrite
117 mode (--overwrite option):
118 High event throughput
120 In general, prefer bigger sub-buffers to lower the risk of losing
121 events. Having bigger sub-buffers also ensures a lower sub-buffer
122 switching frequency. The number of sub-buffers is only meaningful
123 if the channel is enabled in overwrite mode: in this case, if a
124 sub-buffer overwrite happens, the other sub-buffers are left
125 unaltered.
126 Low event throughput
128 In general, prefer smaller sub-buffers since the risk of losing
129 events is already low. Since events happen less frequently, the
130 sub-buffer switching frequency should remain low and thus the
131 tracer’s overhead should not be a problem.
132 Low memory system
134 If the target system has a low memory limit, prefer fewer first,
135 then smaller sub-buffers. Even if the system is limited in memory,
136 it is recommended to keep the sub-buffers as big as possible to
137 avoid a high sub-buffer switching frequency.
138 In discard mode (--discard option), the sub-buffers count parameter is
140 pointless: using two sub-buffers and setting their size according to
141 the requirements of the context is fine.
142 Switch timer
144 When a channel’s switch timer fires, a sub-buffer switch happens. This
145 timer may be used to ensure that event data is consumed and committed
146 to trace files periodically in case of a low event throughput.
147 It’s also convenient when big sub-buffers are used to cope with
149 sporadic high event throughput, even if the throughput is normally
150 lower.
151 Use the --switch-timer option to control the switch timer’s period of
153 the channel to create.
154 Read timer
156 By default, an internal notification mechanism is used to signal a full
157 sub-buffer so that it can be consumed. When such notifications must be
158 avoided, for example in real-time applications, the channel’s read
159 timer can be used instead. When the read timer fires, sub-buffers are
160 checked for consumption when they are full.
161 Use the --read-timer option to control the read timer’s period of the
163 channel to create.
164 Monitor timer
166 When a channel’s monitor timer fires, its registered trigger conditions
167 are evaluated using the current values of its properties (for example,
168 the current usage of its sub-buffers). When a trigger condition is
169 true, LTTng executes its associated action. The only type of action
170 currently supported is to notify one or more user applications.
171 See the installed C/C++ headers in lttng/action, lttng/condition,
173 lttng/notification, and lttng/trigger to learn more about application
174 notifications and triggers.
175 Use the --monitor-timer option to control the monitor timer’s period of
177 the channel to create.
178 Buffering scheme
180 In the user space tracing domain, two buffering schemes are available
181 when creating a channel:
182 Per-process buffering (--buffers-pid option)
184 Keep one ring buffer per process.
185 Per-user buffering (--buffers-uid option)
187 Keep one ring buffer for all the processes of a single user.
188 The per-process buffering scheme consumes more memory than the per-user
190 option if more than one process is instrumented for LTTng-UST. However,
191 per-process buffering ensures that one process having a high event
192 throughput won’t fill all the shared sub-buffers, only its own.
193 The Linux kernel tracing domain only has one available buffering scheme
195 which is to use a single ring buffer for the whole system (--buffers-
196 global option).
197 Trace files limit and size
199 By default, trace files can grow as large as needed. The maximum size
200 of each trace file written by a channel can be set on creation using
201 the --tracefile-size option. When such a trace file’s size reaches the
202 channel’s fixed maximum size, another trace file is created to hold the
203 next recorded events. A file count is appended to each trace file name
204 in this case.
205 If the --tracefile-size option is used, the maximum number of created
207 trace files is unlimited. To limit them, the --tracefile-count option
208 can be used. This option is always used in conjunction with the
209 --tracefile-size option.
210 For example, consider this command:
212 $ lttng enable-channel --kernel --tracefile-size=4096 \
214 --tracefile-count=32 my-channel
215 Here, for each stream, the maximum size of each trace file is 4 kiB and
217 there can be a maximum of 32 different files. When there is no space
218 left in the last file, trace file rotation happens: the first file is
219 cleared and new sub-buffers containing events are written there.
220 LTTng does not guarantee that you can view the trace of an active
222 tracing session before you run the lttng-stop(1) command, even with
223 multiple trace files, because LTTng could overwrite them at any moment,
224 or some of them could be incomplete. You can archive a tracing
225 session’s current trace chunk while the tracing session is active to
226 obtain an unmanaged and self-contained LTTng trace: see the lttng-
227 rotate(1) and lttng-enable-rotation(1) commands.
228
230 General options are described in lttng(1).
231 Domain
233 One of:
234 -k, --kernel
236 Enable channel in the Linux kernel domain.
237 -u, --userspace
239 Enable channel in the user space domain.
240 Target
242 -s SESSION, --session=SESSION
243 Create or enable channel in the tracing session named SESSION
244 instead of the current tracing session.
245 Event loss mode
247 --blocking-timeout=TIMEOUTUS
248 Set the channel’s blocking timeout value to TIMEOUTUS µs for
249 instrumented applications executed with a set
250 LTTNG_UST_ALLOW_BLOCKING environment variable:
251 0 (default)
253 Do not block (non-blocking mode).
254 inf
256 Block forever until room is available in the sub-buffer to
257 write the event record.
258 n, a positive value
260 Wait for at most n µs when trying to write into a sub-buffer.
261 After n µs, discard the event record.
262 This option is only available with the --userspace option and
264 without the --overwrite option.
265 One of:
267 --discard
269 Discard events when sub-buffers are full (default).
270 --overwrite
272 Flight recorder mode: always keep a fixed amount of the latest
273 data.
274 Sub-buffers
276 --num-subbuf=COUNT
277 Use COUNT sub-buffers. Rounded up to the next power of two.
278 Default values:
280 • --userspace and --buffers-uid options: 4
282 • --userspace and --buffers-pid options: 4
284 • --kernel option: 4
286 • metadata channel: 2
288 --output=TYPE
290 Set channel’s output type to TYPE.
291 Available types: mmap (always available) and splice (only available
293 with the --kernel option).
294 Default values:
296 • --userspace and --buffers-uid options: mmap
298 • --userspace and --buffers-pid options: mmap
300 • --kernel option: splice
302 • metadata channel: mmap
304 --subbuf-size=SIZE
306 Set the individual size of sub-buffers to SIZE bytes. The k (kiB),
307 M (MiB), and G (GiB) suffixes are supported. Rounded up to the next
308 power of two.
309 The minimum sub-buffer size, for each tracer, is the maximum value
311 between the default below and the system’s page size. The following
312 command shows the current system’s page size: getconf PAGE_SIZE.
313 Default values:
315 • --userspace and --buffers-uid options: 524288
317 • --userspace and --buffers-pid options: 16384
319 • --kernel option: 1048576
321 • metadata channel: 4096
323 Buffering scheme
325 One of:
326 --buffers-global
328 Use shared sub-buffers for the whole system (only available with
329 the --kernel option).
330 --buffers-pid
332 Use different sub-buffers for each traced process (only available
333 with the the --userspace option). This is the default buffering
334 scheme for user space channels.
335 --buffers-uid
337 Use shared sub-buffers for all the processes of the user running
338 the command (only available with the --userspace option).
339 Trace files
341 --tracefile-count=COUNT
342 Limit the number of trace files created by this channel to COUNT. 0
343 means unlimited. Default: 0.
344 Use this option in conjunction with the --tracefile-size option.
346 The file count within a stream is appended to each created trace
348 file. If COUNT files are created and more events need to be
349 recorded, the first trace file of the stream is cleared and used
350 again.
351 --tracefile-size=SIZE
353 Set the maximum size of each trace file written by this channel
354 within a stream to SIZE bytes. 0 means unlimited. Default: 0.
355 Note: traces generated with this option may inaccurately report
357 discarded events as of CTF 1.8.
358 Timers
360 --monitor-timer
361 Set the channel’s monitor timer’s period to PERIODUS µs. 0 means a
362 disabled monitor timer.
363 Default values:
365 • --userspace and --buffers-uid options: 1000000
367 • --userspace and --buffers-pid options: 1000000
369 • --kernel option: 1000000
371 --read-timer
373 Set the channel’s read timer’s period to PERIODUS µs. 0 means a
374 disabled read timer.
375 Default values:
377 • --userspace and --buffers-uid options: 0
379 • --userspace and --buffers-pid options: 0
381 • --kernel option: 200000
383 • metadata channel: 0
385 --switch-timer=PERIODUS
387 Set the channel’s switch timer’s period to PERIODUS µs. 0 means a
388 disabled switch timer.
389 Default values:
391 • --userspace and --buffers-uid options: 0
393 • --userspace and --buffers-pid options: 0
395 • --kernel option: 0
397 • metadata channel: 0
399 Program information
401 -h, --help
402 Show command help.
403 This option, like lttng-help(1), attempts to launch /usr/bin/man to
405 view the command’s man page. The path to the man pager can be
406 overridden by the LTTNG_MAN_BIN_PATH environment variable.
407 --list-options
409 List available command options.
410
412 As of this version of LTTng, it is not possible to perform the
413 following actions with the lttng enable-channel command:
414 • Reconfigure a channel once it is created.
416 • Re-enable a disabled channel once its tracing session has been
418 active at least once.
419 • Create a channel once its tracing session has been active at least
421 once.
422 • Create a user space channel with a given buffering scheme
424 (--buffers-uid or --buffers-pid options) and create a second user
425 space channel with a different buffering scheme in the same tracing
426 session.
427
429 LTTNG_ABORT_ON_ERROR
430 Set to 1 to abort the process after the first error is encountered.
431 LTTNG_HOME
433 Overrides the $HOME environment variable. Useful when the user
434 running the commands has a non-writable home directory.
435 LTTNG_MAN_BIN_PATH
437 Absolute path to the man pager to use for viewing help information
438 about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
439 LTTNG_SESSION_CONFIG_XSD_PATH
441 Path in which the session.xsd session configuration XML schema may
442 be found.
443 LTTNG_SESSIOND_PATH
445 Full session daemon binary path.
446 The --sessiond-path option has precedence over this environment
448 variable.
449 Note that the lttng-create(1) command can spawn an LTTng session daemon
451 automatically if none is running. See lttng-sessiond(8) for the
452 environment variables influencing the execution of the session daemon.
453
455 $LTTNG_HOME/.lttngrc
456 User LTTng runtime configuration.
457 This is where the per-user current tracing session is stored
459 between executions of lttng(1). The current tracing session can be
460 set with lttng-set-session(1). See lttng-create(1) for more
461 information about tracing sessions.
462 $LTTNG_HOME/lttng-traces
464 Default output directory of LTTng traces. This can be overridden
465 with the --output option of the lttng-create(1) command.
466 $LTTNG_HOME/.lttng
468 User LTTng runtime and configuration directory.
469 $LTTNG_HOME/.lttng/sessions
471 Default location of saved user tracing sessions (see lttng-save(1)
472 and lttng-load(1)).
473 /usr/local/etc/lttng/sessions
475 System-wide location of saved tracing sessions (see lttng-save(1)
476 and lttng-load(1)).
477 Note
479 $LTTNG_HOME defaults to $HOME when not explicitly set.
480
482 0
483 Success
484 1
486 Command error
487 2
489 Undefined command
490 3
492 Fatal error
493 4
495 Command warning (something went wrong during the command)
496
498 If you encounter any issue or usability problem, please report it on
499 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
500
502 • LTTng project website <https://lttng.org>
503 • LTTng documentation <https://lttng.org/docs>
505 • Git repositories <http://git.lttng.org>
507 • GitHub organization <http://github.com/lttng>
509 • Continuous integration <http://ci.lttng.org/>
511 • Mailing list <http://lists.lttng.org> for support and development:
513 lttng-dev@lists.lttng.org
514 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
516
518 This program is part of the LTTng-tools project.
519 LTTng-tools is distributed under the GNU General Public License version
521 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
522 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
523 for details.
524
526 Special thanks to Michel Dagenais and the DORSAL laboratory
527 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
528 the LTTng journey.
529 Also thanks to the Ericsson teams working on tracing which helped us
531 greatly with detailed bug reports and unusual test cases.
532
534 lttng-disable-channel(1), lttng(1), lttng-ust(3)
535LTTng 2.12.4 9 November 2018 LTTNG-ENABLE-CHANN(1)