Commit | Line | Data |
---|---|---|
f5595c32 PP |
1 | lttng-relayd(8) |
2 | =============== | |
3 | ||
4 | ||
5 | NAME | |
6 | ---- | |
7 | lttng-relayd - LTTng 2 relay daemon | |
8 | ||
9 | ||
10 | SYNOPSIS | |
11 | -------- | |
12 | [verse] | |
13 | *lttng-relayd* [option:--background | option:--daemonize] | |
14 | [option:--control-port='URL'] [option:--data-port='URL'] [option:--live-port='URL'] | |
15 | [option:--output='PATH'] [option:-v | option:-vv | option:-vvv] | |
16 | ||
17 | ||
18 | DESCRIPTION | |
19 | ----------- | |
20 | The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open | |
21 | source software package used for correlated tracing of the Linux kernel, | |
22 | user applications, and user libraries. | |
23 | ||
24 | LTTng consists of Linux kernel modules (for Linux kernel tracing) and | |
25 | dynamically loaded libraries (for user application and library tracing). | |
26 | ||
27 | The _LTTng relay daemon_ is responsible for receiving trace data from | |
28 | possibly remote LTTng session/consumer daemons and for writing it to | |
29 | the local file system. The relay daemon also accepts _LTTng live_ | |
30 | connections from compatible viewers; this is the official approach to | |
31 | viewing LTTng events as they are emitted. | |
32 | ||
33 | The relay daemon listens by default on all network interfaces to gather | |
34 | trace data, but only on localhost for LTTng live connections. | |
35 | ||
36 | The relay daemon does not require any particular permissions, as long as | |
37 | it can write to the output directory and listen on the configured ports. | |
38 | If a user is within a secured network and/or has proper firewall | |
39 | settings, `lttng-relayd` can listen to LTTng live connections from _all_ | |
c93eadad PP |
40 | network interfaces by specifying |
41 | +--live-port=tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+. | |
f5595c32 PP |
42 | |
43 | Once a trace has been streamed completely, the trace can be processed by | |
44 | any tool that can process an LTTng trace located on the local | |
45 | file system. | |
46 | ||
47 | ||
48 | [[output-directory]] | |
49 | Output directory | |
50 | ~~~~~~~~~~~~~~~~ | |
51 | By default, the relay daemon writes the traces to: | |
52 | ||
53 | [verse] | |
2ff6d569 | 54 | $LTTNG_HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN' |
f5595c32 PP |
55 | |
56 | with: | |
57 | ||
58 | 'HOSTNAME':: | |
59 | Remote hostname. | |
60 | ||
61 | 'SESSION':: | |
62 | Full session name. | |
63 | ||
64 | 'DOMAIN':: | |
65 | Tracing domain. | |
66 | ||
67 | You can override the default output directory prefix | |
2ff6d569 | 68 | (`$LTTNG_HOME/lttng-traces`) with the option:--output option. The other |
f5595c32 PP |
69 | parts depend on the remote configuration. |
70 | ||
71 | ||
72 | [[url-format]] | |
73 | URL format | |
74 | ~~~~~~~~~~ | |
75 | The option:--control-port, option:--data-port, and option:--live-port | |
76 | options specify URLs. | |
77 | ||
78 | The format of those URLs is: | |
79 | ||
80 | [verse] | |
81 | tcp://('HOST' | 'IPADDR'):__PORT__ | |
82 | ||
83 | with: | |
84 | ||
85 | ('HOST' | 'IPADDR'):: | |
86 | Binding hostname or IP address (IPv6 address *must* be enclosed in | |
87 | brackets (`[` and `]`); see | |
88 | https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). | |
89 | ||
90 | 'PORT':: | |
91 | TCP port. | |
92 | ||
93 | ||
94 | OPTIONS | |
95 | ------- | |
96 | Daemon | |
97 | ~~~~~~ | |
98 | option:-b, option:--background:: | |
99 | Start as Unix daemon, but keep file descriptors (console) open. | |
100 | Use the option:--daemonize option instead to close the file | |
101 | descriptors. | |
102 | ||
103 | option:-d, option:--daemonize:: | |
104 | Start as Unix daemon, and close file descriptors (console). Use the | |
105 | option:--background option instead to keep the file descriptors | |
106 | open. | |
107 | ||
108 | option:-g, option:--group='GROUP':: | |
109 | Use 'GROUP' as Unix tracing group (default: `tracing`). | |
110 | ||
111 | option:-o, option:--output='PATH':: | |
112 | Set base directory of written trace data to 'PATH'. | |
113 | + | |
114 | See the <<output-directory,Output directory>> section above for more | |
115 | information. | |
116 | ||
117 | option:-v, option:--verbose:: | |
118 | Increase verbosity. | |
119 | + | |
120 | Three levels of verbosity are available, which are triggered by | |
121 | appending additional `v` letters to the option | |
122 | (that is, `-vv` and `-vvv`). | |
123 | ||
124 | ||
125 | Ports | |
126 | ~~~~~ | |
127 | See the <<url-format,URL format>> section above for more information | |
128 | about the syntax of the following options' 'URL' argument. | |
129 | ||
130 | option:-C, option:--control-port='URL':: | |
c93eadad PP |
131 | Listen to control data on URL 'URL' (default: |
132 | +tcp://{default_network_control_bind_address}:{default_network_control_port}+). | |
f5595c32 PP |
133 | |
134 | option:-D, option:--data-port='URL':: | |
c93eadad PP |
135 | Listen to trace data on URL 'URL' (default: |
136 | +tcp://{default_network_data_bind_address}:{default_network_data_port}+). | |
f5595c32 PP |
137 | |
138 | option:-L, option:--live-port='URL':: | |
139 | Listen to LTTng live connections on URL 'URL' | |
c93eadad PP |
140 | (default: |
141 | +tcp://{default_network_viewer_bind_address}:{default_network_viewer_port}+). | |
f5595c32 PP |
142 | |
143 | ||
144 | Program information | |
145 | ~~~~~~~~~~~~~~~~~~~ | |
146 | option:-h, option:--help:: | |
147 | Show help. | |
148 | ||
149 | option:-V, option:--version:: | |
150 | Show version. | |
151 | ||
152 | ||
153 | ENVIRONMENT VARIABLES | |
154 | --------------------- | |
9bbd8e06 MD |
155 | `LTTNG_ABORT_ON_ERROR`:: |
156 | Set to 1 to abort the process after the first error is encountered. | |
157 | ||
f5595c32 PP |
158 | `LTTNG_NETWORK_SOCKET_TIMEOUT`:: |
159 | Socket connection, receive and send timeout (milliseconds). A value | |
160 | of 0 or -1 uses the timeout of the operating system (default). | |
161 | ||
162 | `LTTNG_RELAYD_HEALTH`:: | |
163 | Path to relay daemon health's socket. | |
164 | ||
165 | ||
900690ca PP |
166 | FILES |
167 | ----- | |
168 | `$LTTNG_HOME/.lttng`:: | |
169 | User LTTng runtime and configuration directory. | |
170 | ||
171 | `$LTTNG_HOME/lttng-traces`:: | |
172 | Default output directory of LTTng traces. This can be overridden | |
173 | with the option:--output option. | |
174 | ||
175 | NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. | |
176 | ||
177 | ||
f5595c32 PP |
178 | EXIT STATUS |
179 | ----------- | |
180 | *0*:: | |
181 | Success | |
182 | ||
183 | *1*:: | |
184 | Error | |
185 | ||
186 | *3*:: | |
187 | Fatal error | |
188 | ||
189 | ||
190 | LIMITATIONS | |
191 | ----------- | |
192 | As of this version, only the TCP protocol is supported for both control | |
193 | and data ports. In future versions, TCP will remain the sole available | |
194 | protocol for control data since those communications are low-volume and | |
195 | need absolute reliability; trace data could be carried over UDP. | |
196 | ||
197 | For an unprivileged user running `lttng-relayd`, the maximum number of | |
198 | file descriptors per process is usually 1024. This limits the number of | |
199 | connections and opened trace files. This limit can be configured with | |
200 | *ulimit*(3). | |
201 | ||
202 | ||
203 | include::common-footer.txt[] | |
204 | ||
205 | ||
206 | SEE ALSO | |
207 | -------- | |
7c1a4458 PP |
208 | man:lttng(1), |
209 | man:lttng-sessiond(8), | |
210 | man:lttng-crash(1), | |
211 | man:lttng-ust(3), | |
212 | man:babeltrace(1) |