The following command line only creates a new channel if my-channel
doesn’t name an existing Linux kernel channel in the current recording
session.
$
lttng enable-channel --kernel my-channel
lttng-enable-channel — Create or enable LTTng channels
Create a Linux kernel channel:
lttng [GENERAL OPTIONS] enable-channel--kernel
[--discard
|--overwrite
] [--output
=(mmap | splice)] [--subbuf-size
=SIZE
] [--num-subbuf
=COUNT
] [--switch-timer
=PERIODUS
] [--read-timer
=PERIODUS
] [--monitor-timer
=PERIODUS
] [--buffers-global
] [--tracefile-size
=SIZE
[--tracefile-count
=COUNT
]] [--session
=SESSION
]CHANNEL
Create a user space channel:
lttng [GENERAL OPTIONS] enable-channel--userspace
[--overwrite
| [--discard
]--blocking-timeout
=TIMEOUTUS
] [--output
=mmap] [--buffers-uid
|--buffers-pid
] [--subbuf-size
=SIZE
] [--num-subbuf
=COUNT
] [--switch-timer
=PERIODUS
] [--read-timer
=PERIODUS
] [--monitor-timer
=PERIODUS
] [--tracefile-size
=SIZE
[--tracefile-count
=COUNT
]] [--session
=SESSION
]CHANNEL
Enable channel(s):
lttng [GENERAL OPTIONS] enable-channel (--userspace
|--kernel
) [--session
=SESSION
]CHANNEL
[,CHANNEL
]…
The lttng enable-channel
command does one of:
Create a channel named CHANNEL
.
Enable one or more disabled channels named CHANNEL
(non-option argument, comma-separated).
See lttng-concepts(7) to learn more about channels.
The channel(s) to create or enable belong to:
--session
=SESSION
option
The recording session named SESSION
.
--session
option
The current recording session (see lttng-concepts(7) to learn more about the current recording session).
Note:The lttng-enable-event(1) command can automatically create a default channel when no channel exists for the provided tracing domain.
See the “EXAMPLES” section below for usage examples.
List the channels of a given recording session with the lttng-list(1) and lttng-status(1) commands.
Disable an enabled channel with the lttng-disable-channel(1) command.
Important:As of LTTng 2.13, you may not perform the following
operations with the enable-channel
command:
Change an attribute of an existing channel.
Enable a disabled channel once its recording session has been active (started; see lttng-start(1)) at least once.
Create a channel once its recording session has been active at least once.
Create a user space channel with a given buffering scheme
(--buffers-uid
or --buffers-pid
options) and create a
second user space channel with a different buffering scheme in the
same recording session.
See lttng(1) for GENERAL OPTIONS.
One of:
-k
, --kernel
Create or enable channels in the Linux kernel domain.
-u
, --userspace
Create or enable channels in the user space domain.
One of:
--buffers-global
Allocate a single set of ring buffers for the whole system.
Only available with the --kernel
option.
As of LTTng 2.13, this is the default buffering scheme for the Linux kernel tracing domain, but this may change in the future.
--buffers-pid
Allocate one set of ring buffers (one per CPU) for each instrumented process of:
All Unix users.
See the “Session daemon connection” section of lttng(1) to learn how a user application connects to a session daemon.
Your Unix user.
Only available with the --userspace
option.
--buffers-uid
Allocate one set of ring buffers (one per CPU) shared by all the instrumented processes of:
Each Unix user.
See the “Session daemon connection” section of lttng(1) to learn how a user application connects to a session daemon.
Your Unix user.
Only available with the --userspace
option.
As of LTTng 2.13, this is the default buffering scheme for the user space tracing domain, but this may change in the future.
--blocking-timeout
=TIMEOUTUS
Set the channel’s blocking timeout value to TIMEOUTUS
µs
for instrumented applications executed with a set
LTTNG_UST_ALLOW_BLOCKING
environment variable.
TIMEOUTUS
is one of:
0
(default)
Do not block (non-blocking mode).
inf
Block forever until a sub-buffer is available to write the event record.
N
, a positive value
Wait for at most N
µs when trying to write to a sub-buffer.
After N
µs, discard the event record.
This option is only available with both the --userspace
and
--discard
options.
One of:
--discard
Discard event records when there’s no available sub-buffer.
As of LTTng 2.13, this is the default event record loss mode, but this may change in the future.
--overwrite
Overwrite the whole sub-buffer containing the oldest event records when there’s no available sub-buffer (flight recorder mode).
--num-subbuf
=COUNT
Use COUNT
sub-buffers per ring buffer.
The effective value is COUNT
rounded up to the next power of two.
Default values:
--userspace
and --buffers-uid
options
4
--userspace
and --buffers-pid
options
4
--kernel
and --buffers-global
options
4
metadata
channel
2
--output
=TYPE
Set channel’s output type to TYPE
.
TYPE
is one of:
mmap
Share ring buffers between the tracer and the consumer daemon with the mmap(2) system call.
splice
Share ring buffers between the tracer and the consumer daemon with the splice(2) system call.
Only available with the --kernel
option.
Default values:
--userspace
and --buffers-uid
options
mmap
--userspace
and --buffers-pid
options
mmap
--kernel
and --buffers-global
options
splice
metadata
channel
mmap
--subbuf-size
=SIZE
Set the size of each sub-buffer to SIZE
bytes.
The effective value is SIZE
rounded up to the next power of two.
The k
(KiB), M
(MiB), and G
(GiB) suffixes are
supported.
The minimum sub-buffer size, for each tracer, is the maximum value
between the default below and the system page size (see getconf(1)
with the PAGE_SIZE
variable).
Default values:
--userspace
and --buffers-uid
options
524288
--userspace
and --buffers-pid
options
16384
--kernel
and --buffers-global
options
1048576
metadata
channel
4096
--tracefile-count
=COUNT
Limit the number of trace files which LTTng writes for this channel
to COUNT
.
COUNT
set to 0
means “unlimited”.
Default: 0
.
You must also use the --tracefile-size
option with this option.
--tracefile-size
=SIZE
Set the maximum size of each trace file which LTTng writes for
this channel to SIZE
bytes.
SIZE
set to 0
means “unlimited”.
Default: 0
.
Note:Data streams which LTTng writes for a channel configured with this option may inaccurately report discarded event records as of CTF 1.8.
--monitor-timer
=PERIODUS
Set the period of the monitor timer of the channel to
PERIODUS
µs.
Set PERIODUS
to 0
to disable the monitor timer.
Default values:
--userspace
and --buffers-uid
options
1000000
--userspace
and --buffers-pid
options
1000000
--kernel
and --buffers-global
options
1000000
--read-timer
=PERIODUS
Set the period of the read timer of the channel to
PERIODUS
µs.
Set PERIODUS
to 0
to disable the read timer.
Default values:
--userspace
and --buffers-uid
options
0
--userspace
and --buffers-pid
options
0
--kernel
and --buffers-global
options
200000
metadata
channel
0
--switch-timer
=PERIODUS
Set the period of the switch timer of the channel to
PERIODUS
µs.
Set PERIODUS
to 0
to disable the switch timer.
Default values:
--userspace
and --buffers-uid
options
0
--userspace
and --buffers-pid
options
0
--kernel
and --buffers-global
options
0
metadata
channel
0
-h
, --help
Show help.
This option attempts to launch /usr/bin/man
to view this manual page.
Override the manual pager path with the LTTNG_MAN_BIN_PATH
environment
variable.
--list-options
List available command options and quit.
Success
Command error
Undefined command
Fatal error
Command warning (something went wrong during the command)
LTTNG_ABORT_ON_ERROR
Set to 1
to abort the process after the first error is
encountered.
LTTNG_HOME
Path to the LTTng home directory.
Defaults to $HOME
.
Useful when the Unix user running the commands has a non-writable home directory.
LTTNG_MAN_BIN_PATH
Absolute path to the manual pager to use to read the LTTng
command-line help (with lttng-help(1) or with the
--help
option) instead of /usr/bin/man
.
LTTNG_SESSION_CONFIG_XSD_PATH
Path to the directory containing the session.xsd
recording session
configuration XML schema.
LTTNG_SESSIOND_PATH
Absolute path to the LTTng session daemon binary (see lttng-sessiond(8)) to spawn from the lttng-create(1) command.
The --sessiond-path
general option overrides this environment
variable.
$LTTNG_HOME/.lttngrc
Unix user’s LTTng runtime configuration.
This is where LTTng stores the name of the Unix user’s current recording session between executions of lttng(1). lttng-create(1) and lttng-set-session(1) set the current recording session.
$LTTNG_HOME/lttng-traces
Default output directory of LTTng traces in local and snapshot modes.
Override this path with the --output
option of the
lttng-create(1) command.
$LTTNG_HOME/.lttng
Unix user’s LTTng runtime and configuration directory.
$LTTNG_HOME/.lttng/sessions
Default directory containing the Unix user’s saved recording session configurations (see lttng-save(1) and lttng-load(1)).
/etc/lttng/sessions
Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).
Note:$LTTNG_HOME
defaults to the value of the HOME
environment
variable.
Example:Create a Linux kernel channel with default attributes in the current recording session.
The following command line only creates a new channel if my-channel
doesn’t name an existing Linux kernel channel in the current recording
session.
$
lttng enable-channel --kernel my-channel
Example:Create a user space channel with a per-process buffering scheme in a specific recording session.
See the --session
and --buffers-pid
options.
$
lttng enable-channel --session=my-session --userspace \ --buffers-pid my-channel
Example:Create a Linux kernel channel in the current recording session with four 32-MiB sub-buffers per ring buffer.
See the --num-subbuf
and --subbuf-size
options.
$
lttng enable-channel --kernel my-channel \ --num-subbuf=4 --subbuf-size=32M
Example:Create a user space channel in the current recording session with trace file rotation.
See the --tracefile-count
and --tracefile-size
options.
$
lttng enable-channel --userspace my-channel \ --tracefile-count=16 --tracefile-size=8M
Example:Enable two user space channels of a specific recording session.
$
lttng enable-channel --session=my-session --userspace \ canal-d,rds
Mailing list for support and
development: lttng-dev@lists.lttng.org
IRC channel: #lttng
on irc.oftc.net
This program is part of the LTTng-tools project.
LTTng-tools is distributed under the
GNU General
Public License version 2. See the
LICENSE
file
for details.
Special thanks to Michel Dagenais and the DORSAL laboratory at École Polytechnique de Montréal for the LTTng journey.
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases.