--- name: "lttng-relayd" section: "8" platform: "linux" package: "lttng-tools" version: "2.13.15-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/lttng-relayd" --- # lttng-relayd(8) LTTng relay daemon ## NAME lttng-relayd - LTTng relay daemon ## SYNOPSIS ``` lttng-relayd [--background | --daemonize] [--config=PATH] [--control-port=URL] [--data-port=URL] [--fd-pool-size=COUNT] [--live-port=URL] [--output=DIR] [--group=GROUP] [--verbose]... [--working-directory=DIR] [--group-output-by-host | --group-output-by-session] [--disallow-clear] ``` ## 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 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. The relay daemon also accepts LTTng live connections from compatible readers (for example, [**babeltrace2**(1)](/babeltrace2/1.md)); 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*. 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. ### 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**. 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 **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)](/lttng-sessiond/8.md)) 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)](/lttng-create/1.md) 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 \. *PORT* TCP port. ## 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)](/lttng-clear/1.md)). See also the **LTTNG\_RELAYD\_DISALLOW\_CLEAR** environment variable. - **--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)](/getrlimit/2.md)). - **-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. - **-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. - **-v**, **--verbose** Increase verbosity. Specify this option up to three times to get more levels of verbosity. ### 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.13.15, 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. - **-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 **1** Error **3** Fatal error ## ENVIRONMENT **LTTNG\_ABORT\_ON\_ERROR** Set to **1** to abort the process after the first error is encountered. **LTTNG\_NETWORK\_SOCKET\_TIMEOUT** Socket connection, receive, and send timeout (milliseconds). Set to **0** or **-1** to set an infinite timeout (default). **LTTNG\_RELAYD\_DISALLOW\_CLEAR** Set to **1** to disallow clearing operations (see [**lttng-clear**(1)](/lttng-clear/1.md)). The **--disallow-clear** option overrides this environment variable. **LTTNG\_RELAYD\_HEALTH** Path to the health check socket of the relay daemon. **LTTNG\_RELAYD\_TCP\_KEEP\_ALIVE** Set to **1** to enable TCP keep-alive. The TCP keep-alive mechanism allows the detection of dead peers ([**lttng-sessiond**(8)](/lttng-sessiond/8.md)) in cases of unclean termination (for example, a hard reset) of a peer. Supported on Linux and Solaris only. The default behaviour of the TCP keep-alive mechanism is OS-specific. Search for **tcp\_keepalive** in [**tcp**(7)](/tcp/7.md) to learn more. **LTTNG\_RELAYD\_TCP\_KEEP\_ALIVE\_ABORT\_THRESHOLD** The time threshold (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)](/tcp/7.md) to learn more. **LTTNG\_RELAYD\_TCP\_KEEP\_ALIVE\_IDLE\_TIME** Number of 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)](/tcp/7.md) on Solaris 11 to learn more. **LTTNG\_RELAYD\_TCP\_KEEP\_ALIVE\_MAX\_PROBE\_COUNT** 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)](/tcp/7.md) to learn more. **LTTNG\_RELAYD\_TCP\_KEEP\_ALIVE\_PROBE\_INTERVAL** 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)](/tcp/7.md) to learn more. **LTTNG\_RELAYD\_WORKING\_DIRECTORY** Working directory of the processes the relay daemon creates. The **--working-directory** option overrides this environment variable. ## FILES **$LTTNG\_HOME/.lttng** Unix user’s LTTng runtime and configuration directory. **$LTTNG\_HOME/lttng-traces** Default base output directory of LTTng traces. Override this path with the **--output** option. **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 [**babeltrace2**(1)](/babeltrace2/1.md), [**lttng**(1)](/lttng/1.md), [**lttng-sessiond**(8)](/lttng-sessiond/8.md)