Commit | Line | Data |
---|---|---|
f5595c32 PP |
1 | lttng-relayd(8) |
2 | =============== | |
c590aa64 | 3 | :revdate: 2 April 2020 |
f5595c32 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-relayd - LTTng 2 relay daemon | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
14 | *lttng-relayd* [option:--background | option:--daemonize] | |
89751b02 JG |
15 | [option:--control-port='URL'] [option:--data-port='URL'] [option:--fd-pool-size='COUNT'] |
16 | [option:--live-port='URL'] [option:--output='PATH'] | |
17 | [option:-v | option:-vv | option:-vvv] [option:--working-directory='PATH'] | |
c590aa64 PP |
18 | [option:--group-output-by-session] [option:--disallow-clear] |
19 | ||
f5595c32 PP |
20 | |
21 | DESCRIPTION | |
22 | ----------- | |
a18d9544 | 23 | The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open |
f5595c32 PP |
24 | source software package used for correlated tracing of the Linux kernel, |
25 | user applications, and user libraries. | |
26 | ||
27 | LTTng consists of Linux kernel modules (for Linux kernel tracing) and | |
28 | dynamically loaded libraries (for user application and library tracing). | |
29 | ||
30 | The _LTTng relay daemon_ is responsible for receiving trace data from | |
31 | possibly remote LTTng session/consumer daemons and for writing it to | |
32 | the local file system. The relay daemon also accepts _LTTng live_ | |
33 | connections from compatible viewers; this is the official approach to | |
34 | viewing LTTng events as they are emitted. | |
35 | ||
36 | The relay daemon listens by default on all network interfaces to gather | |
37 | trace data, but only on localhost for LTTng live connections. | |
38 | ||
39 | The relay daemon does not require any particular permissions, as long as | |
40 | it can write to the output directory and listen on the configured ports. | |
41 | If a user is within a secured network and/or has proper firewall | |
42 | settings, `lttng-relayd` can listen to LTTng live connections from _all_ | |
c93eadad | 43 | network interfaces by specifying |
e9b02942 | 44 | +--live-port=tcp://0.0.0.0:{default_network_viewer_port}+. |
f5595c32 PP |
45 | |
46 | Once a trace has been streamed completely, the trace can be processed by | |
47 | any tool that can process an LTTng trace located on the local | |
48 | file system. | |
49 | ||
50 | ||
51 | [[output-directory]] | |
52 | Output directory | |
53 | ~~~~~~~~~~~~~~~~ | |
c590aa64 | 54 | The relay daemon uses different output path patterns depending on: |
f5595c32 | 55 | |
c590aa64 PP |
56 | * Its configuration. |
57 | * The connected peer's tracing session configuration. | |
58 | * The connected peer's LTTng session daemon (see man:lttng-sessiond(8)) | |
59 | version. | |
f5595c32 | 60 | |
c590aa64 PP |
61 | Consider the following variables: |
62 | ||
63 | 'BASE':: | |
64 | Base output directory: `$LTTNG_HOME/lttng-traces` or the | |
65 | argument of the option:--output option. | |
66 | + | |
67 | NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. | |
f5595c32 PP |
68 | |
69 | 'HOSTNAME':: | |
c590aa64 | 70 | Peer's hostname. |
f5595c32 PP |
71 | |
72 | 'SESSION':: | |
c590aa64 PP |
73 | Tracing session name. |
74 | ||
75 | 'DATETIME':: | |
76 | Unique tracing session date/time. | |
f5595c32 | 77 | |
c590aa64 PP |
78 | 'TRACEPATH':: |
79 | Custom trace path ('TRACEPATH' part of the man:lttng-create(1) | |
80 | command's nloption:--set-url option's argument, if any). | |
f5595c32 | 81 | |
c590aa64 PP |
82 | The relay daemon output path patterns are: |
83 | ||
84 | Hostname grouping (without option:--group-output-by-session):: | |
85 | Without a custom trace path::: | |
86 | + | |
87 | -- | |
88 | [verse] | |
89 | 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' | |
90 | -- | |
91 | ||
92 | With a custom trace path::: | |
93 | + | |
94 | -- | |
95 | [verse] | |
96 | 'BASE'/'HOSTNAME'/'TRACEPATH' | |
97 | -- | |
04dedfc0 | 98 | |
c590aa64 PP |
99 | Tracing session grouping (with option:--group-output-by-session):: |
100 | Without a custom trace path::: | |
101 | The peer's LTTng session daemon version is at least 2.4:::: | |
102 | + | |
103 | -- | |
04dedfc0 | 104 | [verse] |
c590aa64 PP |
105 | 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME' |
106 | -- | |
04dedfc0 | 107 | |
c590aa64 PP |
108 | Otherwise:::: |
109 | Defaults to the hostname grouping pattern: | |
110 | + | |
111 | -- | |
112 | [verse] | |
113 | 'BASE'/'HOSTNAME'/'SESSION'-'DATETIME' | |
114 | -- | |
04dedfc0 | 115 | |
c590aa64 PP |
116 | With a custom trace path::: |
117 | The peer's LTTng session daemon version is at least 2.4:::: | |
118 | + | |
119 | -- | |
120 | [verse] | |
121 | 'BASE'/'SESSION'/'HOSTNAME'-'DATETIME'/'TRACEPATH' | |
122 | -- | |
f5595c32 | 123 | |
c590aa64 PP |
124 | Otherwise:::: |
125 | Defaults to the hostname grouping pattern: | |
126 | + | |
127 | -- | |
128 | [verse] | |
129 | 'BASE'/'HOSTNAME'/'TRACEPATH' | |
130 | -- | |
04dedfc0 | 131 | |
f5595c32 PP |
132 | |
133 | [[url-format]] | |
134 | URL format | |
135 | ~~~~~~~~~~ | |
136 | The option:--control-port, option:--data-port, and option:--live-port | |
137 | options specify URLs. | |
138 | ||
139 | The format of those URLs is: | |
140 | ||
141 | [verse] | |
142 | tcp://('HOST' | 'IPADDR'):__PORT__ | |
143 | ||
144 | with: | |
145 | ||
146 | ('HOST' | 'IPADDR'):: | |
147 | Binding hostname or IP address (IPv6 address *must* be enclosed in | |
148 | brackets (`[` and `]`); see | |
149 | https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). | |
150 | ||
151 | 'PORT':: | |
152 | TCP port. | |
153 | ||
154 | ||
155 | OPTIONS | |
156 | ------- | |
157 | Daemon | |
158 | ~~~~~~ | |
159 | option:-b, option:--background:: | |
160 | Start as Unix daemon, but keep file descriptors (console) open. | |
161 | Use the option:--daemonize option instead to close the file | |
162 | descriptors. | |
163 | ||
164 | option:-d, option:--daemonize:: | |
165 | Start as Unix daemon, and close file descriptors (console). Use the | |
166 | option:--background option instead to keep the file descriptors | |
167 | open. | |
168 | ||
c590aa64 PP |
169 | option:-x, option:--disallow-clear:: |
170 | Disallow clearing operations (see man:lttng-clear(1)). | |
f5595c32 | 171 | + |
c590aa64 | 172 | See also the `LTTNG_RELAYD_DISALLOW_CLEAR` environment variable. |
f5595c32 | 173 | |
c590aa64 PP |
174 | option:--fd-pool-size='SIZE':: |
175 | Set the size of the file descriptor pool to 'SIZE'. | |
04dedfc0 | 176 | + |
c590aa64 PP |
177 | 'SIZE' is the maximum number of file descriptors that may be kept opened |
178 | simultaneously by the relay daemon. | |
04dedfc0 | 179 | + |
c590aa64 PP |
180 | Default: the soft `RLIMIT_NOFILE` resource limit of the process (see |
181 | man:getrlimit(2)). | |
182 | ||
183 | option:-g 'GROUP', option:--group='GROUP':: | |
184 | Use 'GROUP' as Unix tracing group (default: `tracing`). | |
04dedfc0 | 185 | |
6ab3f69a | 186 | option:-w 'PATH', option:--working-directory='PATH':: |
c590aa64 PP |
187 | Set the working directory of the processes the relay daemon creates |
188 | to 'PATH'. | |
189 | + | |
190 | See also the `LTTNG_RELAYD_WORKING_DIRECTORY` environment variable. | |
6ab3f69a | 191 | |
f5595c32 PP |
192 | option:-v, option:--verbose:: |
193 | Increase verbosity. | |
194 | + | |
195 | Three levels of verbosity are available, which are triggered by | |
196 | appending additional `v` letters to the option | |
197 | (that is, `-vv` and `-vvv`). | |
198 | ||
199 | ||
c590aa64 PP |
200 | Output |
201 | ~~~~~~ | |
202 | See the <<output-directory,Output directory>> section above for more | |
203 | information. | |
204 | ||
205 | option:-p, option:--group-output-by-host:: | |
206 | Group the written trace directories by hostname (default). | |
207 | ||
208 | option:-s, option:--group-output-by-session:: | |
209 | Group the written trace directories by tracing session name instead | |
210 | of by hostname. | |
211 | ||
212 | option:-o 'PATH', option:--output='PATH':: | |
213 | Set the base output directory of the written trace directories to | |
214 | 'PATH'. | |
215 | ||
216 | ||
f5595c32 PP |
217 | Ports |
218 | ~~~~~ | |
219 | See the <<url-format,URL format>> section above for more information | |
c590aa64 | 220 | about the syntax of the following 'URL' argument. |
f5595c32 | 221 | |
59b19c3c | 222 | option:-C 'URL', option:--control-port='URL':: |
c93eadad PP |
223 | Listen to control data on URL 'URL' (default: |
224 | +tcp://{default_network_control_bind_address}:{default_network_control_port}+). | |
f5595c32 | 225 | |
59b19c3c | 226 | option:-D 'URL', option:--data-port='URL':: |
c93eadad PP |
227 | Listen to trace data on URL 'URL' (default: |
228 | +tcp://{default_network_data_bind_address}:{default_network_data_port}+). | |
f5595c32 | 229 | |
59b19c3c | 230 | option:-L 'URL', option:--live-port='URL':: |
f5595c32 | 231 | Listen to LTTng live connections on URL 'URL' |
c93eadad PP |
232 | (default: |
233 | +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+). | |
f5595c32 PP |
234 | |
235 | ||
236 | Program information | |
237 | ~~~~~~~~~~~~~~~~~~~ | |
238 | option:-h, option:--help:: | |
239 | Show help. | |
240 | ||
241 | option:-V, option:--version:: | |
242 | Show version. | |
243 | ||
244 | ||
245 | ENVIRONMENT VARIABLES | |
246 | --------------------- | |
9bbd8e06 MD |
247 | `LTTNG_ABORT_ON_ERROR`:: |
248 | Set to 1 to abort the process after the first error is encountered. | |
249 | ||
f5595c32 PP |
250 | `LTTNG_NETWORK_SOCKET_TIMEOUT`:: |
251 | Socket connection, receive and send timeout (milliseconds). A value | |
252 | of 0 or -1 uses the timeout of the operating system (default). | |
253 | ||
06e1d71f | 254 | `LTTNG_RELAYD_DISALLOW_CLEAR`:: |
c590aa64 PP |
255 | Set to 1 to disallow clearing operations (see man:lttng-clear(1)). |
256 | + | |
257 | The option:--disallow-clear option overrides this variable. | |
06e1d71f | 258 | |
f5595c32 PP |
259 | `LTTNG_RELAYD_HEALTH`:: |
260 | Path to relay daemon health's socket. | |
261 | ||
e0512bf5 JR |
262 | `LTTNG_RELAYD_TCP_KEEP_ALIVE`:: |
263 | Set to 1 to enable TCP keep-alive. | |
264 | + | |
265 | The TCP keep-alive mechanism allows the detection of dead peers | |
266 | (man:lttng-sessiond(8)) in cases of unclean termination | |
267 | (for example, a hard reset) of a peer. | |
268 | + | |
269 | Supported on Linux and Solaris only. The default behaviour of the TCP | |
270 | keep-alive mechanism is OS-specific. | |
271 | + | |
272 | Search for `tcp_keepalive` in man:tcp(7) for more information. | |
273 | ||
274 | `LTTNG_RELAYD_TCP_KEEP_ALIVE_ABORT_THRESHOLD`:: | |
275 | The time threshold in seconds to abort a TCP connection after the keep-alive | |
276 | probing mechanism has failed. | |
277 | + | |
278 | Set to 0 or -1 to use the value chosen by the operating system (default). | |
279 | + | |
280 | Supported on Solaris 11 only. | |
281 | + | |
282 | Search for `tcp_keepalive_abort_threshold` in man:tcp(7) for more information. | |
283 | ||
284 | `LTTNG_RELAYD_TCP_KEEP_ALIVE_IDLE_TIME`:: | |
285 | Number of seconds a connection needs to be idle before TCP begins | |
286 | sending out keep-alive probes. | |
287 | + | |
288 | Set to 0 or -1 to use the value chosen by the operating system (default). | |
289 | + | |
290 | Supported on Linux and Solaris 11 only. | |
291 | + | |
292 | On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000. | |
293 | + | |
294 | Search for `tcp_keepalive_time` and `tcp_keepalive_interval` | |
295 | in man:tcp(7) on Solaris 11 for more information. | |
296 | ||
297 | `LTTNG_RELAYD_TCP_KEEP_ALIVE_MAX_PROBE_COUNT`:: | |
298 | Maximum number of TCP keep-alive probes to send before giving up and | |
299 | killing the connection if no response is obtained from the other end. | |
300 | + | |
301 | Set to 0 or -1 to use the value chosen by the operating system (default). | |
302 | + | |
303 | Supported on Linux only. | |
304 | + | |
305 | Search for `tcp_keepalive_probes` in man:tcp(7) for more information. | |
306 | ||
307 | `LTTNG_RELAYD_TCP_KEEP_ALIVE_PROBE_INTERVAL`:: | |
308 | Number of seconds between TCP keep-alive probes. | |
309 | + | |
310 | Set to 0 or -1 to use the value chosen by the operating system (default). | |
311 | + | |
312 | Supported on Linux only. | |
313 | + | |
314 | Search for `tcp_keepalive_intvl` in man:tcp(7) for more information. | |
315 | ||
508a802c | 316 | `LTTNG_RELAYD_WORKING_DIRECTORY`:: |
c590aa64 | 317 | Working directory of the processes the relay daemon creates. |
508a802c JR |
318 | + |
319 | The option:--working-directory option overrides this variable. | |
320 | ||
f5595c32 | 321 | |
900690ca PP |
322 | FILES |
323 | ----- | |
324 | `$LTTNG_HOME/.lttng`:: | |
325 | User LTTng runtime and configuration directory. | |
326 | ||
327 | `$LTTNG_HOME/lttng-traces`:: | |
c590aa64 PP |
328 | Default base output directory of LTTng traces. This can be |
329 | overridden with the option:--output option. | |
900690ca PP |
330 | |
331 | NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. | |
332 | ||
333 | ||
f5595c32 PP |
334 | EXIT STATUS |
335 | ----------- | |
336 | *0*:: | |
337 | Success | |
338 | ||
339 | *1*:: | |
340 | Error | |
341 | ||
342 | *3*:: | |
343 | Fatal error | |
344 | ||
345 | ||
346 | LIMITATIONS | |
347 | ----------- | |
348 | As of this version, only the TCP protocol is supported for both control | |
349 | and data ports. In future versions, TCP will remain the sole available | |
350 | protocol for control data since those communications are low-volume and | |
351 | need absolute reliability; trace data could be carried over UDP. | |
352 | ||
353 | For an unprivileged user running `lttng-relayd`, the maximum number of | |
354 | file descriptors per process is usually 1024. This limits the number of | |
355 | connections and opened trace files. This limit can be configured with | |
356 | *ulimit*(3). | |
357 | ||
358 | ||
359 | include::common-footer.txt[] | |
360 | ||
361 | ||
362 | SEE ALSO | |
363 | -------- | |
7c1a4458 PP |
364 | man:lttng(1), |
365 | man:lttng-sessiond(8), | |
366 | man:lttng-crash(1), | |
367 | man:lttng-ust(3), | |
392dcc0a | 368 | man:babeltrace2(1) |