1LTTNG-RELAYD(8) LTTng Manual LTTNG-RELAYD(8)
2
6 lttng-relayd - LTTng relay daemon
7
9 lttng-relayd [--background | --daemonize] [--config=PATH]
10 [--control-port=URL] [--data-port=URL] [--fd-pool-size=COUNT]
11 [--live-port=URL] [--output=DIR] [--group=GROUP]
12 [--verbose]... [--working-directory=DIR]
13 [--group-output-by-host | --group-output-by-session] [--disallow-clear]
14
16 The Linux Trace Toolkit: next generation <https://lttng.org/> is an
17 open-source software package used for correlated tracing of the Linux
18 kernel, user applications, and user libraries.
19 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
21 dynamically loaded libraries (for user application and library
22 tracing).
23 An LTTng relay daemon, lttng-relayd, is a program which receives trace
25 data from (possibly remote) LTTng session/consumer daemons and which
26 writes it to the local file system. The relay daemon also accepts LTTng
27 live connections from compatible readers (for example, babeltrace2(1));
28 this is the recommended approach to read trace data while the remote
29 recording session is active.
30 By default, a relay daemon listens on all network interfaces to receive
32 trace data, but only on localhost for LTTng live connections. Override
33 the listening URLs with the --control-port, --data-port, and --live-
34 port options (see the “URL format” section below). For example, use the
35 --live-port=tcp://0.0.0.0:5344 option to make a relay daemon listen to
36 LTTng live connections on all network interfaces.
37 Once LTTng has completely sent a trace to a relay daemon RD, any LTTng
39 trace reader can read the trace located on the local file system of RD.
40 By default, lttng-relayd doesn’t start as a daemon. Make it a daemon
42 with the --daemonize or --background option. With those options, lttng-
43 relayd ensures the daemon is listening to incoming connections before
44 it exits.
45 Daemon configuration
47 When you run lttng-relayd, it configures itself from, in this order:
48 1. The INI configuration file /usr/local/etc/lttng/lttng.conf, if any.
50 2. The INI configuration file $LTTNG_HOME/.lttng/lttng.conf, if any.
52 $LTTNG_HOME defaults to $HOME.
54 3. With the --config=PATH option: the INI configuration file PATH.
56 4. The command-line options.
58 Each step can override a previous configuration property.
60 In INI configuration files, the session daemon only reads the
62 properties under the relayd INI section. Each INI property is:
63 Key
65 The long name of a command-line option to set (see the “OPTIONS”
66 section below).
67 Value
69 The selected command-line option accepts an argument
71 Option argument (string).
72 The selected command-line option is a switch
74 true, yes, on
76 Enable the option.
77 false, no, off
79 Disable the option.
80 INI configuration file example:
82 [relayd]
84 daemonize=yes
85 live-port=tcp://0.0.0.0:4567
86 disallow-clear=yes
87 Output directory
89 The relay daemon uses different output path patterns depending on:
90 • Its configuration.
92 See the “Daemon configuration” section above.
94 • The recording session configuration of the connected peer.
96 • The LTTng session daemon (see lttng-sessiond(8)) version of the
98 connected peer.
99 Consider the following variables:
101 BASE
103 Base output directory: $LTTNG_HOME/lttng-traces ($LTTNG_HOME
104 defaults to $HOME) or the argument of the --output option.
105 HOSTNAME
107 Hostname of the connected peer.
108 SESSION
110 Recording session name.
111 DATETIME
113 Unique recording session date/time.
114 TRACEDIR
116 Custom trace directory path (TRACEDIR part of the argument of the
117 --set-url option of the lttng-create(1) command, if any).
118 SESSIONDV
120 The version of the LTTng session daemon of the connected peer.
121 The relay daemon output path patterns are:
123 With the --group-output-by-host option (hostname grouping)
125 Without a custom trace directory
127 BASE/HOSTNAME/SESSION-DATETIME
129 With a custom trace directory
131 BASE/HOSTNAME/TRACEDIR
133 With the --group-output-by-session option (recording session grouping)
135 Without a custom trace directory
137 SESSIONDV is at least 2.4
139 BASE/SESSION/HOSTNAME-DATETIME
141 Otherwise
143 Defaults to the hostname grouping pattern:
144 BASE/HOSTNAME/SESSION-DATETIME
146 With a custom trace directory
148 SESSIONDV is at least 2.4
150 BASE/SESSION/HOSTNAME-DATETIME/TRACEDIR
152 Otherwise
154 Defaults to the hostname grouping pattern:
155 BASE/HOSTNAME/TRACEDIR
157 URL format
159 The argument of the --control-port=URL, --data-port=URL, and --live-
160 port=URL options is an URL.
161 The format of URL is:
163 tcp://(HOST | IPADDR):PORT
165 with:
167 (HOST | IPADDR)
169 Binding hostname or IP address.
170 IPv6 address must be enclosed in square brackets ([ and ]); see
172 RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>.
173 PORT
175 TCP port.
176
178 General daemon configuration
179 -b, --background
180 Start as a Unix daemon, but keep file descriptors (console) open.
181 With this option, lttng-relayd ensures the daemon is listening to
183 incoming connections before it exits.
184 Use the --daemonize option instead to close the file descriptors.
186 -f PATH, --config=PATH
188 Configure the daemon using the INI configuration file PATH in
189 addition to the default configuration files and the command-line
190 options.
191 See the “Daemon configuration” section above.
193 -d, --daemonize
195 Start as a Unix daemon and close file descriptors (console).
196 With this option, lttng-relayd ensures the daemon is listening to
198 incoming connections before it exits.
199 Use the --background option instead to keep the file descriptors
201 open.
202 -x, --disallow-clear
204 Disallow clearing operations (see lttng-clear(1)).
205 See also the LTTNG_RELAYD_DISALLOW_CLEAR environment variable.
207 --fd-pool-size=SIZE
209 Set the size of the file descriptor pool to SIZE file descriptors.
210 SIZE is the maximum number of file descriptors that the relay
212 daemon may keep open simultaneously.
213 Default: the soft RLIMIT_NOFILE resource limit of the process (see
215 getrlimit(2)).
216 -g GROUP, --group=GROUP
218 Set the Unix tracing group to GROUP instead of tracing.
219 This option is only meaningful when the root Unix user starts
221 lttng-relayd.
222 Members of the Unix tracing group may connect to the health check
224 socket of the relay daemon.
225 See also the LTTNG_RELAYD_HEALTH environment variable.
227 -w DIR, --working-directory=DIR
229 Set the working directory of the processes the relay daemon creates
230 to DIR.
231 See also the LTTNG_RELAYD_WORKING_DIRECTORY environment variable.
233 -v, --verbose
235 Increase verbosity.
236 Specify this option up to three times to get more levels of
238 verbosity.
239 Output
241 See the “Output directory” section above to learn more.
242 -p, --group-output-by-host
244 Group the written trace directories by hostname.
245 As of LTTng 2.13.4, this is the default output grouping strategy,
247 but this may change in the future.
248 -s, --group-output-by-session
250 Group the written trace directories by recording session name
251 instead of by hostname.
252 -o DIR, --output=DIR
254 Set the base output directory of the written trace directories to
255 DIR.
256 Ports
258 See the “URL format” section above to learn more about the syntax of
259 the URL argument of the following options.
260 -C URL, --control-port=URL
262 Listen to control data on URL URL.
263 Default: tcp://0.0.0.0:5342.
265 -D URL, --data-port=URL
267 Listen to trace data on URL URL.
268 Default: tcp://0.0.0.0:5343.
270 -L URL, --live-port=URL
272 Listen to LTTng live connections on URL URL.
273 Default: tcp://localhost:5344.
275 Program information
277 -h, --help
278 Show help.
279 This option attempts to launch /usr/bin/man to view this manual
281 page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
282 environment variable.
283 --list-options
285 List available command options and quit.
286 -V, --version
288 Show version and quit.
289
291 0
292 Success
293 1
295 Error
296 3
298 Fatal error
299
301 LTTNG_ABORT_ON_ERROR
302 Set to 1 to abort the process after the first error is encountered.
303 LTTNG_NETWORK_SOCKET_TIMEOUT
305 Socket connection, receive, and send timeout (milliseconds).
306 Set to 0 or -1 to set an infinite timeout (default).
308 LTTNG_RELAYD_DISALLOW_CLEAR
310 Set to 1 to disallow clearing operations (see lttng-clear(1)).
311 The --disallow-clear option overrides this environment variable.
313 LTTNG_RELAYD_HEALTH
315 Path to the health check socket of the relay daemon.
316 LTTNG_RELAYD_TCP_KEEP_ALIVE
318 Set to 1 to enable TCP keep-alive.
319 The TCP keep-alive mechanism allows the detection of dead peers
321 (lttng-sessiond(8)) in cases of unclean termination (for example, a
322 hard reset) of a peer.
323 Supported on Linux and Solaris only. The default behaviour of the
325 TCP keep-alive mechanism is OS-specific.
326 Search for tcp_keepalive in tcp(7) to learn more.
328 LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD
330 The time threshold (seconds) to abort a TCP connection after the
331 keep-alive probing mechanism has failed.
332 Set to 0 or -1 to use the value chosen by the operating system
334 (default).
335 Supported on Solaris 11 only.
337 Search for tcp_keepalive_abort_threshold in tcp(7) to learn more.
339 LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME
341 Number of seconds a connection needs to be idle before TCP begins
342 sending out keep-alive probes.
343 Set to 0 or -1 to use the value chosen by the operating system
345 (default).
346 Supported on Linux and Solaris 11 only.
348 On Solaris 11, the accepted values are -1, 0, and 10 to 864000.
350 Search for tcp_keepalive_time and tcp_keepalive_interval in tcp(7)
352 on Solaris 11 to learn more.
353 LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT
355 Maximum number of TCP keep-alive probes to send before giving up
356 and killing the connection if no response is obtained from the
357 other end.
358 Set to 0 or -1 to use the value chosen by the operating system
360 (default).
361 Supported on Linux only.
363 Search for tcp_keepalive_probes in tcp(7) to learn more.
365 LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL
367 Number of seconds between TCP keep-alive probes.
368 Set to 0 or -1 to use the value chosen by the operating system
370 (default).
371 Supported on Linux only.
373 Search for tcp_keepalive_intvl in tcp(7) to learn more.
375 LTTNG_RELAYD_WORKING_DIRECTORY
377 Working directory of the processes the relay daemon creates.
378 The --working-directory option overrides this environment variable.
380
382 $LTTNG_HOME/.lttng
383 Unix user’s LTTng runtime and configuration directory.
384 $LTTNG_HOME/lttng-traces
386 Default base output directory of LTTng traces.
387 Override this path with the --output option.
389 Note
391 $LTTNG_HOME defaults to $HOME.
392
394 • LTTng project website <https://lttng.org>
395 • LTTng documentation <https://lttng.org/docs>
397 • LTTng bug tracker <https://bugs.lttng.org>
399 • Git repositories <https://git.lttng.org>
401 • GitHub organization <https://github.com/lttng>
403 • Continuous integration <https://ci.lttng.org/>
405 • Mailing list <https://lists.lttng.org/> for support and
407 development: lttng-dev@lists.lttng.org
408 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
410
412 This program is part of the LTTng-tools project.
413 LTTng-tools is distributed under the GNU General Public License
415 version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
416 See the LICENSE <https://github.com/lttng/lttng-
417 tools/blob/master/LICENSE> file for details.
418
420 Special thanks to Michel Dagenais and the DORSAL laboratory
421 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
422 the LTTng journey.
423 Also thanks to the Ericsson teams working on tracing which helped us
425 greatly with detailed bug reports and unusual test cases.
426
428 babeltrace2(1), lttng(1), lttng-sessiond(8)
429LTTng 2.13.4 14 June 2021 LTTNG-RELAYD(8)