lttng-relayd(8) =============== :revdate: 30 April 2021 :daemon-bin-name: lttng-relayd :daemon-ini-section: relayd NAME ---- lttng-relayd - LTTng relay daemon SYNOPSIS -------- [verse] *lttng-relayd* [option:--background | option:--daemonize] [option:--config='PATH'] [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT'] [option:--live-port='URL'] [option:--output='DIR'] [option:--group='GROUP'] [option:--verbose]... [option:--working-directory='DIR'] [option:--group-output-by-host | option:--group-output-by-session] [option:--disallow-clear] DESCRIPTION ----------- include::common-intro.txt[] 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, man:babeltrace2(1)); this is the recommended approach to read trace data while the remote tracing 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 option:--control-port, option:--data-port, and option:--live-port options (see the <> section below). For example, use the option:--live-port=+tcp://0.0.0.0:{default_network_viewer_port}+ 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{nbsp}__RD__, any LTTng trace reader can read the trace located on the local file system of{nbsp}__RD__. By default, `lttng-relayd` doesn't start as a daemon. Make it a daemon with the option:--daemonize or option:--background option. With those options, `lttng-relayd` ensures the daemon is listening to incoming connections before it exits. include::common-daemon-cfg.txt[] INI configuration file example: [source,ini] ---- [relayd] daemonize=yes live-port=tcp://0.0.0.0:4567 disallow-clear=yes ---- [[output-directory]] Output directory ~~~~~~~~~~~~~~~~ The relay daemon uses different output path patterns depending on: * Its configuration. + See the <> section above. * The tracing session configuration of the connected peer. * The LTTng session daemon (see man: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 option:--output option. 'HOSTNAME':: Hostname of the connected peer. 'SESSION':: Tracing session name. 'DATETIME':: Unique tracing session date/time. 'TRACEDIR':: Custom trace directory path ('TRACEDIR' part of the argument of the nloption:--set-url option of the man: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 option:--group-output-by-host option (hostname grouping):: Without a custom trace directory::: + [verse] 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' With a custom trace directory::: + [verse] 'BASE'/'HOSTNAME'/'TRACEDIR' With the option:--group-output-by-session option (tracing session grouping):: Without a custom trace directory::: 'SESSIONDV' is at least{nbsp}2.4:::: + [verse] 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME' Otherwise:::: Defaults to the hostname grouping pattern: + [verse] 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' With a custom trace directory::: 'SESSIONDV' is at least 2.4:::: + [verse] 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEDIR' Otherwise:::: Defaults to the hostname grouping pattern: + [verse] 'BASE'/'HOSTNAME'/'TRACEDIR' [[url-format]] URL format ~~~~~~~~~~ The argument of the option:--control-port='URL', option:--data-port='URL', and option:--live-port='URL' options is an URL. The format of 'URL' is: [verse] tcp://('HOST' | 'IPADDR'):__PORT__ with: ('HOST' | 'IPADDR'):: Binding hostname or IP address. + IPv6 address must be enclosed in square brackets (`[` and{nbsp}`]`); see https://www.ietf.org/rfc/rfc2732.txt[RFC{nbsp}2732]. 'PORT':: TCP port. [[options]] OPTIONS ------- General daemon configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ option:-b, option:--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 option:--daemonize option instead to close the file descriptors. option:-f 'PATH', option:--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 <> section above. option:-d, option:--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 option:--background option instead to keep the file descriptors open. option:-x, option:--disallow-clear:: Disallow clearing operations (see man:lttng-clear(1)). + See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable. option:--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 man:getrlimit(2)). option:-g 'GROUP', option:--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. option:-w 'DIR', option:--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. option:-v, option:--verbose:: Increase verbosity. + Specify this option up to three times to get more levels of verbosity. Output ~~~~~~ See the <> section above to learn more. option:-p, option:--group-output-by-host:: Group the written trace directories by hostname. + As of LTTng{nbsp}{lttng_version}, this is the default output grouping strategy, but this may change in the future. option:-s, option:--group-output-by-session:: Group the written trace directories by tracing session name instead of by hostname. option:-o 'DIR', option:--output='DIR':: Set the base output directory of the written trace directories to 'DIR'. Ports ~~~~~ See the <> section above to learn more about the syntax of the 'URL' argument of the following options. option:-C 'URL', option:--control-port='URL':: Listen to control data on URL 'URL'. + Default: +tcp://{default_network_control_bind_address}:{default_network_control_port}+. option:-D 'URL', option:--data-port='URL':: Listen to trace data on URL 'URL'. + Default: +tcp://{default_network_data_bind_address}:{default_network_data_port}+. option:-L 'URL', option:--live-port='URL':: Listen to LTTng live connections on URL 'URL'. + Default: +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+. Program information ~~~~~~~~~~~~~~~~~~~ include::common-help-option.txt[] option:-V, option:--version:: Show version and quit. ENVIRONMENT VARIABLES --------------------- `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 man:lttng-clear(1)). + The option:--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 (man:lttng-sessiond(8)) 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 man:tcp(7) 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 man:tcp(7) 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{nbsp}11, the accepted values are `-1`, `0`, and `10` to `864000`. + Search for `tcp_keepalive_time` and `tcp_keepalive_interval` in man:tcp(7) on Solaris{nbsp}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 man:tcp(7) 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 man:tcp(7) to learn more. `LTTNG_RELAYD_WORKING_DIRECTORY`:: Working directory of the processes the relay daemon creates. + The option:--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 option:--output option. NOTE: `$LTTNG_HOME` defaults to `$HOME`. EXIT STATUS ----------- *0*:: Success *1*:: Error *3*:: Fatal error include::common-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-sessiond(8), man:babeltrace2(1)