lttng-sessiond - Man Page

LTTng session daemon

Synopsis

lttng-sessiond [--background | --daemonize] [--sig-parent]
               [--config=PATH] [--group=GROUP] [--load=PATH]
               [--default-trace-format=(ctf-1.8 | ctf-2)]
               [--agent-tcp-port=PORT] [--pidfile=PATH]
               [--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]
               [--spawn-consumers]
               [--event-notifier-error-buffer-size-kernel=SLOTS]
               [--event-notifier-error-buffer-size-userspace=SLOTS]
               [--quiet | [--verbose]... [--verbose-consumer]]

Description

The Linux Trace Toolkit: next generation <https://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).

An LTTng session daemon, lttng-sessiond, is a program which:

Manages recording sessions (see lttng-concepts(7) to learn more about recording sessions).
Controls the various components (like tracers and consumer daemons) of LTTng.
Sends asynchronous notifications to user applications.

A session daemon receives commands from the lttng(1) command-line tool, as well as from any user application linked with the LTTng control library (liblttng-ctl).

Each Unix user may have its own independent running session daemon. However, the lttng(1) tool must connect to the session daemon of the root user (the root session daemon) to control Linux kernel tracing.

When you start lttng-sessiond as the root Unix user, a non-root Unix user can connect to it if it’s part of the Unix tracing group. By default, the name of the tracing group is tracing. Override the tracing group name with the --group option.

See the “Session daemon connection” section of lttng(1) to learn how a user application connects to a session daemon.

A session daemon manages trace data consumer daemons, spawning them when necessary. You do NOT need to manage the consumer daemons yourself.

By default, lttng-sessiond doesn’t start as a daemon. Make it a daemon with the --daemonize or --background option. With those options, lttng-sessiond ensures the daemon is ready to receive client commands before it exits. Make lttng-sessiond write its process ID to a file with the --pidfile option.
Note

The LTTng project recommends that you start the session daemon at boot time for stable and long-term tracing.

Note

For an unprivileged Unix 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 are two file descriptors per CPU as well as one socket for bidirectional communication.

For the root user, the limit is usually 65,535.

Daemon configuration

When you run lttng-sessiond, it configures itself from, in this order:

The INI configuration file /usr/local/etc/lttng/lttng.conf, if any.
The INI configuration file $LTTNG_HOME/.lttng/lttng.conf, if any.
$LTTNG_HOME defaults to $HOME.
With the --config=PATH option: the INI configuration file PATH.
The command-line options.

Each step can override a previous configuration property.

In INI configuration files, the session daemon only reads the properties under the sessiond INI section. Each INI property is:

Key

The long name of a command-line option to set (see the “Options” section below).

Value

The selected command-line option accepts an argument

Option argument (string).

The selected command-line option is a switch

true, yes, on: Enable the option.
false, no, off: Disable the option.

INI configuration file example:

[sessiond]
daemonize=yes
default-trace-format=ctf-1.8
extra-kmod-probes=my-driver,other-module

Recording session configuration loading

When the session daemon starts, it loads recording session configurations from:

Without the --load option

In this order:

All the files in $LTTNG_HOME/.lttng/sessions/auto.
$LTTNG_HOME defaults to $HOME.
All the files in /usr/local/etc/lttng/sessions/auto.

lttng-sessiond only loads recording session configuration files from the directories above if its UID and their UID are the same.

With the --load=PATH option

PATH is a directory: All the files in PATH.
PATH is a file: The file PATH.

Options

General daemon configuration

-b, --background

Start as a Unix daemon, but keep file descriptors (console) open.

With this option, lttng-sessiond ensures the daemon is ready to receive client commands before it exits.

Use the --daemonize option instead to close the file descriptors.

-f PATH, --config=PATH

Configure the daemon using the INI configuration file PATH in addition to the default configuration files and the command-line options.

See the “Daemon configuration” section above.

-d, --daemonize

Start as a Unix daemon and close file descriptors (console).

With this option, lttng-sessiond ensures the daemon is ready to receive client commands before it exits.

Use the --background option instead to keep the file descriptors open.

--default-trace-format=FORMAT

Set the default trace format of recording sessions to FORMAT.

FORMAT is one of:

ctf-1.8: CTF 1.8 <https://diamon.org/ctf/v1.8.3/> (legacy).
ctf-2: CTF 2 <https://diamon.org/ctf/> (preferred).

When a user application creates a recording session using the lttng-create(1) command or the liblttng-ctl API without explicitly specifying a trace format, lttng-sessiond uses FORMAT.

Default: ctf-2.

See also the LTTNG_SESSIOND_DEFAULT_TRACE_FORMAT environment variable.

-g GROUP, --group=GROUP

Set the Unix tracing group to GROUP instead of tracing.

This option is only meaningful when the root Unix user starts lttng-sessiond.

Members of the Unix tracing group may connect to the root session daemon and, therefore, control LTTng kernel tracing.

-l PATH, --load=PATH

Load recording session configurations from PATH, either a directory or a file, instead of loading them from the default search directories.

See the “Recording session configuration loading” section above.

-p PATH, --pidfile=PATH

Write the process ID (PID) of the lttng-sessiond process to PATH.

Such a file contains the textual PID (decimal) followed with a newline.

-S, --sig-parent

Send the USR1 signal to the parent process to notify readiness.

You can also use the --daemonize or --background option, in which case lttng-sessiond ensures the daemon is ready to receive client commands before it exits.

--spawn-consumers

Start the consumer daemon(s) at session daemon startup instead of starting them on an as-needed basis.

Linux kernel tracing

At most one of:

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

For each PROBE argument, load the LTTng kernel probe module named lttng-probe-PROBE.ko, in addition to loading the default LTTng kernel probe modules.

See also the LTTNG_EXTRA_KMOD_PROBES environment variable.

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

Only load, for each PROBE argument, the LTTng kernel probe module named lttng-probe-PROBE.ko, instead of loading the default LTTng kernel probe modules.

See also the LTTNG_KMOD_PROBES environment variable.

--no-kernel

Disable Linux kernel tracing.

Paths and ports

--agent-tcp-port=PORT

Listen on TCP port PORT for agent application registration instead of a port within the range [5345, 5354]).

-a PATH, --apps-sock=PATH

Set the application Unix socket path to PATH.

This option sets the application Unix socket path even if you set the LTTNG_UST_CTL_PATH environment variable.

-c PATH, --client-sock=PATH

Set the client Unix socket path to PATH.

--consumerd32-libdir=PATH

Set the 32-bit consumer daemon library directory to PATH.

See also the LTTNG_CONSUMERD32_LIBDIR environment variable.

--consumerd32-path=PATH

Set the 32-bit consumer daemon binary path to PATH.

See also the LTTNG_CONSUMERD32_BIN environment variable.

--consumerd64-libdir=PATH

Set the 64-bit consumer daemon library directory to PATH.

See also the LTTNG_CONSUMERD64_LIBDIR environment variable.

--consumerd64-path=PATH

Set the 64-bit consumer daemon binary path to PATH.

See also the LTTNG_CONSUMERD64_BIN environment variable.

--kconsumerd-cmd-sock=PATH

Set the command Unix socket path of the Linux kernel consumer daemon to PATH.

--kconsumerd-err-sock=PATH

Set the error Unix socket path of the Linux kernel consumer daemon to PATH.

--ustconsumerd32-cmd-sock=PATH

Set the Unix socket path of the 32-bit consumer daemon command to PATH.

--ustconsumerd64-cmd-sock=PATH

Set the Unix socket path of the 64-bit consumer daemon command to PATH.

--ustconsumerd32-err-sock=PATH

Set the Unix socket path of the 32-bit consumer daemon error to PATH.

--ustconsumerd64-err-sock=PATH

Set the Unix socket path of the 64-bit consumer daemon error to PATH.

Buffer size of event notifier error counters

--event-notifier-error-buffer-size-kernel=SLOTS: Set the size of the kernel event notifier error counter buffers to SLOTS slots.
--event-notifier-error-buffer-size-userspace=SLOTS: Set the size of the user space event notifier error counter buffers to SLOTS slots.

As of LTTng 2.16.0, a slot is a 32-bit counter, but this may change in the future.

Verbosity

-q, --quiet

Suppress all messages, including warnings and errors.

You may NOT use this option with the --verbose and --verbose-consumer options.

-v, --verbose

Increase verbosity.

Specify this option up to three times to get more levels of verbosity.

You may NOT use this option with the --quiet option.

--verbose-consumer

Increase the verbosity of the consumer daemons which this session daemon spawns.

You may NOT use this option with the --quiet option.

Program information

-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.

-V, --version

Show version and quit.

Exit Status

0: Success
1: Error
3: Fatal error

Environment

LTTNG_ABORT_ON_ERROR

Set to 1 to abort the process after the first error is encountered.

LTTNG_APP_SOCKET_TIMEOUT

Timeout (in seconds) of the application socket when sending/receiving commands.

After this period of time, lttng-sessiond unregisters the application.

Set to 0 or -1 to set an infinite timeout.

Default: 5.

LTTNG_CONSUMERD32_BIN

32-bit consumer daemon binary path.

The --consumerd32-path option overrides this environment variable.

LTTNG_CONSUMERD32_LIBDIR

32-bit consumer daemon library directory path.

The --consumerd32-libdir option overrides this environment variable.

LTTNG_CONSUMERD64_BIN

64-bit consumer daemon binary path.

The --consumerd64-path option overrides this environment variable.

LTTNG_CONSUMERD64_LIBDIR

64-bit consumer daemon library directory path.

The --consumerd64-libdir option overrides this environment variable.

LTTNG_DEBUG_NOCLONE

Set to 1 to disable the use of clone(2)/fork(2).

Setting this environment variable is considered insecure, but it’s required to allow debuggers to work with lttng-sessiond on some operating systems.

LTTNG_EXTRA_KMOD_PROBES

Extra LTTng kernel probe modules to load.

See the --extra-kmod-probes option which overrides this environment variable.

LTTNG_KMOD_PROBES

Exclusive LTTng kernel probe modules to load.

See the --kmod-probes option which overrides this environment variable.

LTTNG_NETWORK_SOCKET_TIMEOUT

Socket connection, receive, and send timeout (milliseconds).

Set to 0 or -1 to use the timeout of the operating system (default).

LTTNG_RUNDIR

The directory containing the control files instead of:

Session daemon of the root user (root session daemon)

The value of the --with-lttng-system-rundir option when configuring the build of the project (/var/run/lttng by default).

Other session daemon

$LTTNG_HOME/.lttng

This environment variable is particularly useful to run multiple root session daemons.

LTTNG_SESSION_CONFIG_XSD_PATH

Recording session configuration XML schema definition (XSD) path.

LTTNG_SESSIOND_DEFAULT_TRACE_FORMAT

Default trace format of recording sessions.

The value is either ctf-1.8 or ctf-2.
Note

The --default-trace-format option overrides this environment variable.

LTTNG_UST_CTL_PATH

Colon-delimited paths of the directories where lttng-sessiond places:

The application registration Unix socket.
Note
The --apps-sock option overrides this specific path.
The "wait" shared memory files to wake up instrumented applications that are waiting for a session daemon to start.
The agent port file.
This file contains the TCP port the agents must connect to to enable LTTng tracing.

Any such directory must exist when you start lttng-sessiond.

As of LTTng 2.16.0:

lttng-sessiond ignores any path after the first colon (:) and prints a warning.
You cannot escape a colon within a specific path.

When tracing an application, start it with the LTTNG_UST_APP_PATH environment variable set to the same value as this environment variable.

If not set, the default directory path is the effective control file directory (see the LTTNG_RUNDIR environment variable).

Files

$LTTNG_HOME/.lttng

Unix user’s LTTng runtime and configuration directory.

$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/sessions/auto

Directory from which lttng-sessiond loads Unix user recording session configurations when starting.

See the “Recording session configuration loading” section above to learn more.

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

Directory from which lttng-sessiond loads system-wide recording session configurations when starting.

See the “Recording session configuration loading” section above to learn more.

$LTTNG_HOME/.lttng/lttng.conf

Unix user’s LTTng daemon INI configuration file.

See the “Daemon configuration” section above to learn more.

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

System-wide LTTng daemon INI configuration file.