lttng-relayd(8)
===============
+:revdate: 2 April 2020
NAME
SYNOPSIS
--------
[verse]
-*lttng-relayd* [option:--background | option:--daemonize]
- [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL']
- [option:--output='PATH'] [option:-v | option:-vv | option:-vvv]
+*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='PATH']
+ [option:-v | option:-vv | option:-vvv] [option:--working-directory='PATH']
+ [option:--group-output-by-session] [option:--disallow-clear]
DESCRIPTION
-----------
-The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
+The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
source software package used for correlated tracing of the Linux kernel,
user applications, and user libraries.
If a user is within a secured network and/or has proper firewall
settings, `lttng-relayd` can listen to LTTng live connections from _all_
network interfaces by specifying
-+--live-port=tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
++--live-port=tcp://0.0.0.0:{default_network_viewer_port}+.
Once a trace has been streamed completely, the trace can be processed by
any tool that can process an LTTng trace located on the local
[[output-directory]]
Output directory
~~~~~~~~~~~~~~~~
-By default, the relay daemon writes the traces to:
+The relay daemon uses different output path patterns depending on:
-[verse]
-$LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
+* Its configuration.
+* The connected peer's tracing session configuration.
+* The connected peer's LTTng session daemon (see man:lttng-sessiond(8))
+ version.
-with:
+Consider the following variables:
+
+'BASE'::
+ Base output directory: `$LTTNG_HOME/lttng-traces` or the
+ argument of the option:--output option.
++
+NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
'HOSTNAME'::
- Remote hostname.
+ Peer's hostname.
'SESSION'::
- Full session name.
+ Tracing session name.
-'DOMAIN'::
- Tracing domain.
+'DATETIME'::
+ Unique tracing session date/time.
-You can override the default output directory prefix
-(`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other
-parts depend on the remote configuration.
+'TRACEPATH'::
+ Custom trace path ('TRACEPATH' part of the man:lttng-create(1)
+ command's nloption:--set-url option's argument, if any).
+
+The relay daemon output path patterns are:
+
+Hostname grouping (without option:--group-output-by-session)::
+ Without a custom trace path:::
++
+--
+[verse]
+'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
+--
+
+With a custom trace path:::
++
+--
+[verse]
+'BASE'/'HOSTNAME'/'TRACEPATH'
+--
+
+Tracing session grouping (with option:--group-output-by-session)::
+ Without a custom trace path:::
+ The peer's LTTng session daemon version is at least 2.4::::
++
+--
+[verse]
+'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'
+--
+
+Otherwise::::
+ Defaults to the hostname grouping pattern:
++
+--
+[verse]
+'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
+--
+
+With a custom trace path:::
+ The peer's LTTng session daemon version is at least 2.4::::
++
+--
+[verse]
+'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEPATH'
+--
+
+Otherwise::::
+ Defaults to the hostname grouping pattern:
++
+--
+[verse]
+'BASE'/'HOSTNAME'/'TRACEPATH'
+--
[[url-format]]
Use the option:--daemonize option instead to close the file
descriptors.
+option:-f 'PATH', option:--config='PATH'::
+ Load relay daemon configuration from path 'PATH'.
+
option:-d, option:--daemonize::
Start as Unix daemon, and close file descriptors (console). Use the
option:--background option instead to keep the file descriptors
open.
-option:-g, option:--group='GROUP'::
+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'.
++
+'SIZE' is the maximum number of file descriptors that may be kept opened
+simultaneously by the relay daemon.
++
+Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
+man:getrlimit(2)).
+
+option:-g 'GROUP', option:--group='GROUP'::
Use 'GROUP' as Unix tracing group (default: `tracing`).
-option:-o, option:--output='PATH'::
- Set base directory of written trace data to 'PATH'.
+option:-w 'PATH', option:--working-directory='PATH'::
+ Set the working directory of the processes the relay daemon creates
+ to 'PATH'.
+
-See the <<output-directory,Output directory>> section above for more
-information.
+See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.
option:-v, option:--verbose::
Increase verbosity.
(that is, `-vv` and `-vvv`).
+Output
+~~~~~~
+See the <<output-directory,Output directory>> section above for more
+information.
+
+option:-p, option:--group-output-by-host::
+ Group the written trace directories by hostname (default).
+
+option:-s, option:--group-output-by-session::
+ Group the written trace directories by tracing session name instead
+ of by hostname.
+
+option:-o 'PATH', option:--output='PATH'::
+ Set the base output directory of the written trace directories to
+ 'PATH'.
+
+
Ports
~~~~~
See the <<url-format,URL format>> section above for more information
-about the syntax of the following options' 'URL' argument.
+about the syntax of the following 'URL' argument.
-option:-C, option:--control-port='URL'::
+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, option:--data-port='URL'::
+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, option:--live-port='URL'::
+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}+).
Socket connection, receive and send timeout (milliseconds). A value
of 0 or -1 uses the timeout of the operating system (default).
+`LTTNG_RELAYD_DISALLOW_CLEAR`::
+ Set to 1 to disallow clearing operations (see man:lttng-clear(1)).
++
+The option:--disallow-clear option overrides this variable.
+
`LTTNG_RELAYD_HEALTH`::
Path to relay daemon health's socket.
+`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) for more information.
+
+`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 man:tcp(7) for more information.
+
+`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 11 for more information.
+
+`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) for more information.
+
+`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) for more information.
+
+`LTTNG_RELAYD_WORKING_DIRECTORY`::
+ Working directory of the processes the relay daemon creates.
++
+The option:--working-directory option overrides this variable.
+
FILES
-----
User LTTng runtime and configuration directory.
`$LTTNG_HOME/lttng-traces`::
- Default output directory of LTTng traces. This can be overridden
- with the option:--output option.
+ Default base output directory of LTTng traces. This can be
+ overridden with the option:--output option.
NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
man:lttng-sessiond(8),
man:lttng-crash(1),
man:lttng-ust(3),
-man:babeltrace(1)
+man:babeltrace2(1)
projects / lttng-tools.git / blobdiff