SYNOPSIS

lttng-sessiond [--background | --daemonize] [--sig-parent]
[--config=PATH] [--group=GROUP] [--load=PATH]
[--agent-tcp-port=PORT]
[--apps-sock=PATH] [--client-sock=PATH]
[--no-kernel | [--kmod-probes=PROBE[,PROBE]...]
[--extra-kmod-probes=PROBE[,PROBE]...]
[--kconsumerd-err-sock=PATH]
[--kconsumerd-cmd-sock=PATH]]
[--ustconsumerd32-err-sock=PATH]
[--ustconsumerd64-err-sock=PATH]
[--ustconsumerd32-cmd-sock=PATH]
[--ustconsumerd64-cmd-sock=PATH]
[--consumerd32-path=PATH] [--consumerd32-libdir=PATH]
[--consumerd64-path=PATH] [--consumerd64-libdir=PATH]
[--quiet | [-v | -vv | -vvv] [--verbose-consumer]]

DESCRIPTION

The Linux Trace Toolkit: next generation <http://lttng.org/> is an open source software package used for correlated tracing of the Linux kernel, user applications, and user libraries.

LTTng consists of Linux kernel modules (for Linux kernel tracing) and dynamically loaded libraries (for user application and library tracing).

The LTTng session daemon is a tracing registry which allows the user to interact with multiple tracers (kernel and user space) within the same container, a tracing session. Traces can be gathered from the Linux kernel and/or from instrumented applications (see lttng-ust(3)). You can aggregate and read the events of LTTng traces using babeltrace(1).

To trace the Linux kernel, the session daemon needs to be running as root. LTTng uses a tracing group to allow specific users to interact with the root session daemon. The default tracing group name is tracing. You can use the --group option to set the tracing group name to use.

Session daemons can coexist. You can have a session daemon running as user Alice that can be used to trace her applications alongside a root session daemon or a session daemon running as user Bob.

The LTTng session daemon manages trace data consumer daemons by spawning them when necessary. You do not need to manage the consumer daemons manually.

Note

It is highly recommended to start the session daemon at boot time for stable and long-term tracing.

Automatic loading of tracing session configurations

When the session daemon starts, it automatically loads session configuration files.

The following directories are searched, non-recursively, in this order for configuration files to load on launch:

1. $LTTNG_HOME/.lttng/sessions/auto ($LTTNG_HOME defaults to $HOME)

2. /usr/local/etc/lttng/sessions/auto

Note that both the directory containing the tracing session configurations and the session daemon binary must share the same UID for the configurations to be automatically loaded.

The --load option overrides the default directories and the UID check. The session daemon simply checks if the path is accessible and tries to load every tracing session configuration in it. When this option is specified, the default directories are NOT searched for configuration files. When the option is not specified, both default directories are searched for configuration files.

If the --load option's argument is a directory, then all the tracing session configurations found in all the files in this directory are loaded. If the argument is a file, then all the tracing session configurations found in this file are loaded.

OPTIONS

Daemon configuration

-b, --background

Start as Unix daemon, but keep file descriptors (console) open. Use the --daemonize option instead to close the file descriptors.

-d, --daemonize

Start as Unix daemon, and close file descriptors (console). Use the --background option instead to keep the file descriptors open.

-f, --config=PATH

Load session daemon configuration from path PATH.

-g, --group=GROUP

Use GROUP as Unix tracing group (default: tracing).

-l, --load=PATH

Automatically load tracing session configurations from PATH, either a directory or a file, instead of loading them from the default search directories.

-S, --sig-parent

Send SIGUSR1 to parent process to notify readiness.

Note
This is used by lttng(1) to get notified when the session daemon is ready to accept commands. When building a third party tool on liblttng-ctl, this option can be very handy to synchronize the control tool and the session daemon.

Linux kernel tracing

--extra-kmod-probes=PROBE[,PROBE]...

Load specific LTTng Linux kernel modules when kernel tracing is enabled (--no-kernel option is NOT specified), in addition to loading the default list of LTTng kernel modules.

Only the name of the probe needs to be specified, without the lttng-probe- prefix and without the kernel module extension suffix. For example, specify sched to load the lttng-probe-sched.ko kernel module.

--kmod-probes=PROBE[,PROBE]...

Only load specific LTTng Linux kernel modules when kernel tracing is enabled (--no-kernel option is NOT specified).

Only the name of the probe needs to be specified, without the lttng-probe- prefix and without the kernel module extension suffix. For example, specify sched to load the lttng-probe-sched.ko kernel module.

--no-kernel

Disable Linux kernel tracing.

Paths and ports

--agent-tcp-port=PORT

Listen on TCP port PORT for agent application registrations (default: 5345).

-a, --apps-sock=PATH

Set application Unix socket path to PATH.

-c, --client-sock=PATH

Set client Unix socket path to PATH.

--consumerd32-libdir=PATH

Set 32-bit consumer daemon library directory to PATH.

--consumerd32-path=PATH

Set 32-bit consumer daemon binary path to PATH.

--consumerd64-libdir=PATH

Set 64-bit consumer daemon library directory to PATH.

--consumerd64-path=PATH

Set 64-bit consumer daemon binary path to PATH.

--kconsumerd-cmd-sock=PATH

Set Linux kernel consumer daemon's command Unix socket path to PATH.

--kconsumerd-err-sock=PATH

Set Linux kernel consumer daemon's error Unix socket path to PATH.

--ustconsumerd32-cmd-sock=PATH

Set 32-bit consumer daemon's command Unix socket path to PATH.

--ustconsumerd64-cmd-sock=PATH

Set 64-bit consumer daemon's command Unix socket path to PATH.

--ustconsumerd32-err-sock=PATH

Set 32-bit consumer daemon's error Unix socket path to PATH.

--ustconsumerd64-err-sock=PATH

Set 64-bit consumer daemon's error Unix socket path to PATH.

Verbosity

-q, --quiet

Suppress all messages, including warnings and errors.

-v, --verbose

Increase verbosity.

Three levels of verbosity are available, which are triggered by appending additional v letters to the option (that is, -vv and -vvv).

--verbose-consumer

Increase verbosity of consumer daemons spawned by this session daemon.

Program information

-h, --help

Show help.

-V, --version

Show version.

FILES

$LTTNG_HOME/.lttng

User LTTng runtime and configuration directory.

$LTTNG_HOME/lttng-traces

Default output directory of LTTng traces. This can be overridden with the --output option of the lttng-create(1) command.

$LTTNG_HOME/.lttng/sessions/auto

Directory from which user tracing configuration files are automatically loaded when the session daemon starts (see lttng-save(1) and lttng-load(1) for saving and loading tracing sessions).

/usr/local/etc/lttng/sessions/auto

Directory from which system-wide tracing configuration files are automatically loaded when the session daemon starts (see lttng-save(1) and lttng-load(1) for saving and loading tracing sessions).

$LTTNG_HOME/.lttng/lttng.conf

Default location of the session daemon configuration file (see the --config option).

/usr/local/etc/lttng/lttng.conf

System-wide location of the session daemon configuration file (see the --config option).

Note

$LTTNG_HOME defaults to $HOME when not explicitly set.

LIMITATIONS

For an unprivileged user running lttng-sessiond, the maximum number of file descriptors per process is usually 1024. This limits the number of traceable applications, since for each instrumented application, there is two file descriptors per CPU and one more socket for bidirectional communication.

For the root user, the limit is bumped to 65535. A future version will deal with this limitation.

RESOURCES

• LTTng project website <http://lttng.org>

• LTTng documentation <http://lttng.org/docs>

• Git repositories <http://git.lttng.org>

• GitHub organization <http://github.com/lttng>

• Continuous integration <http://ci.lttng.org/>

• Mailing list <http://lists.lttng.org> for support and development: [email protected]

• IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net

COPYRIGHTS

This program is part of the LTTng-tools project.

LTTng-tools is distributed under the GNU General Public License version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

THANKS

Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> 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.

AUTHORS

LTTng-tools was originally written by Mathieu Desnoyers, Julien Desfossez, and David Goulet. More people have since contributed to it.

LTTng-tools is currently maintained by Jérémie Galarneau <mailto:[email protected]>.