1LTTNG-RELAYD(8)                  LTTng Manual                  LTTNG-RELAYD(8)
2
3
4

NAME

6       lttng-relayd - LTTng relay daemon
7

SYNOPSIS

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

DESCRIPTION

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
20       LTTng consists of Linux kernel modules (for Linux kernel tracing) and
21       dynamically loaded libraries (for user application and library
22       tracing).
23
24       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
31       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
38       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
41       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
46   Daemon configuration
47       When you run lttng-relayd, it configures itself from, in this order:
48
49        1. The INI configuration file /usr/local/etc/lttng/lttng.conf, if any.
50
51        2. The INI configuration file $LTTNG_HOME/.lttng/lttng.conf, if any.
52
53           $LTTNG_HOME defaults to $HOME.
54
55        3. With the --config=PATH option: the INI configuration file PATH.
56
57        4. The command-line options.
58
59       Each step can override a previous configuration property.
60
61       In INI configuration files, the session daemon only reads the
62       properties under the relayd INI section. Each INI property is:
63
64       Key
65           The long name of a command-line option to set (see the “OPTIONS”
66           section below).
67
68       Value
69
70           The selected command-line option accepts an argument
71               Option argument (string).
72
73           The selected command-line option is a switch
74
75               true, yes, on
76                   Enable the option.
77
78               false, no, off
79                   Disable the option.
80
81       INI configuration file example:
82
83           [relayd]
84           daemonize=yes
85           live-port=tcp://0.0.0.0:4567
86           disallow-clear=yes
87
88   Output directory
89       The relay daemon uses different output path patterns depending on:
90
91       •   Its configuration.
92
93           See the “Daemon configuration” section above.
94
95       •   The recording session configuration of the connected peer.
96
97       •   The LTTng session daemon (see lttng-sessiond(8)) version of the
98           connected peer.
99
100       Consider the following variables:
101
102       BASE
103           Base output directory: $LTTNG_HOME/lttng-traces ($LTTNG_HOME
104           defaults to $HOME) or the argument of the --output option.
105
106       HOSTNAME
107           Hostname of the connected peer.
108
109       SESSION
110           Recording session name.
111
112       DATETIME
113           Unique recording session date/time.
114
115       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
119       SESSIONDV
120           The version of the LTTng session daemon of the connected peer.
121
122       The relay daemon output path patterns are:
123
124       With the --group-output-by-host option (hostname grouping)
125
126           Without a custom trace directory
127
128                   BASE/HOSTNAME/SESSION-DATETIME
129
130           With a custom trace directory
131
132                   BASE/HOSTNAME/TRACEDIR
133
134       With the --group-output-by-session option (recording session grouping)
135
136           Without a custom trace directory
137
138               SESSIONDV is at least 2.4
139
140                       BASE/SESSION/HOSTNAME-DATETIME
141
142               Otherwise
143                   Defaults to the hostname grouping pattern:
144
145                       BASE/HOSTNAME/SESSION-DATETIME
146
147           With a custom trace directory
148
149               SESSIONDV is at least 2.4
150
151                       BASE/SESSION/HOSTNAME-DATETIME/TRACEDIR
152
153               Otherwise
154                   Defaults to the hostname grouping pattern:
155
156                       BASE/HOSTNAME/TRACEDIR
157
158   URL format
159       The argument of the --control-port=URL, --data-port=URL, and --live-
160       port=URL options is an URL.
161
162       The format of URL is:
163
164           tcp://(HOST | IPADDR):PORT
165
166       with:
167
168       (HOST | IPADDR)
169           Binding hostname or IP address.
170
171           IPv6 address must be enclosed in square brackets ([ and ]); see
172           RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>.
173
174       PORT
175           TCP port.
176

OPTIONS

178   General daemon configuration
179       -b, --background
180           Start as a Unix daemon, but keep file descriptors (console) open.
181
182           With this option, lttng-relayd ensures the daemon is listening to
183           incoming connections before it exits.
184
185           Use the --daemonize option instead to close the file descriptors.
186
187       -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
192           See the “Daemon configuration” section above.
193
194       -d, --daemonize
195           Start as a Unix daemon and close file descriptors (console).
196
197           With this option, lttng-relayd ensures the daemon is listening to
198           incoming connections before it exits.
199
200           Use the --background option instead to keep the file descriptors
201           open.
202
203       -x, --disallow-clear
204           Disallow clearing operations (see lttng-clear(1)).
205
206           See also the LTTNG_RELAYD_DISALLOW_CLEAR environment variable.
207
208       --fd-pool-size=SIZE
209           Set the size of the file descriptor pool to SIZE file descriptors.
210
211           SIZE is the maximum number of file descriptors that the relay
212           daemon may keep open simultaneously.
213
214           Default: the soft RLIMIT_NOFILE resource limit of the process (see
215           getrlimit(2)).
216
217       -g GROUP, --group=GROUP
218           Set the Unix tracing group to GROUP instead of tracing.
219
220           This option is only meaningful when the root Unix user starts
221           lttng-relayd.
222
223           Members of the Unix tracing group may connect to the health check
224           socket of the relay daemon.
225
226           See also the LTTNG_RELAYD_HEALTH environment variable.
227
228       -w DIR, --working-directory=DIR
229           Set the working directory of the processes the relay daemon creates
230           to DIR.
231
232           See also the LTTNG_RELAYD_WORKING_DIRECTORY environment variable.
233
234       -v, --verbose
235           Increase verbosity.
236
237           Specify this option up to three times to get more levels of
238           verbosity.
239
240   Output
241       See the “Output directory” section above to learn more.
242
243       -p, --group-output-by-host
244           Group the written trace directories by hostname.
245
246           As of LTTng 2.13.7, this is the default output grouping strategy,
247           but this may change in the future.
248
249       -s, --group-output-by-session
250           Group the written trace directories by recording session name
251           instead of by hostname.
252
253       -o DIR, --output=DIR
254           Set the base output directory of the written trace directories to
255           DIR.
256
257   Ports
258       See the “URL format” section above to learn more about the syntax of
259       the URL argument of the following options.
260
261       -C URL, --control-port=URL
262           Listen to control data on URL URL.
263
264           Default: tcp://0.0.0.0:5342.
265
266       -D URL, --data-port=URL
267           Listen to trace data on URL URL.
268
269           Default: tcp://0.0.0.0:5343.
270
271       -L URL, --live-port=URL
272           Listen to LTTng live connections on URL URL.
273
274           Default: tcp://localhost:5344.
275
276   Program information
277       -h, --help
278           Show help.
279
280           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
284       --list-options
285           List available command options and quit.
286
287       -V, --version
288           Show version and quit.
289

EXIT STATUS

291       0
292           Success
293
294       1
295           Error
296
297       3
298           Fatal error
299

ENVIRONMENT

301       LTTNG_ABORT_ON_ERROR
302           Set to 1 to abort the process after the first error is encountered.
303
304       LTTNG_NETWORK_SOCKET_TIMEOUT
305           Socket connection, receive, and send timeout (milliseconds).
306
307           Set to 0 or -1 to set an infinite timeout (default).
308
309       LTTNG_RELAYD_DISALLOW_CLEAR
310           Set to 1 to disallow clearing operations (see lttng-clear(1)).
311
312           The --disallow-clear option overrides this environment variable.
313
314       LTTNG_RELAYD_HEALTH
315           Path to the health check socket of the relay daemon.
316
317       LTTNG_RELAYD_TCP_KEEP_ALIVE
318           Set to 1 to enable TCP keep-alive.
319
320           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
324           Supported on Linux and Solaris only. The default behaviour of the
325           TCP keep-alive mechanism is OS-specific.
326
327           Search for tcp_keepalive in tcp(7) to learn more.
328
329       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
333           Set to 0 or -1 to use the value chosen by the operating system
334           (default).
335
336           Supported on Solaris 11 only.
337
338           Search for tcp_keepalive_abort_threshold in tcp(7) to learn more.
339
340       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
344           Set to 0 or -1 to use the value chosen by the operating system
345           (default).
346
347           Supported on Linux and Solaris 11 only.
348
349           On Solaris 11, the accepted values are -1, 0, and 10 to 864000.
350
351           Search for tcp_keepalive_time and tcp_keepalive_interval in tcp(7)
352           on Solaris 11 to learn more.
353
354       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
359           Set to 0 or -1 to use the value chosen by the operating system
360           (default).
361
362           Supported on Linux only.
363
364           Search for tcp_keepalive_probes in tcp(7) to learn more.
365
366       LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL
367           Number of seconds between TCP keep-alive probes.
368
369           Set to 0 or -1 to use the value chosen by the operating system
370           (default).
371
372           Supported on Linux only.
373
374           Search for tcp_keepalive_intvl in tcp(7) to learn more.
375
376       LTTNG_RELAYD_WORKING_DIRECTORY
377           Working directory of the processes the relay daemon creates.
378
379           The --working-directory option overrides this environment variable.
380

FILES

382       $LTTNG_HOME/.lttng
383           Unix user’s LTTng runtime and configuration directory.
384
385       $LTTNG_HOME/lttng-traces
386           Default base output directory of LTTng traces.
387
388           Override this path with the --output option.
389
390       Note
391           $LTTNG_HOME defaults to $HOME.
392

RESOURCES

394       •   LTTng project website <https://lttng.org>
395
396       •   LTTng documentation <https://lttng.org/docs>
397
398       •   LTTng bug tracker <https://bugs.lttng.org>
399
400       •   Git repositories <https://git.lttng.org>
401
402       •   GitHub organization <https://github.com/lttng>
403
404       •   Continuous integration <https://ci.lttng.org/>
405
406       •   Mailing list <https://lists.lttng.org/> for support and
407           development: lttng-dev@lists.lttng.org
408
409       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
410
412       This program is part of the LTTng-tools project.
413
414       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

THANKS

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
424       Also thanks to the Ericsson teams working on tracing which helped us
425       greatly with detailed bug reports and unusual test cases.
426

SEE ALSO

428       babeltrace2(1), lttng(1), lttng-sessiond(8)
429
430
431
432LTTng 2.13.7                     14 June 2021                  LTTNG-RELAYD(8)
Impressum