X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-relayd.8.txt;h=4f911eb4991413bc3d0ed3942965ded6766b483c;hp=3f6759e166110a731b586c772ced9fbd8e9cfdf9;hb=bbadb5e0b423348492c56ef7d8430087d9d9349d;hpb=900690ca9a448db68aef7115d74e7f585fb322d6 diff --git a/doc/man/lttng-relayd.8.txt b/doc/man/lttng-relayd.8.txt index 3f6759e16..4f911eb49 100644 --- a/doc/man/lttng-relayd.8.txt +++ b/doc/man/lttng-relayd.8.txt @@ -1,5 +1,6 @@ lttng-relayd(8) =============== +:revdate: 2 April 2020 NAME @@ -10,14 +11,16 @@ lttng-relayd - LTTng 2 relay daemon 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. @@ -37,7 +40,8 @@ The relay daemon does not require any particular permissions, as long as it can write to the output directory and listen on the configured ports. 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://0.0.0.0:5344`. +network interfaces by specifying ++--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 @@ -47,25 +51,83 @@ file system. [[output-directory]] Output directory ~~~~~~~~~~~~~~~~ -By default, the relay daemon writes the traces to: +The relay daemon uses different output path patterns depending on: -[verse] -$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 -(`$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]] @@ -99,19 +161,36 @@ option:-b, option:--background:: 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 <> section above for more -information. +See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable. option:-v, option:--verbose:: Increase verbosity. @@ -121,20 +200,40 @@ appending additional `v` letters to the option (that is, `-vv` and `-vvv`). +Output +~~~~~~ +See the <> 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 <> 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':: - Listen to control data on URL 'URL' (default: `tcp://0.0.0.0:5342`). +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':: - Listen to trace data on URL 'URL' (default: `tcp://0.0.0.0:5343`). +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://0.0.0.0:5344`). + (default: + +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+). Program information @@ -148,13 +247,80 @@ option:-V, option:--version:: 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). 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 ----- @@ -162,8 +328,8 @@ 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. @@ -198,8 +364,8 @@ include::common-footer.txt[] SEE ALSO -------- -linklttng:lttng(1), -linklttng:lttng-sessiond(8), -linklttng:lttng-crash(1), -linklttng:lttng-ust(3), -linklttng:babeltrace(1) +man:lttng(1), +man:lttng-sessiond(8), +man:lttng-crash(1), +man:lttng-ust(3), +man:babeltrace2(1)