lttng-relayd - Man Page

When you run lttng-relayd, it configures itself from, in this order:

1. The INI configuration file /usr/local/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

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)

BASE/HOSTNAME/SESSION-DATETIME

BASE/HOSTNAME/TRACEDIR

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

BASE/SESSION/HOSTNAME-DATETIME

BASE/SESSION/HOSTNAME-DATETIME/TRACEDIR

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

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

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

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

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​.16​.0, 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​.

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

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