1LTTNG-RELAYD(8) LTTng Manual LTTNG-RELAYD(8)
2
3
4
6 lttng-relayd - LTTng 2 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=PATH]
12 [-v | -vv | -vvv] [--working-directory=PATH]
13 [--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 The LTTng relay daemon is responsible for receiving trace data from
25 possibly remote LTTng session/consumer daemons and for writing it to
26 the local file system. The relay daemon also accepts LTTng live
27 connections from compatible viewers; this is the official approach to
28 viewing LTTng events as they are emitted.
29
30 The relay daemon listens by default on all network interfaces to gather
31 trace data, but only on localhost for LTTng live connections.
32
33 The relay daemon does not require any particular permissions, as long
34 as it can write to the output directory and listen on the configured
35 ports. If a user is within a secured network and/or has proper firewall
36 settings, lttng-relayd can listen to LTTng live connections from all
37 network interfaces by specifying --live-port=tcp://0.0.0.0:5344.
38
39 Once a trace has been streamed completely, the trace can be processed
40 by any tool that can process an LTTng trace located on the local file
41 system.
42
43 Output directory
44 The relay daemon uses different output path patterns depending on:
45
46 · Its configuration.
47
48 · The connected peer’s tracing session configuration.
49
50 · The connected peer’s LTTng session daemon (see lttng-sessiond(8))
51 version.
52
53 Consider the following variables:
54
55 BASE
56 Base output directory: $LTTNG_HOME/lttng-traces or the argument of
57 the --output option.
58
59 Note
60 $LTTNG_HOME defaults to $HOME when not explicitly set.
61
62 HOSTNAME
63 Peer’s hostname.
64
65 SESSION
66 Tracing session name.
67
68 DATETIME
69 Unique tracing session date/time.
70
71 TRACEPATH
72 Custom trace path (TRACEPATH part of the lttng-create(1) command’s
73 --set-url option’s argument, if any).
74
75 The relay daemon output path patterns are:
76
77 Hostname grouping (without --group-output-by-session)
78
79 Without a custom trace path
80
81 BASE/HOSTNAME/SESSION-DATETIME
82
83 With a custom trace path
84
85 BASE/HOSTNAME/TRACEPATH
86
87 Tracing session grouping (with --group-output-by-session)
88
89 Without a custom trace path
90
91 The peer’s LTTng session daemon version is at least 2.4
92
93 BASE/SESSION/HOSTNAME-DATETIME
94
95 Otherwise
96 Defaults to the hostname grouping pattern:
97
98 BASE/HOSTNAME/SESSION-DATETIME
99
100 With a custom trace path
101
102 The peer’s LTTng session daemon version is at least 2.4
103
104 BASE/SESSION/HOSTNAME-DATETIME/TRACEPATH
105
106 Otherwise
107 Defaults to the hostname grouping pattern:
108
109 BASE/HOSTNAME/TRACEPATH
110
111 URL format
112 The --control-port, --data-port, and --live-port options specify URLs.
113
114 The format of those URLs is:
115
116 tcp://(HOST | IPADDR):PORT
117
118 with:
119
120 (HOST | IPADDR)
121 Binding hostname or IP address (IPv6 address must be enclosed in
122 brackets ([ and ]); see RFC 2732
123 <https://www.ietf.org/rfc/rfc2732.txt>).
124
125 PORT
126 TCP port.
127
129 Daemon
130 -b, --background
131 Start as Unix daemon, but keep file descriptors (console) open. Use
132 the --daemonize option instead to close the file descriptors.
133
134 -f PATH, --config=PATH
135 Load relay daemon configuration from path PATH.
136
137 -d, --daemonize
138 Start as Unix daemon, and close file descriptors (console). Use the
139 --background option instead to keep the file descriptors open.
140
141 -x, --disallow-clear
142 Disallow clearing operations (see lttng-clear(1)).
143
144 See also the LTTNG_RELAYD_DISALLOW_CLEAR environment variable.
145
146 --fd-pool-size=SIZE
147 Set the size of the file descriptor pool to SIZE.
148
149 SIZE is the maximum number of file descriptors that may be kept
150 opened simultaneously by the relay daemon.
151
152 Default: the soft RLIMIT_NOFILE resource limit of the process (see
153 getrlimit(2)).
154
155 -g GROUP, --group=GROUP
156 Use GROUP as Unix tracing group (default: tracing).
157
158 -w PATH, --working-directory=PATH
159 Set the working directory of the processes the relay daemon creates
160 to PATH.
161
162 See also the LTTNG_RELAYD_WORKING_DIRECTORY environment variable.
163
164 -v, --verbose
165 Increase verbosity.
166
167 Three levels of verbosity are available, which are triggered by
168 appending additional v letters to the option (that is, -vv and
169 -vvv).
170
171 Output
172 See the Output directory section above for more information.
173
174 -p, --group-output-by-host
175 Group the written trace directories by hostname (default).
176
177 -s, --group-output-by-session
178 Group the written trace directories by tracing session name instead
179 of by hostname.
180
181 -o PATH, --output=PATH
182 Set the base output directory of the written trace directories to
183 PATH.
184
185 Ports
186 See the URL format section above for more information about the syntax
187 of the following URL argument.
188
189 -C URL, --control-port=URL
190 Listen to control data on URL URL (default: tcp://0.0.0.0:5342).
191
192 -D URL, --data-port=URL
193 Listen to trace data on URL URL (default: tcp://0.0.0.0:5343).
194
195 -L URL, --live-port=URL
196 Listen to LTTng live connections on URL URL (default:
197 tcp://localhost:5344).
198
199 Program information
200 -h, --help
201 Show help.
202
203 -V, --version
204 Show version.
205
207 LTTNG_ABORT_ON_ERROR
208 Set to 1 to abort the process after the first error is encountered.
209
210 LTTNG_NETWORK_SOCKET_TIMEOUT
211 Socket connection, receive and send timeout (milliseconds). A value
212 of 0 or -1 uses the timeout of the operating system (default).
213
214 LTTNG_RELAYD_DISALLOW_CLEAR
215 Set to 1 to disallow clearing operations (see lttng-clear(1)).
216
217 The --disallow-clear option overrides this variable.
218
219 LTTNG_RELAYD_HEALTH
220 Path to relay daemon health’s socket.
221
222 LTTNG_RELAYD_TCP_KEEP_ALIVE
223 Set to 1 to enable TCP keep-alive.
224
225 The TCP keep-alive mechanism allows the detection of dead peers
226 (lttng-sessiond(8)) in cases of unclean termination (for example, a
227 hard reset) of a peer.
228
229 Supported on Linux and Solaris only. The default behaviour of the
230 TCP keep-alive mechanism is OS-specific.
231
232 Search for tcp_keepalive in tcp(7) for more information.
233
234 LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD
235 The time threshold in seconds to abort a TCP connection after the
236 keep-alive probing mechanism has failed.
237
238 Set to 0 or -1 to use the value chosen by the operating system
239 (default).
240
241 Supported on Solaris 11 only.
242
243 Search for tcp_keepalive_abort_threshold in tcp(7) for more
244 information.
245
246 LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME
247 Number of seconds a connection needs to be idle before TCP begins
248 sending out keep-alive probes.
249
250 Set to 0 or -1 to use the value chosen by the operating system
251 (default).
252
253 Supported on Linux and Solaris 11 only.
254
255 On Solaris 11, the accepted values are -1, 0, and 10 to 864000.
256
257 Search for tcp_keepalive_time and tcp_keepalive_interval in tcp(7)
258 on Solaris 11 for more information.
259
260 LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT
261 Maximum number of TCP keep-alive probes to send before giving up
262 and killing the connection if no response is obtained from the
263 other end.
264
265 Set to 0 or -1 to use the value chosen by the operating system
266 (default).
267
268 Supported on Linux only.
269
270 Search for tcp_keepalive_probes in tcp(7) for more information.
271
272 LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL
273 Number of seconds between TCP keep-alive probes.
274
275 Set to 0 or -1 to use the value chosen by the operating system
276 (default).
277
278 Supported on Linux only.
279
280 Search for tcp_keepalive_intvl in tcp(7) for more information.
281
282 LTTNG_RELAYD_WORKING_DIRECTORY
283 Working directory of the processes the relay daemon creates.
284
285 The --working-directory option overrides this variable.
286
288 $LTTNG_HOME/.lttng
289 User LTTng runtime and configuration directory.
290
291 $LTTNG_HOME/lttng-traces
292 Default base output directory of LTTng traces. This can be
293 overridden with the --output option.
294
295 Note
296 $LTTNG_HOME defaults to $HOME when not explicitly set.
297
299 0
300 Success
301
302 1
303 Error
304
305 3
306 Fatal error
307
309 As of this version, only the TCP protocol is supported for both control
310 and data ports. In future versions, TCP will remain the sole available
311 protocol for control data since those communications are low-volume and
312 need absolute reliability; trace data could be carried over UDP.
313
314 For an unprivileged user running lttng-relayd, the maximum number of
315 file descriptors per process is usually 1024. This limits the number of
316 connections and opened trace files. This limit can be configured with
317 ulimit(3).
318
320 If you encounter any issue or usability problem, please report it on
321 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
322
324 · LTTng project website <https://lttng.org>
325
326 · LTTng documentation <https://lttng.org/docs>
327
328 · Git repositories <http://git.lttng.org>
329
330 · GitHub organization <http://github.com/lttng>
331
332 · Continuous integration <http://ci.lttng.org/>
333
334 · Mailing list <http://lists.lttng.org> for support and development:
335 lttng-dev@lists.lttng.org
336
337 · IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
338
340 This program is part of the LTTng-tools project.
341
342 LTTng-tools is distributed under the GNU General Public License version
343 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
344 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
345 for details.
346
348 Special thanks to Michel Dagenais and the DORSAL laboratory
349 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
350 the LTTng journey.
351
352 Also thanks to the Ericsson teams working on tracing which helped us
353 greatly with detailed bug reports and unusual test cases.
354
356 lttng(1), lttng-sessiond(8), lttng-crash(1), lttng-ust(3),
357 babeltrace2(1)
358
359
360
361LTTng 2.12.2 2 April 2020 LTTNG-RELAYD(8)