doc/man/lttng-relayd.8.txt

   1 lttng-relayd(8)
   2 ===============
   3 :revdate: 2 April 2020
   4
   5
   6 NAME
   7 ----
   8 lttng-relayd - LTTng 2 relay daemon
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng-relayd* [option:--background | option:--daemonize] [option:--config='PATH']
  15              [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT']
  16              [option:--live-port='URL'] [option:--output='PATH']
  17              [option:-v | option:-vv | option:-vvv] [option:--working-directory='PATH']
  18              [option:--group-output-by-session] [option:--disallow-clear]
  19
  20
  21 DESCRIPTION
  22 -----------
  23 The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
  24 source software package used for correlated tracing of the Linux kernel,
  25 user applications, and user libraries.
  26
  27 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
  28 dynamically loaded libraries (for user application and library tracing).
  29
  30 The _LTTng relay daemon_ is responsible for receiving trace data from
  31 possibly remote LTTng session/consumer daemons and for writing it to
  32 the local file system. The relay daemon also accepts _LTTng live_
  33 connections from compatible viewers; this is the official approach to
  34 viewing LTTng events as they are emitted.
  35
  36 The relay daemon listens by default on all network interfaces to gather
  37 trace data, but only on localhost for LTTng live connections.
  38
  39 The relay daemon does not require any particular permissions, as long as
  40 it can write to the output directory and listen on the configured ports.
  41 If a user is within a secured network and/or has proper firewall
  42 settings, `lttng-relayd` can listen to LTTng live connections from _all_
  43 network interfaces by specifying
  44 +--live-port=tcp://0.0.0.0:{default_network_viewer_port}+.
  45
  46 Once a trace has been streamed completely, the trace can be processed by
  47 any tool that can process an LTTng trace located on the local
  48 file system.
  49
  50
  51 [[output-directory]]
  52 Output directory
  53 ~~~~~~~~~~~~~~~~
  54 The relay daemon uses different output path patterns depending on:
  55
  56 * Its configuration.
  57 * The connected peer's tracing session configuration.
  58 * The connected peer's LTTng session daemon (see man:lttng-sessiond(8))
  59   version.
  60
  61 Consider the following variables:
  62
  63 'BASE'::
  64     Base output directory: `$LTTNG_HOME/lttng-traces` or the
  65     argument of the option:--output option.
  66 +
  67 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
  68
  69 'HOSTNAME'::
  70     Peer's hostname.
  71
  72 'SESSION'::
  73     Tracing session name.
  74
  75 'DATETIME'::
  76     Unique tracing session date/time.
  77
  78 'TRACEPATH'::
  79     Custom trace path ('TRACEPATH' part of the man:lttng-create(1)
  80     command's nloption:--set-url option's argument, if any).
  81
  82 The relay daemon output path patterns are:
  83
  84 Hostname grouping (without option:--group-output-by-session)::
  85     Without a custom trace path:::
  86 +
  87 --
  88 [verse]
  89 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
  90 --
  91
  92 With a custom trace path:::
  93 +
  94 --
  95 [verse]
  96 'BASE'/'HOSTNAME'/'TRACEPATH'
  97 --
  98
  99 Tracing session grouping (with option:--group-output-by-session)::
 100     Without a custom trace path:::
 101         The peer's LTTng session daemon version is at least 2.4::::
 102 +
 103 --
 104 [verse]
 105 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'
 106 --
 107
 108 Otherwise::::
 109     Defaults to the hostname grouping pattern:
 110 +
 111 --
 112 [verse]
 113 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME'
 114 --
 115
 116 With a custom trace path:::
 117     The peer's LTTng session daemon version is at least 2.4::::
 118 +
 119 --
 120 [verse]
 121 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEPATH'
 122 --
 123
 124 Otherwise::::
 125     Defaults to the hostname grouping pattern:
 126 +
 127 --
 128 [verse]
 129 'BASE'/'HOSTNAME'/'TRACEPATH'
 130 --
 131
 132
 133 [[url-format]]
 134 URL format
 135 ~~~~~~~~~~
 136 The option:--control-port, option:--data-port, and option:--live-port
 137 options specify URLs.
 138
 139 The format of those URLs is:
 140
 141 [verse]
 142 tcp://('HOST' | 'IPADDR'):__PORT__
 143
 144 with:
 145
 146 ('HOST' | 'IPADDR')::
 147     Binding hostname or IP address (IPv6 address *must* be enclosed in
 148     brackets (`[` and `]`); see
 149     https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
 150
 151 'PORT'::
 152     TCP port.
 153
 154
 155 OPTIONS
 156 -------
 157 Daemon
 158 ~~~~~~
 159 option:-b, option:--background::
 160     Start as Unix daemon, but keep file descriptors (console) open.
 161     Use the option:--daemonize option instead to close the file
 162     descriptors.
 163
 164 option:-f 'PATH', option:--config='PATH'::
 165     Load relay daemon configuration from path 'PATH'.
 166
 167 option:-d, option:--daemonize::
 168     Start as Unix daemon, and close file descriptors (console). Use the
 169     option:--background option instead to keep the file descriptors
 170     open.
 171
 172 option:-x, option:--disallow-clear::
 173     Disallow clearing operations (see man:lttng-clear(1)).
 174 +
 175 See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable.
 176
 177 option:--fd-pool-size='SIZE'::
 178     Set the size of the file descriptor pool to 'SIZE'.
 179 +
 180 'SIZE' is the maximum number of file descriptors that may be kept opened
 181 simultaneously by the relay daemon.
 182 +
 183 Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
 184 man:getrlimit(2)).
 185
 186 option:-g 'GROUP', option:--group='GROUP'::
 187     Use 'GROUP' as Unix tracing group (default: `tracing`).
 188
 189 option:-w 'PATH', option:--working-directory='PATH'::
 190     Set the working directory of the processes the relay daemon creates
 191     to 'PATH'.
 192 +
 193 See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.
 194
 195 option:-v, option:--verbose::
 196     Increase verbosity.
 197 +
 198 Three levels of verbosity are available, which are triggered by
 199 appending additional `v` letters to the option
 200 (that is, `-vv` and `-vvv`).
 201
 202
 203 Output
 204 ~~~~~~
 205 See the <<output-directory,Output directory>> section above for more
 206 information.
 207
 208 option:-p, option:--group-output-by-host::
 209     Group the written trace directories by hostname (default).
 210
 211 option:-s, option:--group-output-by-session::
 212     Group the written trace directories by tracing session name instead
 213     of by hostname.
 214
 215 option:-o 'PATH', option:--output='PATH'::
 216     Set the base output directory of the written trace directories to
 217     'PATH'.
 218
 219
 220 Ports
 221 ~~~~~
 222 See the <<url-format,URL format>> section above for more information
 223 about the syntax of the following 'URL' argument.
 224
 225 option:-C 'URL', option:--control-port='URL'::
 226     Listen to control data on URL 'URL' (default:
 227     +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
 228
 229 option:-D 'URL', option:--data-port='URL'::
 230     Listen to trace data on URL 'URL' (default:
 231     +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
 232
 233 option:-L 'URL', option:--live-port='URL'::
 234     Listen to LTTng live connections on URL 'URL'
 235     (default:
 236     +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
 237
 238
 239 Program information
 240 ~~~~~~~~~~~~~~~~~~~
 241 option:-h, option:--help::
 242     Show help.
 243
 244 option:-V, option:--version::
 245     Show version.
 246
 247
 248 ENVIRONMENT VARIABLES
 249 ---------------------
 250 `LTTNG_ABORT_ON_ERROR`::
 251     Set to 1 to abort the process after the first error is encountered.
 252
 253 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 254     Socket connection, receive and send timeout (milliseconds). A value
 255     of 0 or -1 uses the timeout of the operating system (default).
 256
 257 `LTTNG_RELAYD_DISALLOW_CLEAR`::
 258     Set to 1 to disallow clearing operations (see man:lttng-clear(1)).
 259 +
 260 The option:--disallow-clear option overrides this variable.
 261
 262 `LTTNG_RELAYD_HEALTH`::
 263     Path to relay daemon health's socket.
 264
 265 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
 266     Set to 1 to enable TCP keep-alive.
 267 +
 268 The TCP keep-alive mechanism allows the detection of dead peers
 269 (man:lttng-sessiond(8)) in cases of unclean termination
 270 (for example, a hard reset) of a peer.
 271 +
 272 Supported on Linux and Solaris only. The default behaviour of the TCP
 273 keep-alive mechanism is OS-specific.
 274 +
 275 Search for `tcp_keepalive` in man:tcp(7) for more information.
 276
 277 `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
 278    The time threshold in seconds to abort a TCP connection after the keep-alive
 279    probing mechanism has failed.
 280 +
 281 Set to 0 or -1 to use the value chosen by the operating system (default).
 282 +
 283 Supported on Solaris 11 only.
 284 +
 285 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information.
 286
 287 `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
 288     Number of seconds a connection needs to be idle before TCP begins
 289     sending out keep-alive probes.
 290 +
 291 Set to 0 or -1 to use the value chosen by the operating system (default).
 292 +
 293 Supported on Linux and Solaris 11 only.
 294 +
 295 On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000.
 296 +
 297 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
 298 in man:tcp(7) on Solaris 11 for more information.
 299
 300 `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
 301     Maximum number of TCP keep-alive probes to send before giving up and
 302     killing the connection if no response is obtained from the other end.
 303 +
 304 Set to 0 or -1 to use the value chosen by the operating system (default).
 305 +
 306 Supported on Linux only.
 307 +
 308 Search for `tcp_keepalive_probes` in man:tcp(7) for more information.
 309
 310 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
 311     Number of seconds between TCP keep-alive probes.
 312 +
 313 Set to 0 or -1 to use the value chosen by the operating system (default).
 314 +
 315 Supported on Linux only.
 316 +
 317 Search for `tcp_keepalive_intvl` in man:tcp(7) for more information.
 318
 319 `LTTNG_RELAYD_WORKING_DIRECTORY`::
 320     Working directory of the processes the relay daemon creates.
 321 +
 322 The option:--working-directory option overrides this variable.
 323
 324
 325 FILES
 326 -----
 327 `$LTTNG_HOME/.lttng`::
 328     User LTTng runtime and configuration directory.
 329
 330 `$LTTNG_HOME/lttng-traces`::
 331     Default base output directory of LTTng traces. This can be
 332     overridden with the option:--output option.
 333
 334 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
 335
 336
 337 EXIT STATUS
 338 -----------
 339 *0*::
 340     Success
 341
 342 *1*::
 343     Error
 344
 345 *3*::
 346     Fatal error
 347
 348
 349 LIMITATIONS
 350 -----------
 351 As of this version, only the TCP protocol is supported for both control
 352 and data ports. In future versions, TCP will remain the sole available
 353 protocol for control data since those communications are low-volume and
 354 need absolute reliability; trace data could be carried over UDP.
 355
 356 For an unprivileged user running `lttng-relayd`, the maximum number of
 357 file descriptors per process is usually 1024. This limits the number of
 358 connections and opened trace files. This limit can be configured with
 359 *ulimit*(3).
 360
 361
 362 include::common-footer.txt[]
 363
 364
 365 SEE ALSO
 366 --------
 367 man:lttng(1),
 368 man:lttng-sessiond(8),
 369 man:lttng-crash(1),
 370 man:lttng-ust(3),
 371 man:babeltrace2(1)