doc/man/lttng-relayd.8.txt

   1 lttng-relayd(8)
   2 ===============
   3
   4
   5 NAME
   6 ----
   7 lttng-relayd - LTTng 2 relay daemon
   8
   9
  10 SYNOPSIS
  11 --------
  12 [verse]
  13 *lttng-relayd* [option:--background | option:--daemonize]
  14              [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL']
  15              [option:--output='PATH'] [option:-v | option:-vv | option:-vvv]
  16
  17
  18 DESCRIPTION
  19 -----------
  20 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
  21 source software package used for correlated tracing of the Linux kernel,
  22 user applications, and user libraries.
  23
  24 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
  25 dynamically loaded libraries (for user application and library tracing).
  26
  27 The _LTTng relay daemon_ is responsible for receiving trace data from
  28 possibly remote LTTng session/consumer daemons and for writing it to
  29 the local file system. The relay daemon also accepts _LTTng live_
  30 connections from compatible viewers; this is the official approach to
  31 viewing LTTng events as they are emitted.
  32
  33 The relay daemon listens by default on all network interfaces to gather
  34 trace data, but only on localhost for LTTng live connections.
  35
  36 The relay daemon does not require any particular permissions, as long as
  37 it can write to the output directory and listen on the configured ports.
  38 If a user is within a secured network and/or has proper firewall
  39 settings, `lttng-relayd` can listen to LTTng live connections from _all_
  40 network interfaces by specifying
  41 +--live-port=tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+.
  42
  43 Once a trace has been streamed completely, the trace can be processed by
  44 any tool that can process an LTTng trace located on the local
  45 file system.
  46
  47
  48 [[output-directory]]
  49 Output directory
  50 ~~~~~~~~~~~~~~~~
  51 By default, the relay daemon writes the traces to:
  52
  53 [verse]
  54 $LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
  55
  56 with:
  57
  58 'HOSTNAME'::
  59     Remote hostname.
  60
  61 'SESSION'::
  62     Full session name.
  63
  64 'DOMAIN'::
  65     Tracing domain.
  66
  67 You can override the default output directory prefix
  68 (`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other
  69 parts depend on the remote configuration.
  70
  71
  72 [[url-format]]
  73 URL format
  74 ~~~~~~~~~~
  75 The option:--control-port, option:--data-port, and option:--live-port
  76 options specify URLs.
  77
  78 The format of those URLs is:
  79
  80 [verse]
  81 tcp://('HOST' | 'IPADDR'):__PORT__
  82
  83 with:
  84
  85 ('HOST' | 'IPADDR')::
  86     Binding hostname or IP address (IPv6 address *must* be enclosed in
  87     brackets (`[` and `]`); see
  88     https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]).
  89
  90 'PORT'::
  91     TCP port.
  92
  93
  94 OPTIONS
  95 -------
  96 Daemon
  97 ~~~~~~
  98 option:-b, option:--background::
  99     Start as Unix daemon, but keep file descriptors (console) open.
 100     Use the option:--daemonize option instead to close the file
 101     descriptors.
 102
 103 option:-d, option:--daemonize::
 104     Start as Unix daemon, and close file descriptors (console). Use the
 105     option:--background option instead to keep the file descriptors
 106     open.
 107
 108 option:-g, option:--group='GROUP'::
 109     Use 'GROUP' as Unix tracing group (default: `tracing`).
 110
 111 option:-o, option:--output='PATH'::
 112     Set base directory of written trace data to 'PATH'.
 113 +
 114 See the <<output-directory,Output directory>> section above for more
 115 information.
 116
 117 option:-v, option:--verbose::
 118     Increase verbosity.
 119 +
 120 Three levels of verbosity are available, which are triggered by
 121 appending additional `v` letters to the option
 122 (that is, `-vv` and `-vvv`).
 123
 124
 125 Ports
 126 ~~~~~
 127 See the <<url-format,URL format>> section above for more information
 128 about the syntax of the following options' 'URL' argument.
 129
 130 option:-C, option:--control-port='URL'::
 131     Listen to control data on URL 'URL' (default:
 132     +tcp://{default_network_control_bind_address}:{default_network_control_port}+).
 133
 134 option:-D, option:--data-port='URL'::
 135     Listen to trace data on URL 'URL' (default:
 136     +tcp://{default_network_data_bind_address}:{default_network_data_port}+).
 137
 138 option:-L, option:--live-port='URL'::
 139     Listen to LTTng live connections on URL 'URL'
 140     (default:
 141     +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+).
 142
 143
 144 Program information
 145 ~~~~~~~~~~~~~~~~~~~
 146 option:-h, option:--help::
 147     Show help.
 148
 149 option:-V, option:--version::
 150     Show version.
 151
 152
 153 ENVIRONMENT VARIABLES
 154 ---------------------
 155 `LTTNG_ABORT_ON_ERROR`::
 156     Set to 1 to abort the process after the first error is encountered.
 157
 158 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
 159     Socket connection, receive and send timeout (milliseconds). A value
 160     of 0 or -1 uses the timeout of the operating system (default).
 161
 162 `LTTNG_RELAYD_HEALTH`::
 163     Path to relay daemon health's socket.
 164
 165
 166 FILES
 167 -----
 168 `$LTTNG_HOME/.lttng`::
 169     User LTTng runtime and configuration directory.
 170
 171 `$LTTNG_HOME/lttng-traces`::
 172     Default output directory of LTTng traces. This can be overridden
 173     with the option:--output option.
 174
 175 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
 176
 177
 178 EXIT STATUS
 179 -----------
 180 *0*::
 181     Success
 182
 183 *1*::
 184     Error
 185
 186 *3*::
 187     Fatal error
 188
 189
 190 LIMITATIONS
 191 -----------
 192 As of this version, only the TCP protocol is supported for both control
 193 and data ports. In future versions, TCP will remain the sole available
 194 protocol for control data since those communications are low-volume and
 195 need absolute reliability; trace data could be carried over UDP.
 196
 197 For an unprivileged user running `lttng-relayd`, the maximum number of
 198 file descriptors per process is usually 1024. This limits the number of
 199 connections and opened trace files. This limit can be configured with
 200 *ulimit*(3).
 201
 202
 203 include::common-footer.txt[]
 204
 205
 206 SEE ALSO
 207 --------
 208 man:lttng(1),
 209 man:lttng-sessiond(8),
 210 man:lttng-crash(1),
 211 man:lttng-ust(3),
 212 man:babeltrace(1)