LTTNG-RELAYD(8): document the --fd-pool-size option
[lttng-tools.git] / doc / man / lttng-relayd.8.txt
CommitLineData
f5595c32
PP
1lttng-relayd(8)
2===============
4605890e 3:revdate: 5 June 2018
f5595c32
PP
4
5
6NAME
7----
8lttng-relayd - LTTng 2 relay daemon
9
10
11SYNOPSIS
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
20DESCRIPTION
21-----------
a18d9544 22The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
f5595c32
PP
23source software package used for correlated tracing of the Linux kernel,
24user applications, and user libraries.
25
26LTTng consists of Linux kernel modules (for Linux kernel tracing) and
27dynamically loaded libraries (for user application and library tracing).
28
29The _LTTng relay daemon_ is responsible for receiving trace data from
30possibly remote LTTng session/consumer daemons and for writing it to
31the local file system. The relay daemon also accepts _LTTng live_
32connections from compatible viewers; this is the official approach to
33viewing LTTng events as they are emitted.
34
35The relay daemon listens by default on all network interfaces to gather
36trace data, but only on localhost for LTTng live connections.
37
38The relay daemon does not require any particular permissions, as long as
39it can write to the output directory and listen on the configured ports.
40If a user is within a secured network and/or has proper firewall
41settings, `lttng-relayd` can listen to LTTng live connections from _all_
c93eadad 42network interfaces by specifying
e9b02942 43+--live-port=tcp://0.0.0.0:{default_network_viewer_port}+.
f5595c32
PP
44
45Once a trace has been streamed completely, the trace can be processed by
46any tool that can process an LTTng trace located on the local
47file system.
48
49
50[[output-directory]]
51Output directory
52~~~~~~~~~~~~~~~~
04dedfc0
JR
53By default (option:--group-output-by-host), the relay daemon writes the traces
54to:
f5595c32
PP
55
56[verse]
2ff6d569 57$LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN'
f5595c32
PP
58
59with:
60
61'HOSTNAME'::
62 Remote hostname.
63
64'SESSION'::
65 Full session name.
66
67'DOMAIN'::
68 Tracing domain.
69
04dedfc0
JR
70You can group the output per session instead of per hostname with the
71option:--group-output-by-session option. This result in the following:
72
73[verse]
74
75$LTTNG_HOME/lttng-traces/'SESSION'/'HOST'/'DOMAIN'
76
f5595c32 77You can override the default output directory prefix
2ff6d569 78(`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other
f5595c32
PP
79parts depend on the remote configuration.
80
04dedfc0
JR
81Grouping by session is not supported for peers with version inferior to 2.4.
82In such cases, the grouping of output for that particular peer will be per host
83(default).
84
85A best effort backward compatibility is done for peers version greater or equal to
862.4 and smaller than 2.11.
f5595c32
PP
87
88[[url-format]]
89URL format
90~~~~~~~~~~
91The option:--control-port, option:--data-port, and option:--live-port
92options specify URLs.
93
94The format of those URLs is:
95
96[verse]
97tcp://('HOST' | 'IPADDR'):__PORT__
98
99with:
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
110OPTIONS
111-------
112Daemon
113~~~~~~
114option:-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
119option:-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
124option:--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 130option:-g 'GROUP', option:--group='GROUP'::
f5595c32
PP
131 Use 'GROUP' as Unix tracing group (default: `tracing`).
132
59b19c3c 133option:-o 'PATH', option:--output='PATH'::
f5595c32
PP
134 Set base directory of written trace data to 'PATH'.
135+
136See the <<output-directory,Output directory>> section above for more
137information.
138
04dedfc0
JR
139option:-p, option:--group-output-by-host::
140 Organize the output directory by host. Default behavior.
141+
142See the <<output-directory,Output directory>> section above for more
143information.
144
145option:-s, option:--group-output-by-session::
146 Organize the output directory by session.
147+
148See the <<output-directory,Output directory>> section above for more
149information.
150
6ab3f69a
JR
151option:-w 'PATH', option:--working-directory='PATH'::
152 Set the working directory of the processes this relay daemon creates.
153
f5595c32
PP
154option:-v, option:--verbose::
155 Increase verbosity.
156+
157Three levels of verbosity are available, which are triggered by
158appending additional `v` letters to the option
159(that is, `-vv` and `-vvv`).
160
161
162Ports
163~~~~~
164See the <<url-format,URL format>> section above for more information
165about the syntax of the following options' 'URL' argument.
166
59b19c3c 167option:-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 171option:-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 175option:-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
181Program information
182~~~~~~~~~~~~~~~~~~~
183option:-h, option:--help::
184 Show help.
185
186option:-V, option:--version::
187 Show version.
188
189
190ENVIRONMENT 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+
209The 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+
213Supported on Linux and Solaris only. The default behaviour of the TCP
214keep-alive mechanism is OS-specific.
215+
216Search 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+
222Set to 0 or -1 to use the value chosen by the operating system (default).
223+
224Supported on Solaris 11 only.
225+
226Search 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+
232Set to 0 or -1 to use the value chosen by the operating system (default).
233+
234Supported on Linux and Solaris 11 only.
235+
236On Solaris{nbsp}11, the accepted values are -1, 0, and 10 to 864000.
237+
238Search for `tcp_keepalive_time` and `tcp_keepalive_interval`
239in 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+
245Set to 0 or -1 to use the value chosen by the operating system (default).
246+
247Supported on Linux only.
248+
249Search 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+
254Set to 0 or -1 to use the value chosen by the operating system (default).
255+
256Supported on Linux only.
257+
258Search 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+
263The option:--working-directory option overrides this variable.
264
f5595c32 265
900690ca
PP
266FILES
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
275NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
276
277
f5595c32
PP
278EXIT STATUS
279-----------
280*0*::
281 Success
282
283*1*::
284 Error
285
286*3*::
287 Fatal error
288
289
290LIMITATIONS
291-----------
292As of this version, only the TCP protocol is supported for both control
293and data ports. In future versions, TCP will remain the sole available
294protocol for control data since those communications are low-volume and
295need absolute reliability; trace data could be carried over UDP.
296
297For an unprivileged user running `lttng-relayd`, the maximum number of
298file descriptors per process is usually 1024. This limits the number of
299connections and opened trace files. This limit can be configured with
300*ulimit*(3).
301
302
303include::common-footer.txt[]
304
305
306SEE ALSO
307--------
7c1a4458
PP
308man:lttng(1),
309man:lttng-sessiond(8),
310man:lttng-crash(1),
311man:lttng-ust(3),
312man:babeltrace(1)
This page took 0.075218 seconds and 5 git commands to generate.