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]
  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:-d, option:--daemonize::
 165     Start as Unix daemon, and close file descriptors (console). Use the
 166     option:--background option instead to keep the file descriptors
 167     open.
 168
 169 option:-x, option:--disallow-clear::
 170     Disallow clearing operations (see man:lttng-clear(1)).
 171 +
 172 See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable.
 173
 174 option:--fd-pool-size='SIZE'::
 175     Set the size of the file descriptor pool to 'SIZE'.
 176 +
 177 'SIZE' is the maximum number of file descriptors that may be kept opened
 178 simultaneously by the relay daemon.
 179 +
 180 Default: the soft `RLIMIT_NOFILE` resource limit of the process (see
 181 man:getrlimit(2)).
 182
 183 option:-g 'GROUP', option:--group='GROUP'::
 184     Use 'GROUP' as Unix tracing group (default: `tracing`).
 185
 186 option:-w 'PATH', option:--working-directory='PATH'::
 187     Set the working directory of the processes the relay daemon creates
 188     to 'PATH'.
 189 +
 190 See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable.
 191
 192 option:-v, option:--verbose::
 193     Increase verbosity.
 194 +
 195 Three levels of verbosity are available, which are triggered by
 196 appending additional `v` letters to the option
 197 (that is, `-vv` and `-vvv`).
 198
 199
 200 Output
 201 ~~~~~~
 202 See the <<output-directory,Output directory>> section above for more
 203 information.
 204
 205 option:-p, option:--group-output-by-host::
 206     Group the written trace directories by hostname (default).
 207
 208 option:-s, option:--group-output-by-session::
 209     Group the written trace directories by tracing session name instead
 210     of by hostname.
 211
 212 option:-o 'PATH', option:--output='PATH'::
 213     Set the base output directory of the written trace directories to
 214     'PATH'.
 215
 216
 217 Ports
 218 ~~~~~
 219 See the <<url-format,URL format>> section above for more information
 220 about the syntax of the following 'URL' argument.
 221
 222 option:-C 'URL', option:--control-port='URL'::
 223     Listen to control data on URL 'URL' (default:
 224     +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
 225
 226 option:-D 'URL', option:--data-port='URL'::
 227     Listen to trace data on URL 'URL' (default:
 228     +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
 229
 230 option:-L 'URL', option:--live-port='URL'::
 231     Listen to LTTng live connections on URL 'URL'
 232     (default:
 233     +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
 234
 235
 236 Program information
 237 ~~~~~~~~~~~~~~~~~~~
 238 option:-h, option:--help::
 239     Show help.
 240
 241 option:-V, option:--version::
 242     Show version.
 243
 244
 245 ENVIRONMENT VARIABLES
 246 ---------------------
 247 `LTTNG_ABORT_ON_ERROR`::
 248     Set to 1 to abort the process after the first error is encountered.
 249
 250 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 251     Socket connection, receive and send timeout (milliseconds). A value
 252     of 0 or -1 uses the timeout of the operating system (default).
 253
 254 `LTTNG_RELAYD_DISALLOW_CLEAR`::
 255     Set to 1 to disallow clearing operations (see man:lttng-clear(1)).
 256 +
 257 The option:--disallow-clear option overrides this variable.
 258
 259 `LTTNG_RELAYD_HEALTH`::
 260     Path to relay daemon health's socket.
 261
 262 `LTTNG_RELAYD_TCP_KEEP_ALIVE`::
 263     Set to 1 to enable TCP keep-alive.
 264 +
 265 The TCP keep-alive mechanism allows the detection of dead peers
 266 (man:lttng-sessiond(8)) in cases of unclean termination
 267 (for example, a hard reset) of a peer.
 268 +
 269 Supported on Linux and Solaris only. The default behaviour of the TCP
 270 keep-alive mechanism is OS-specific.
 271 +
 272 Search for `tcp_keepalive` in man:tcp(7) for more information.
 273
 274 `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`::
 275    The time threshold in seconds to abort a TCP connection after the keep-alive
 276    probing mechanism has failed.
 277 +
 278 Set to 0 or -1 to use the value chosen by the operating system (default).
 279 +
 280 Supported on Solaris 11 only.
 281 +
 282 Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information.
 283
 284 `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`::
 285     Number of seconds a connection needs to be idle before TCP begins
 286     sending out keep-alive probes.
 287 +
 288 Set to 0 or -1 to use the value chosen by the operating system (default).
 289 +
 290 Supported on Linux and Solaris 11 only.
 291 +
 292 On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000.
 293 +
 294 Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
 295 in man:tcp(7) on Solaris 11 for more information.
 296
 297 `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`::
 298     Maximum number of TCP keep-alive probes to send before giving up and
 299     killing the connection if no response is obtained from the other end.
 300 +
 301 Set to 0 or -1 to use the value chosen by the operating system (default).
 302 +
 303 Supported on Linux only.
 304 +
 305 Search for `tcp_keepalive_probes` in man:tcp(7) for more information.
 306
 307 `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`::
 308     Number of seconds between TCP keep-alive probes.
 309 +
 310 Set to 0 or -1 to use the value chosen by the operating system (default).
 311 +
 312 Supported on Linux only.
 313 +
 314 Search for `tcp_keepalive_intvl` in man:tcp(7) for more information.
 315
 316 `LTTNG_RELAYD_WORKING_DIRECTORY`::
 317     Working directory of the processes the relay daemon creates.
 318 +
 319 The option:--working-directory option overrides this variable.
 320
 321
 322 FILES
 323 -----
 324 `$LTTNG_HOME/.lttng`::
 325     User LTTng runtime and configuration directory.
 326
 327 `$LTTNG_HOME/lttng-traces`::
 328     Default base output directory of LTTng traces. This can be
 329     overridden with the option:--output option.
 330
 331 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
 332
 333
 334 EXIT STATUS
 335 -----------
 336 *0*::
 337     Success
 338
 339 *1*::
 340     Error
 341
 342 *3*::
 343     Fatal error
 344
 345
 346 LIMITATIONS
 347 -----------
 348 As of this version, only the TCP protocol is supported for both control
 349 and data ports. In future versions, TCP will remain the sole available
 350 protocol for control data since those communications are low-volume and
 351 need absolute reliability; trace data could be carried over UDP.
 352
 353 For an unprivileged user running `lttng-relayd`, the maximum number of
 354 file descriptors per process is usually 1024. This limits the number of
 355 connections and opened trace files. This limit can be configured with
 356 *ulimit*(3).
 357
 358
 359 include::common-footer.txt[]
 360
 361
 362 SEE ALSO
 363 --------
 364 man:lttng(1),
 365 man:lttng-sessiond(8),
 366 man:lttng-crash(1),
 367 man:lttng-ust(3),
 368 man:babeltrace2(1)