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