1LTTNG-RELAYD(8) LTTng Manual LTTNG-RELAYD(8)
2
3
4
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
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
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
291 0
292 Success
293
294 1
295 Error
296
297 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
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
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
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
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
428 babeltrace2(1), lttng(1), lttng-sessiond(8)
429
430
431
432LTTng 2.13.7 14 June 2021 LTTNG-RELAYD(8)