# lttng-sessiond

## NAME



           lttng-sessiond - LTTng 2 tracing 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_]
                          [**--quiet** | [**-v** | **-vv** | **-vvv**] [**--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).
    
           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: a port within the range [5345, 5354]).
    
           **-a** _PATH_ , **--apps-sock** =_PATH_
               Set application Unix socket path to _PATH_.
    
           **-c** _PATH_ , **--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.
    


## ENVIRONMENT VARIABLES



           Note that command-line options override their equivalent
           environment variable.
    
           **LTTNG_ABORT_ON_ERROR**
               Set to 1 to abort the process after the first error is
               encountered.
    
           **LTTNG_APP_SOCKET_TIMEOUT**
               Application socket’s timeout (seconds) when sending/receiving
               commands. After this period of time, the application is
               unregistered by the session daemon. A value of 0 or -1 means
               an infinite timeout. Default value: 5.
    
           **LTTNG_CONSUMERD32_BIN**
               32-bit consumer daemon binary path.
    
               The **--consumerd32-path** option overrides this variable.
    
           **LTTNG_CONSUMERD32_LIBDIR**
               32-bit consumer daemon library path.
    
               The **--consumerd32-libdir** option overrides this variable.
    
           **LTTNG_CONSUMERD64_BIN**
               64-bit consumer daemon binary path.
    
               The **--consumerd64-path** option overrides this variable.
    
           **LTTNG_CONSUMERD64_LIBDIR**
               64-bit consumer daemon library path.
    
               The **--consumerd64-libdir** option overrides this variable.
    
           **LTTNG_DEBUG_NOCLONE**
               Set to 1 to disable the use of **clone()** /**fork()**. Setting this
               variable is considered insecure, but it is required to allow
               debuggers to work with the session daemon on some operating
               systems.
    
           **LTTNG_EXTRA_KMOD_PROBES**
               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.
    
               The **--extra-kmod-probes** option overrides this variable.
    
           **LTTNG_KMOD_PROBES**
               Only load specific LTTng Linux kernel modules when kernel
               tracing is enabled (**--no-kernel** option is NOT specified).
    
               The **--kmod-probes** option overrides this variable.
    
           **LTTNG_NETWORK_SOCKET_TIMEOUT**
               Socket connection, receive and send timeout (milliseconds). A
               value of 0 or -1 uses the timeout of the operating system
               (default).
    
           **LTTNG_SESSION_CONFIG_XSD_PATH**
               Tracing session configuration XML schema definition (XSD)
               path.
    


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


## EXIT STATUS



           **0**
               Success
    
           **1**
               Error
    
           **3**
               Fatal error
    


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


## BUGS



           If you encounter any issue or usability problem, please report it
           on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
           tools>.
    


## RESOURCES



           •   LTTng project website <https://lttng.org>
    
           •   LTTng documentation <https://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: **lttng-dev@lists.lttng.org**
    
           •   IRC channel <irc://irc.oftc.net/lttng>: **#lttng** on **irc.oftc.net**
    


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


* * *