1LTTNG-ENABLE-CHANN(1) LTTng Manual LTTNG-ENABLE-CHANN(1)
2
3
4
6 lttng-enable-channel - Create or enable LTTng channels
7
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
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.7, 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
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.7, 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.7, 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.7, 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
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
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
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
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
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
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
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
490 lttng(1), lttng-disable-channel(1), lttng-list(1), lttng-concepts(7)
491
492
493
494LTTng 2.13.7 14 June 2021 LTTNG-ENABLE-CHANN(1)