1LTTNG-ENABLE-CHANN(1)            LTTng Manual            LTTNG-ENABLE-CHANN(1)
2
3
4

NAME

6       lttng-enable-channel - Create or enable LTTng channels
7

SYNOPSIS

9       Create a Linux kernel channel:
10
11       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
19       Create a user space channel:
20
21       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
29       Enable existing channel(s):
30
31       lttng [GENERAL OPTIONS] enable-channel (--userspace | --kernel)
32             [--session=SESSION] CHANNEL[,CHANNEL]...
33

DESCRIPTION

35       The lttng enable-channel command can create a new channel, or enable
36       one or more existing and disabled ones.
37
38       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
44       When CHANNEL does not name an existing channel, a channel named CHANNEL
45       is created. Otherwise, the disabled channel named CHANNEL is enabled.
46
47       Note that the lttng-enable-event(1) command can automatically create
48       default channels when no channel exist.
49
50       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
56       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
60       See the LIMITATIONS section below for a list of limitations of this
61       command to consider.
62
63   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
68       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
72       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
78       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
82       Discard
83           Drop the newest events until a sub-buffer is released.
84
85       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
91       Which mechanism to choose depends on the context: prioritize the newest
92       or the oldest events in the ring buffer?
93
94       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
99       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
104       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
108   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
112       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
119       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
127       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
133       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
139       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
143   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
148       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
152       Use the --switch-timer option to control the switch timer’s period of
153       the channel to create.
154
155   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
162       Use the --read-timer option to control the read timer’s period of the
163       channel to create.
164
165   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
172       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
176       Use the --monitor-timer option to control the monitor timer’s period of
177       the channel to create.
178
179   Buffering scheme
180       In the user space tracing domain, two buffering schemes are available
181       when creating a channel:
182
183       Per-process buffering (--buffers-pid option)
184           Keep one ring buffer per process.
185
186       Per-user buffering (--buffers-uid option)
187           Keep one ring buffer for all the processes of a single user.
188
189       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
194       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
198   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
206       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
211       For example, consider this command:
212
213           $ lttng enable-channel --kernel --tracefile-size=4096 \
214                                --tracefile-count=32 my-channel
215
216       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
221       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

OPTIONS

230       General options are described in lttng(1).
231
232   Domain
233       One of:
234
235       -k, --kernel
236           Enable channel in the Linux kernel domain.
237
238       -u, --userspace
239           Enable channel in the user space domain.
240
241   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
246   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
252           0 (default)
253               Do not block (non-blocking mode).
254
255           inf
256               Block forever until room is available in the sub-buffer to
257               write the event record.
258
259           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
263           This option is only available with the --userspace option and
264           without the --overwrite option.
265
266       One of:
267
268       --discard
269           Discard events when sub-buffers are full (default).
270
271       --overwrite
272           Flight recorder mode: always keep a fixed amount of the latest
273           data.
274
275   Sub-buffers
276       --num-subbuf=COUNT
277           Use COUNT sub-buffers. Rounded up to the next power of two.
278
279           Default values:
280
281--userspace and --buffers-uid options: 4
282
283--userspace and --buffers-pid options: 4
284
285--kernel option: 4
286
287metadata channel: 2
288
289       --output=TYPE
290           Set channel’s output type to TYPE.
291
292           Available types: mmap (always available) and splice (only available
293           with the --kernel option).
294
295           Default values:
296
297--userspace and --buffers-uid options: mmap
298
299--userspace and --buffers-pid options: mmap
300
301--kernel option: splice
302
303metadata channel: mmap
304
305       --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
310           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
314           Default values:
315
316--userspace and --buffers-uid options: 524288
317
318--userspace and --buffers-pid options: 16384
319
320--kernel option: 1048576
321
322metadata channel: 4096
323
324   Buffering scheme
325       One of:
326
327       --buffers-global
328           Use shared sub-buffers for the whole system (only available with
329           the --kernel option).
330
331       --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
336       --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
340   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
345           Use this option in conjunction with the --tracefile-size option.
346
347           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
352       --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
356           Note: traces generated with this option may inaccurately report
357           discarded events as of CTF 1.8.
358
359   Timers
360       --monitor-timer
361           Set the channel’s monitor timer’s period to PERIODUS µs. 0 means a
362           disabled monitor timer.
363
364           Default values:
365
366--userspace and --buffers-uid options: 1000000
367
368--userspace and --buffers-pid options: 1000000
369
370--kernel option: 1000000
371
372       --read-timer
373           Set the channel’s read timer’s period to PERIODUS µs. 0 means a
374           disabled read timer.
375
376           Default values:
377
378--userspace and --buffers-uid options: 0
379
380--userspace and --buffers-pid options: 0
381
382--kernel option: 200000
383
384metadata channel: 0
385
386       --switch-timer=PERIODUS
387           Set the channel’s switch timer’s period to PERIODUS µs. 0 means a
388           disabled switch timer.
389
390           Default values:
391
392--userspace and --buffers-uid options: 0
393
394--userspace and --buffers-pid options: 0
395
396--kernel option: 0
397
398metadata channel: 0
399
400   Program information
401       -h, --help
402           Show command help.
403
404           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
408       --list-options
409           List available command options.
410

LIMITATIONS

412       As of this version of LTTng, it is not possible to perform the
413       following actions with the lttng enable-channel command:
414
415       •   Reconfigure a channel once it is created.
416
417       •   Re-enable a disabled channel once its tracing session has been
418           active at least once.
419
420       •   Create a channel once its tracing session has been active at least
421           once.
422
423       •   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

ENVIRONMENT VARIABLES

429       LTTNG_ABORT_ON_ERROR
430           Set to 1 to abort the process after the first error is encountered.
431
432       LTTNG_HOME
433           Overrides the $HOME environment variable. Useful when the user
434           running the commands has a non-writable home directory.
435
436       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
440       LTTNG_SESSION_CONFIG_XSD_PATH
441           Path in which the session.xsd session configuration XML schema may
442           be found.
443
444       LTTNG_SESSIOND_PATH
445           Full session daemon binary path.
446
447           The --sessiond-path option has precedence over this environment
448           variable.
449
450       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

FILES

455       $LTTNG_HOME/.lttngrc
456           User LTTng runtime configuration.
457
458           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
463       $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
467       $LTTNG_HOME/.lttng
468           User LTTng runtime and configuration directory.
469
470       $LTTNG_HOME/.lttng/sessions
471           Default location of saved user tracing sessions (see lttng-save(1)
472           and lttng-load(1)).
473
474       /usr/local/etc/lttng/sessions
475           System-wide location of saved tracing sessions (see lttng-save(1)
476           and lttng-load(1)).
477
478           Note
479           $LTTNG_HOME defaults to $HOME when not explicitly set.
480

EXIT STATUS

482       0
483           Success
484
485       1
486           Command error
487
488       2
489           Undefined command
490
491       3
492           Fatal error
493
494       4
495           Command warning (something went wrong during the command)
496

BUGS

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

RESOURCES

502       •   LTTng project website <https://lttng.org>
503
504       •   LTTng documentation <https://lttng.org/docs>
505
506       •   Git repositories <http://git.lttng.org>
507
508       •   GitHub organization <http://github.com/lttng>
509
510       •   Continuous integration <http://ci.lttng.org/>
511
512       •   Mailing list <http://lists.lttng.org> for support and development:
513           lttng-dev@lists.lttng.org
514
515       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
516

COPYRIGHTS

518       This program is part of the LTTng-tools project.
519
520       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

THANKS

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
530       Also thanks to the Ericsson teams working on tracing which helped us
531       greatly with detailed bug reports and unusual test cases.
532

SEE ALSO

534       lttng-disable-channel(1), lttng(1), lttng-ust(3)
535
536
537
538LTTng 2.12.4                    9 November 2018          LTTNG-ENABLE-CHANN(1)
Impressum