--- name: "lttng-sessiond" section: "8" platform: "linux" package: "lttng-tools" version: "2.13.15-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/lttng-sessiond" --- # lttng-sessiond(8) LTTng session daemon ## NAME lttng-sessiond - LTTng session daemon ## 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] [--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* \ 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)](/lttng-concepts/7.md) 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)](/lttng/1.md) 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)](/lttng/1.md) 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)](/lttng/1.md) 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. **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: 1\. The INI configuration file **/etc/lttng/lttng.conf**, if any. 2\. The INI configuration file **$LTTNG\_HOME/.lttng/lttng.conf**, if any. **$LTTNG\_HOME** defaults to **$HOME**. 3\. With the **--config**=*PATH* option: the INI configuration file *PATH*. 4\. 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 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: 1\. All the files in **$LTTNG\_HOME/.lttng/sessions/auto**. **$LTTNG\_HOME** defaults to **$HOME**. 2\. All the files in **/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. - **-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. - **-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. ### 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*. - **-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\_CONSUMERD32\_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.13.15, 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)](/clone/2.md)/[**fork**(2)](/fork/2.md). 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\_SESSION\_CONFIG\_XSD\_PATH** Recording session configuration XML schema definition (XSD) path. ## 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)](/lttng-create/1.md) 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. **/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. **/etc/lttng/lttng.conf** System-wide LTTng daemon INI configuration file. See the “Daemon configuration” section above to learn more. **Note**\ **$LTTNG\_HOME** defaults to **$HOME**. ## RESOURCES • LTTng project website \ • LTTng documentation \ • LTTng bug tracker \ • Git repositories \ • GitHub organization \ • Continuous integration \ • Mailing list \ for support and development: **lttng-dev@lists.lttng.org** • IRC channel \: **#lttng** on **irc.oftc.net** ## COPYRIGHT 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. ## THANKS 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. ## SEE ALSO [**lttng**(1)](/lttng/1.md), [**lttng-concepts**(7)](/lttng-concepts/7.md)