LTTNG-SESSIOND(8)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

💖 LTTng Manual — lttng-sessiond(8) 💖

okay bestie, welcome to the lttng-sessiond manual page, part 1 of 3!! this is the LTTng session daemon and she is the main character of your tracing setup, fr fr. grab a snack 🍓

✨ NAME ✨

lttng-sessiond — the 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]
               [--event-notifier-error-buffer-size-kernel=SLOTS]
               [--event-notifier-error-buffer-size-userspace=SLOTS]
               [--quiet | [--verbose]... [--verbose-consumer]]

like… look at her. iconic. every single one of those flags gets its own moment further down, don't you worry 🫶

✨ 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. yes she's that girl 🌈

LTTng consists of Linux kernel modules (for Linux kernel tracing) and dynamically loaded libraries (for user application and library tracing). two whole vibes, one project.

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. not me sliding into your app's DMs 💌

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. kernel tracing is root's territory, no cap 👑

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. she handles her own staff 💅

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. trust the process bestie.
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. last one standing wins, periodt ✨

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

see how cute and simple that is 🎀

🦋 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. same UID or it's not happening, we don't do that here 🙈
  • With the --load=PATH option
    • PATH is a directory
      • All the files in PATH.
    • PATH is a file
      • The file PATH.

okay that's part 1 bestie, there is SO much more coming 💖

✨ OPTIONS ✨

🛠️ General daemon configuration

  • -b, --background — bestie, this starts lttng-sessiond as a Unix daemon but keeps the file descriptors (aka the console) open. With this one, lttng-sessiond makes sure the daemon is ready to receive client commands before it exits, so you're never out here yelling into the void. If you'd rather close those file descriptors, use the --daemonize option instead. 💅
  • -f PATH, --config=PATH — configures the daemon using the INI configuration file PATH on top of the default configuration files and the command-line options. Check the "Daemon configuration" section above for the tea. 🎀
  • -d, --daemonize — starts as a Unix daemon and closes the file descriptors (console). Same deal as above: lttng-sessiond ensures the daemon is ready to receive client commands before it exits. Want the file descriptors kept open instead? That's the --background option's whole moment.
  • --default-trace-format=FORMAT — sets the default trace format of recording sessions to FORMAT. And FORMAT is one of these two icons:

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

Default: ctf-2. Periodt.

Also peep the LTTNG_SESSIOND_DEFAULT_TRACE_FORMAT environment variable. 👀

  • -g GROUP, --group=GROUP — sets the Unix tracing group to GROUP instead of tracing. This one is only meaningful when the root Unix user starts lttng-sessiond, no cap. Members of the Unix tracing group may connect to the root session daemon and therefore control LTTng kernel tracing. Big power, handle with care 🫶
  • -l PATH, --load=PATH — loads 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 for the full lore.
  • -p PATH, --pidfile=PATH — writes the process ID (PID) of the lttng-sessiond process to PATH. Such a file contains the textual PID (decimal) followed with a newline. Very tidy, very demure. 📝
  • -S, --sig-parent — sends the USR1 signal to the parent process to notify readiness. You can also use the --daemonize or --background option instead, in which case lttng-sessiond makes sure the daemon is ready to receive client commands before it exits. ✨

🐧 Linux kernel tracing

At most one of these, bestie — pick your fighter:

  • --extra-kmod-probes=PROBE[,PROBE]... — for each PROBE argument, loads the LTTng kernel probe module named lttng-probe-PROBE.ko, in addition to loading the default LTTng kernel probe modules.

Also see the LTTNG_EXTRA_KMOD_PROBES environment variable. 💖

  • --kmod-probes=PROBE[,PROBE]... — only loads, for each PROBE argument, the LTTng kernel probe module named lttng-probe-PROBE.ko, instead of loading the default LTTng kernel probe modules. Exclusive vibes only.

Also see the LTTNG_KMOD_PROBES environment variable. 💖

  • --no-kernel — disables Linux kernel tracing. That's it, that's the whole thing. 🚫

🔌 Paths and ports

  • --agent-tcp-port=PORT — listens on TCP port PORT for agent application registration instead of a port within the range [5345, 5354]).
  • -a PATH, --apps-sock=PATH — sets the application Unix socket path to PATH. And listen: this option sets the application Unix socket path even if you set the LTTNG_UST_CTL_PATH environment variable. She overrides, she does not negotiate. 💅
  • -c PATH, --client-sock=PATH — sets the client Unix socket path to PATH.
  • --consumerd32-libdir=PATH — sets the 32-bit consumer daemon library directory to PATH. Also see LTTNG_CONSUMERD32_LIBDIR. ✨
  • --consumerd32-path=PATH — sets the 32-bit consumer daemon binary path to PATH. Also see LTTNG_CONSUMERD32_BIN. ✨
  • --consumerd64-libdir=PATH — sets the 64-bit consumer daemon library directory to PATH. Also see LTTNG_CONSUMERD64_LIBDIR. ✨
  • --consumerd64-path=PATH — sets the 64-bit consumer daemon binary path to PATH. Also see LTTNG_CONSUMERD64_BIN. ✨
  • --kconsumerd-cmd-sock=PATH — sets the command Unix socket path of the Linux kernel consumer daemon to PATH.
  • --kconsumerd-err-sock=PATH — sets the error Unix socket path of the Linux kernel consumer daemon to PATH.
  • --ustconsumerd32-cmd-sock=PATH — sets the Unix socket path of the 32-bit consumer daemon command to PATH.
  • --ustconsumerd64-cmd-sock=PATH — sets the Unix socket path of the 64-bit consumer daemon command to PATH.
  • --ustconsumerd32-err-sock=PATH — sets the Unix socket path of the 32-bit consumer daemon error to PATH.
  • --ustconsumerd64-err-sock=PATH — sets 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 — sets the size of the kernel event notifier error counter buffers to SLOTS slots.
  • --event-notifier-error-buffer-size-userspace=SLOTS — sets the size of the user space event notifier error counter buffers to SLOTS slots.
As of LTTng 2.15.1, a slot is a 32-bit counter, but this may change in the future. Noted, bestie, future-proofing is real. 🦋

🔊 Verbosity

  • -q, --quiet — suppresses all messages, including warnings and errors. Like, silence. You may NOT use this option with the --verbose and --verbose-consumer options, so don't even try it. 🙈
  • -v, --verbose — increases verbosity. Specify this option up to three times to get more levels of verbosity. You may NOT use this option with the --quiet option. (They are not friends. They cannot sit together. 💀)
  • --verbose-consumer — increases 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 — shows 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 — lists available command options and quits. Snackable. ✨
  • -V, --version — shows the version and quits.

🌈 EXIT STATUS 🌈

  • 0 Success. Slay. 👑
  • 1 Error.
  • 3 Fatal error. (The dramatic one. 😭)

🧚 ENVIRONMENT 🧚

  • LTTNG_ABORT_ON_ERROR — set to 1 to abort the process after the first error is encountered. One strike and she's out.
  • 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. So like… insecure but necessary, iykyk. 💅
  • 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. Iconic for the multi-daemon girlies. 👑

  • 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. No directory, no party. 🎀

As of LTTng 2.15.1:

  • 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 (the places your faves live)

  • $LTTNG_HOME/.lttng — bestie this is THE spot: your Unix user's LTTng runtime and configuration directory. everything hangs out here. 🏠
  • $LTTNG_HOME/lttng-traces — where traces go by default in local mode and snapshot mode. it's the default output directory, periodt.

Wanna send them somewhere else? Override it with the --output option of the lttng-create(1) command. it's giving "I make the rules actually". 💅

  • $LTTNG_HOME/.lttng/sessions/auto — when lttng-sessiond starts up, this is the directory it pulls your Unix user recording session configurations from. ✨

See the “Recording session configuration loading” section above to learn more (yes, the one we already went over, go look, it's all there).

  • /etc/lttng/sessions/auto — same energy but system-wide: lttng-sessiond loads system-wide recording session configurations from here when it starts.

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

  • $LTTNG_HOME/.lttng/lttng.conf — your Unix user's LTTng daemon INI configuration file. 💖

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

  • /etc/lttng/lttng.conf — the system-wide LTTng daemon INI configuration file. the big one. 👑

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

Note 🫶 $LTTNG_HOME defaults to $HOME. like, if you don't set it, that's what you get. no cap.

🌈 RESOURCES (come hang out)

This program is part of the LTTng-tools project. fr fr.

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 file (https://github.com/lttng/lttng-tools/blob/master/LICENSE) for details. iconic licensing behaviour, honestly. 💜

💐 THANKS (the shoutout section, as she deserves)

Special thanks to Michel Dagenais and the DORSAL laboratory (http://www.dorsal.polymtl.ca/) at École Polytechnique de Montréal for the LTTng journey. literal main character energy. 🎀

Also thanks to the Ericsson teams working on tracing, who helped greatly with detailed bug reports and unusual test cases. not all heroes wear capes, some of them file the weirdest repro steps imaginable and we are OBSESSED. 😭🔥

👀 SEE ALSO

and that's the whole page bestie!! 🫶 this was LTTNG-SESSIOND(8) from LTTng 2.15.1, dated 7 October 2025 — go forth and trace, you absolute legend ✨💖🌸

📦 where this page comes from