LTTNG-RELAYD(8)

📦
version 2.15.1 · 12 versions
, in ubuntu stonking

🎀 lttng-relayd 🎀

okay so bestie, welcome to LTTNG-RELAYD(8) — that's the page title AND the manual name, we love a two-for-one — straight out of the LTTng Manual ✨. this is part 1, so buckle up, hydrate, and let's get into it 💅

🌸 NAME 🌸

lttng-relayd — the LTTng relay daemon, aka the lil mvpp that catches your trace data 💖

✨ SYNOPSIS ✨

lttng-relayd [--background | --daemonize] [--config=PATH]
             [--control-port=URL] [--data-port=URL] [--fd-pool-size=COUNT]
             [--live-port=URL] [--dynamic-port-allocation] [--output=DIR]
             [--group=GROUP] [--verbose]... [--working-directory=DIR]
             [--group-output-by-host | --group-output-by-session] [--disallow-clear]
             [--pid-file=PATH] [--sig-parent]

🦋 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. it's giving ✨observability✨, no cap.

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

An LTTng relay daemon, lttng-relayd, is a program which receives trace data from (possibly remote) LTTng session/consumer daemons and which writes it to the local file system. so it's literally the bestie that takes the mail and files it for you 📬. The relay daemon also accepts LTTng live connections from compatible readers (for example, babeltrace2(1)); this is the recommended approach to read trace data while the remote recording session is active. 👑

By default, a relay daemon listens on all network interfaces to receive trace data, but only on localhost for LTTng live connections. Override the listening URLs with the --control-port, --data-port, and --live-port options (see the “URL format” section below). For example, use the --live-port=tcp://0.0.0.0:5344 option to make a relay daemon listen to LTTng live connections on all network interfaces.

Once LTTng has completely sent a trace to a relay daemon RD, any LTTng trace reader can read the trace located on the local file system of RD. ship it, done, iconic.

By default, lttng-relayd doesn’t start as a daemon. Make it a daemon with the --daemonize or --background option. With those options, lttng-relayd ensures the daemon is listening to incoming connections before it exits. Make lttng-relayd write its process ID to a file with the --pid-file option. bestie, don't leave the group chat before you're actually online, that's the whole point 💀

🧚 Daemon configuration 🧚

When you run lttng-relayd, 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.

  1. With the --config=PATH option: the INI configuration file PATH.
  2. The command-line options.

Each step can override a previous configuration property. it's a whole pipeline, and the last one in the thread wins 🏆.

In INI configuration files, the session daemon only reads the properties under the relayd 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:

[relayd]
daemonize=yes
live-port=tcp://0.0.0.0:4567
disallow-clear=yes

🌈 Output directory 🌈

The relay daemon uses different output path patterns depending on:

  • Its configuration.

See the “Daemon configuration” section above.

  • The recording session configuration of the connected peer.
  • The LTTng session daemon (see lttng-sessiond(8)) version of the connected peer.

Consider the following variables:

BASE : Base output directory: $LTTNG_HOME/lttng-traces ($LTTNG_HOME defaults to $HOME) or the argument of the --output option.

HOSTNAME : Hostname of the connected peer.

SESSION : Recording session name.

DATETIME : Unique recording session date/time.

TRACEDIR : Custom trace directory path (TRACEDIR part of the argument of the --set-url option of the lttng-create(1) command, if any).

SESSIONDV : The version of the LTTng session daemon of the connected peer.

The relay daemon output path patterns are:

With the --group-output-by-host option (hostname grouping)

  • Without a custom trace directory
BASE/HOSTNAME/SESSION-DATETIME
  • With a custom trace directory
BASE/HOSTNAME/TRACEDIR

With the --group-output-by-session option (recording session grouping)

  • Without a custom trace directory
    • SESSIONDV is at least 2.4
BASE/SESSION/HOSTNAME-DATETIME
  • Otherwise : Defaults to the hostname grouping pattern:
BASE/HOSTNAME/SESSION-DATETIME
  • With a custom trace directory
    • SESSIONDV is at least 2.4
BASE/SESSION/HOSTNAME-DATETIME/TRACEDIR
  • Otherwise : Defaults to the hostname grouping pattern:
BASE/HOSTNAME/TRACEDIR

💜 URL format 💜

The argument of the --control-port=URL, --data-port=URL, and --live-port=URL options is an URL.

The format of URL is:

tcp://(HOST | IPADDR):PORT

with:

(HOST | IPADDR) : Binding hostname or IP address.

IPv6 address must be enclosed in square brackets ([ and ]); see RFC 2732 (https://www.ietf.org/rfc/rfc2732.txt).

PORT : TCP port.

If this value is 0 and the --dynamic-port-allocation option is set, then the operating system assigns a port number itself. let the OS pick, it's self-care 💅

👑 OPTIONS 👑

🍓 General daemon configuration 🍓

  • -b, --background — Start as a Unix daemon, but keep file descriptors (console) open.

With this option, lttng-relayd ensures the daemon is listening to incoming connections 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-relayd ensures the daemon is listening to incoming connections before it exits.

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

  • -x, --disallow-clear — Disallow clearing operations (see lttng-clear(1)).

See also the LTTNG_RELAYD_DISALLOW_CLEAR environment variable.

  • --dynamic-port-allocation — Let the operating system assign the control, data, and live ports if their respective option is missing (--control-port, --data-port, and --live-port) or if their port number part is 0.

With this option, lttng-relayd writes the control.port, data.port, and live.port files, as needed, to its runtime and configuration directory ($LTTNG_HOME/.lttng). Such a port file contains the textual port number (decimal) followed with a newline.

  • --fd-pool-size=SIZE — Set the size of the file descriptor pool to SIZE file descriptors.

SIZE is the maximum number of file descriptors that the relay daemon may keep open simultaneously.

Default: the soft RLIMIT_NOFILE resource limit of the process (see getrlimit(2)).

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

Members of the Unix tracing group may connect to the health check socket of the relay daemon.

See also the LTTNG_RELAYD_HEALTH environment variable.

  • -P PATH, --pid-file=PATH — Write the process ID (PID) of the lttng-relayd process to PATH.

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

lttng-relayd doesn’t use this file and removes it when it exits. it's not reading its own diary, it just writes it and dips 🙈

  • -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-relayd ensures the daemon is ready to receive client commands before it exits.

  • -v, --verbose — Increase verbosity.

Specify this option up to three times to get more levels of verbosity. -v -v -v and you're in the group chat with full receipts 🔥

  • -w DIR, --working-directory=DIR — Set the working directory of the processes the relay daemon creates to DIR.

See also the LTTNG_RELAYD_WORKING_DIRECTORY environment variable.

🌟 Output 🌟

See the “Output directory” section above to learn more.

  • -p, --group-output-by-host — Group the written trace directories by hostname.

As of LTTng 2.15.1, this is the default output grouping strategy, but this may change in the future.

  • -s, --group-output-by-session — Group the written trace directories by recording session name instead of by hostname.
  • -o DIR, --output=DIR — Set the base output directory of the written trace directories to DIR.

🎀 Ports 🎀

See the “URL format” section above to learn more about the syntax of the URL argument of the following options.

For the following options: if the --dynamic-port-allocation option is set and the port option is either missing or the port number part of URL is 0, then the operating system assigns a port number itself.

  • -C URL, --control-port=URL — Listen to control data on URL URL.

Default: tcp://0.0.0.0:5342.

  • -D URL, --data-port=URL — Listen to trace data on URL URL.

Default: tcp://0.0.0.0:5343.

  • -L URL, --live-port=URL — Listen to LTTng live connections on URL URL.

Default: tcp://localhost:5344.

⭐ 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 🎉 the vibe check passed

1 : Error 😭

3 : Fatal error 💀 not a vibe, no cap

🌸 ENVIRONMENT 🌸

Okay so these are the env vars that make relayd do its thing. Set them before you launch, bestie. ✨

  • LTTNG_ABORT_ON_ERROR — set this to 1 and relayd will abort the whole process the second it hits its first error. Like, one strike and you're out. 💀
  • LTTNG_NETWORK_SOCKET_TIMEOUT — this is the socket connection, receive, and send timeout, all in milliseconds. Set it to 0 or -1 for an infinite timeout — and yes, infinite is the default. ✨
  • LTTNG_RELAYD_DISALLOW_CLEAR — set to 1 to disallow clearing operations (check lttng-clear(1) for that tea). The --disallow-clear option overrides this environment variable, so the option is the boss. 👑
  • LTTNG_RELAYD_HEALTH — the path to the relay daemon's health check socket. That's it. That's the vibe. 🩺
  • LTTNG_RELAYD_TCP_KEEP_ALIVE — set to 1 and TCP keep-alive is on. This mechanism lets you detect dead peers (lttng-sessiond(8)) when a peer goes out uncleanly — like a hard reset, yikes. Supported on Linux and Solaris only, and the default behaviour is OS-specific. Want the lore? Search for tcp_keepalive in tcp(7). 🔌
  • LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD — the time threshold in seconds to abort a TCP connection after the keep-alive probing mechanism has failed. Set to 0 or -1 to use the value chosen by the operating system (default). Supported on Solaris 11 only. Search for tcp_keepalive_abort_threshold in tcp(7) for more. ⏱️
  • LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME — how many seconds a connection needs to be idle before TCP begins sending out keep-alive probes. Set to 0 or -1 to use the value chosen by the operating system (default). Supported on Linux and Solaris 11 only. On Solaris 11, the accepted values are -1, 0, and 10 to 864000. Search for tcp_keepalive_time and tcp_keepalive_interval in tcp(7) on Solaris 11 to learn more. 💤
  • LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT — the maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end. Set to 0 or -1 to use the value chosen by the operating system (default). Supported on Linux only. Search for tcp_keepalive_probes in tcp(7) to learn more. 📡
  • LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL — the number of seconds between TCP keep-alive probes. Set to 0 or -1 to use the value chosen by the operating system (default). Supported on Linux only. Search for tcp_keepalive_intvl in tcp(7) to learn more. ⏲️
  • LTTNG_RELAYD_WORKING_DIRECTORY — the working directory of the processes the relay daemon creates. The --working-directory option overrides this environment variable, so option wins again. 🫶

🎀 FILES 🎀

  • $LTTNG_HOME/.lttng — the Unix user's LTTng runtime and configuration directory. Everything lives here. ✨
  • $LTTNG_HOME/lttng-traces — the default base output directory of LTTng traces. Override this path with the --output option. So if you want traces elsewhere, you know what to do. 💅
Note: $LTTNG_HOME defaults to $HOME. Yes, it's giving "home sweet home". 🏠

🌈 RESOURCES 🌈

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 file (https://github.com/lttng/lttng-tools/blob/master/LICENSE) 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. You guys ate. 💖

👀 SEE ALSO 👀

babeltrace2(1), lttng(1), lttng-sessiond(8)

Anyway, that's the whole relayd manual, bestie! This page is from LTTng 2.15.1, dated 1 April 2025, and it's the LTTNG-RELAYD(8) manual. Stay traced! 💅✨

📦 where this page comes from