lttng-enable-channel(1)

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             [--discard | --overwrite] [--output=(mmap | splice)]
13             [--subbuf-size=SIZE] [--num-subbuf=COUNT]
14             [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
15             [--monitor-timer=PERIODUS] [--buffers-global]
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 | [--discard] --blocking-timeout=TIMEOUTUS]
23             [--output=mmap] [--buffers-uid | --buffers-pid]
24             [--subbuf-size=SIZE] [--num-subbuf=COUNT]
25             [--switch-timer=PERIODUS] [--read-timer=PERIODUS]
26             [--monitor-timer=PERIODUS]
27             [--tracefile-size=SIZE [--tracefile-count=COUNT]]
28             [--session=SESSION] CHANNEL
29
30       Enable channel(s):
31
32       lttng [GENERAL OPTIONS] enable-channel (--userspace | --kernel)
33             [--session=SESSION] CHANNEL[,CHANNEL]...
34

DESCRIPTION

36       The lttng enable-channel command does one of:
37
38       •   Create a channel named CHANNEL.
39
40       •   Enable one or more disabled channels named CHANNEL (non-option
41           argument, comma-separated).
42
43       See lttng-concepts(7) to learn more about channels.
44
45       The channel(s) to create or enable belong to:
46
47       With the --session=SESSION option
48           The recording session named SESSION.
49
50       Without the --session option
51           The current recording session (see lttng-concepts(7) to learn more
52           about the current recording session).
53
54       Note
55           The lttng-enable-event(1) command can automatically create a
56           default channel when no channel exists for the provided tracing
57           domain.
58
59       See the “EXAMPLES” section below for usage examples.
60
61       List the channels of a given recording session with the lttng-list(1)
62       and lttng-status(1) commands.
63
64       Disable an enabled channel with the lttng-disable-channel(1) command.
65
66       Important
67           As of LTTng 2.13.9, you may NOT perform the following operations
68           with the enable-channel command:
69
70           •   Change an attribute of an existing channel.
71
72           •   Enable a disabled channel once its recording session has been
73               active (started; see lttng-start(1)) at least once.
74
75           •   Create a channel once its recording session has been active at
76               least once.
77
78           •   Create a user space channel with a given buffering scheme
79               (--buffers-uid or --buffers-pid options) and create a second
80               user space channel with a different buffering scheme in the
81               same recording session.
82

OPTIONS

84       See lttng(1) for GENERAL OPTIONS.
85
86   Tracing domain
87       One of:
88
89       -k, --kernel
90           Create or enable channels in the Linux kernel domain.
91
92       -u, --userspace
93           Create or enable channels in the user space domain.
94
95   Recording target
96       -s SESSION, --session=SESSION
97           Create or enable channels in the recording session named SESSION
98           instead of the current recording session.
99
100   Buffering scheme
101       One of:
102
103       --buffers-global
104           Allocate a single set of ring buffers for the whole system.
105
106           Only available with the --kernel option.
107
108           As of LTTng 2.13.9, this is the default buffering scheme for the
109           Linux kernel tracing domain, but this may change in the future.
110
111       --buffers-pid
112           Allocate one set of ring buffers (one per CPU) for each
113           instrumented process of:
114
115           If you connect to the root session daemon
116               All Unix users.
117
118               See the “Session daemon connection” section of lttng(1) to
119               learn how a user application connects to a session daemon.
120
121           Otherwise
122               Your Unix user.
123
124           Only available with the --userspace option.
125
126       --buffers-uid
127           Allocate one set of ring buffers (one per CPU) shared by all the
128           instrumented processes of:
129
130           If you connect to the root session daemon
131               Each Unix user.
132
133               See the “Session daemon connection” section of lttng(1) to
134               learn how a user application connects to a session daemon.
135
136           Otherwise
137               Your Unix user.
138
139           Only available with the --userspace option.
140
141           As of LTTng 2.13.9, this is the default buffering scheme for the
142           user space tracing domain, but this may change in the future.
143
144   Event record loss mode
145       --blocking-timeout=TIMEOUTUS
146           Set the channel’s blocking timeout value to TIMEOUTUS µs for
147           instrumented applications executed with a set
148           LTTNG_UST_ALLOW_BLOCKING environment variable.
149
150           TIMEOUTUS is one of:
151
152           0 (default)
153               Do not block (non-blocking mode).
154
155           inf
156               Block forever until a sub-buffer is available to write the
157               event record.
158
159           N, a positive value
160               Wait for at most N µs when trying to write to a sub-buffer.
161               After N µs, discard the event record.
162
163           This option is only available with both the --userspace and
164           --discard options.
165
166       One of:
167
168       --discard
169           Discard event records when there’s no available sub-buffer.
170
171           As of LTTng 2.13.9, this is the default event record loss mode, but
172           this may change in the future.
173
174       --overwrite
175           Overwrite the whole sub-buffer containing the oldest event records
176           when there’s no available sub-buffer (flight recorder mode).
177
178   Sub-buffers
179       --num-subbuf=COUNT
180           Use COUNT sub-buffers per ring buffer.
181
182           The effective value is COUNT rounded up to the next power of two.
183
184           Default values:
185
186           --userspace and --buffers-uid options
187               4
188
189           --userspace and --buffers-pid options
190               4
191
192           --kernel and --buffers-global options
193               4
194
195           metadata channel
196               2
197
198       --output=TYPE
199           Set channel’s output type to TYPE.
200
201           TYPE is one of:
202
203           mmap
204               Share ring buffers between the tracer and the consumer daemon
205               with the mmap(2) system call.
206
207           splice
208               Share ring buffers between the tracer and the consumer daemon
209               with the splice(2) system call.
210
211               Only available with the --kernel option.
212
213           Default values:
214
215           --userspace and --buffers-uid options
216               mmap
217
218           --userspace and --buffers-pid options
219               mmap
220
221           --kernel and --buffers-global options
222               splice
223
224           metadata channel
225               mmap
226
227       --subbuf-size=SIZE
228           Set the size of each sub-buffer to SIZE bytes.
229
230           The effective value is SIZE rounded up to the next power of two.
231
232           The k (KiB), M (MiB), and G (GiB) suffixes are supported.
233
234           The minimum sub-buffer size, for each tracer, is the maximum value
235           between the default below and the system page size (see getconf(1)
236           with the PAGE_SIZE variable).
237
238           Default values:
239
240           --userspace and --buffers-uid options
241               524288
242
243           --userspace and --buffers-pid options
244               16384
245
246           --kernel and --buffers-global options
247               1048576
248
249           metadata channel
250               4096
251
252   Trace files
253       --tracefile-count=COUNT
254           Limit the number of trace files which LTTng writes for this channel
255           to COUNT.
256
257           COUNT set to 0 means “unlimited”.
258
259           Default: 0.
260
261           You must also use the --tracefile-size option with this option.
262
263       --tracefile-size=SIZE
264           Set the maximum size of each trace file which LTTng writes for this
265           channel to SIZE bytes.
266
267           SIZE set to 0 means “unlimited”.
268
269           Default: 0.
270
271           Note
272               Data streams which LTTng writes for a channel configured with
273               this option may inaccurately report discarded event records as
274               of CTF 1.8.
275
276   Timers
277       --monitor-timer=PERIODUS
278           Set the period of the monitor timer of the channel to PERIODUS µs.
279
280           Set PERIODUS to 0 to disable the monitor timer.
281
282           Default values:
283
284           --userspace and --buffers-uid options
285               1000000
286
287           --userspace and --buffers-pid options
288               1000000
289
290           --kernel and --buffers-global options
291               1000000
292
293       --read-timer=PERIODUS
294           Set the period of the read timer of the channel to PERIODUS µs.
295
296           Set PERIODUS to 0 to disable the read timer.
297
298           Default values:
299
300           --userspace and --buffers-uid options
301               0
302
303           --userspace and --buffers-pid options
304               0
305
306           --kernel and --buffers-global options
307               200000
308
309           metadata channel
310               0
311
312       --switch-timer=PERIODUS
313           Set the period of the switch timer of the channel to PERIODUS µs.
314
315           Set PERIODUS to 0 to disable the switch timer.
316
317           Default values:
318
319           --userspace and --buffers-uid options
320               0
321
322           --userspace and --buffers-pid options
323               0
324
325           --kernel and --buffers-global options
326               0
327
328           metadata channel
329               0
330
331   Program information
332       -h, --help
333           Show help.
334
335           This option attempts to launch /usr/bin/man to view this manual
336           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
337           environment variable.
338
339       --list-options
340           List available command options and quit.
341

EXIT STATUS

343       0
344           Success
345
346       1
347           Command error
348
349       2
350           Undefined command
351
352       3
353           Fatal error
354
355       4
356           Command warning (something went wrong during the command)
357

ENVIRONMENT

359       LTTNG_ABORT_ON_ERROR
360           Set to 1 to abort the process after the first error is encountered.
361
362       LTTNG_HOME
363           Path to the LTTng home directory.
364
365           Defaults to $HOME.
366
367           Useful when the Unix user running the commands has a non-writable
368           home directory.
369
370       LTTNG_MAN_BIN_PATH
371           Absolute path to the manual pager to use to read the LTTng
372           command-line help (with lttng-help(1) or with the --help option)
373           instead of /usr/bin/man.
374
375       LTTNG_SESSION_CONFIG_XSD_PATH
376           Path to the directory containing the session.xsd recording session
377           configuration XML schema.
378
379       LTTNG_SESSIOND_PATH
380           Absolute path to the LTTng session daemon binary (see lttng-
381           sessiond(8)) to spawn from the lttng-create(1) command.
382
383           The --sessiond-path general option overrides this environment
384           variable.
385

FILES

387       $LTTNG_HOME/.lttngrc
388           Unix user’s LTTng runtime configuration.
389
390           This is where LTTng stores the name of the Unix user’s current
391           recording session between executions of lttng(1).  lttng-create(1)
392           and lttng-set-session(1) set the current recording session.
393
394       $LTTNG_HOME/lttng-traces
395           Default output directory of LTTng traces in local and snapshot
396           modes.
397
398           Override this path with the --output option of the lttng-create(1)
399           command.
400
401       $LTTNG_HOME/.lttng
402           Unix user’s LTTng runtime and configuration directory.
403
404       $LTTNG_HOME/.lttng/sessions
405           Default directory containing the Unix user’s saved recording
406           session configurations (see lttng-save(1) and lttng-load(1)).
407
408       /usr/local/etc/lttng/sessions
409           Directory containing the system-wide saved recording session
410           configurations (see lttng-save(1) and lttng-load(1)).
411
412       Note
413           $LTTNG_HOME defaults to the value of the HOME environment variable.
414

EXAMPLES

416       Example 1. Create a Linux kernel channel with default attributes in the
417       current recording session.
418
419           The following command line only creates a new channel if my-channel
420           doesn’t name an existing Linux kernel channel in the current
421           recording session.
422
423               $ lttng enable-channel --kernel my-channel
424
425       Example 2. Create a user space channel with a per-process buffering
426       scheme in a specific recording session.
427
428           See the --session and --buffers-pid options.
429
430               $ lttng enable-channel --session=my-session --userspace \
431                                      --buffers-pid my-channel
432
433       Example 3. Create a Linux kernel channel in the current recording
434       session with four 32-MiB sub-buffers per ring buffer.
435
436           See the --num-subbuf and --subbuf-size options.
437
438               $ lttng enable-channel --kernel my-channel \
439                                      --num-subbuf=4 --subbuf-size=32M
440
441       Example 4. Create a user space channel in the current recording session
442       with trace file rotation.
443
444           See the --tracefile-count and --tracefile-size options.
445
446               $ lttng enable-channel --userspace my-channel \
447                                      --tracefile-count=16 --tracefile-size=8M
448
449       Example 5. Enable two user space channels of a specific recording
450       session.
451
452               $ lttng enable-channel --session=my-session --userspace \
453                                      canal-d,rds
454

RESOURCES

456       •   LTTng project website <https://lttng.org>
457
458       •   LTTng documentation <https://lttng.org/docs>
459
460       •   LTTng bug tracker <https://bugs.lttng.org>
461
462       •   Git repositories <https://git.lttng.org>
463
464       •   GitHub organization <https://github.com/lttng>
465
466       •   Continuous integration <https://ci.lttng.org/>
467
468       •   Mailing list <https://lists.lttng.org/> for support and
469           development: lttng-dev@lists.lttng.org
470
471       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
472

COPYRIGHT

474       This program is part of the LTTng-tools project.
475
476       LTTng-tools is distributed under the GNU General Public License
477       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
478       See the LICENSE <https://github.com/lttng/lttng-
479       tools/blob/master/LICENSE> file for details.
480

THANKS

482       Special thanks to Michel Dagenais and the DORSAL laboratory
483       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
484       the LTTng journey.
485
486       Also thanks to the Ericsson teams working on tracing which helped us
487       greatly with detailed bug reports and unusual test cases.
488