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_ | |
40 | network interfaces by specifying `--live-port=tcp://0.0.0.0:5344`. | |
41 | ||
42 | Once a trace has been streamed completely, the trace can be processed by | |
43 | any tool that can process an LTTng trace located on the local | |
44 | file system. | |
45 | ||
46 | ||
47 | [[output-directory]] | |
48 | Output directory | |
49 | ~~~~~~~~~~~~~~~~ | |
50 | By default, the relay daemon writes the traces to: | |
51 | ||
52 | [verse] | |
53 | $HOME/lttng-traces/'HOSTNAME'/'SESSION'/'DOMAIN' | |
54 | ||
55 | with: | |
56 | ||
57 | 'HOSTNAME':: | |
58 | Remote hostname. | |
59 | ||
60 | 'SESSION':: | |
61 | Full session name. | |
62 | ||
63 | 'DOMAIN':: | |
64 | Tracing domain. | |
65 | ||
66 | You can override the default output directory prefix | |
67 | (`$HOME/lttng-traces`) with the option:--output option. The other | |
68 | parts depend on the remote configuration. | |
69 | ||
70 | ||
71 | [[url-format]] | |
72 | URL format | |
73 | ~~~~~~~~~~ | |
74 | The option:--control-port, option:--data-port, and option:--live-port | |
75 | options specify URLs. | |
76 | ||
77 | The format of those URLs is: | |
78 | ||
79 | [verse] | |
80 | tcp://('HOST' | 'IPADDR'):__PORT__ | |
81 | ||
82 | with: | |
83 | ||
84 | ('HOST' | 'IPADDR'):: | |
85 | Binding hostname or IP address (IPv6 address *must* be enclosed in | |
86 | brackets (`[` and `]`); see | |
87 | https://www.ietf.org/rfc/rfc2732.txt[RFC 2732]). | |
88 | ||
89 | 'PORT':: | |
90 | TCP port. | |
91 | ||
92 | ||
93 | OPTIONS | |
94 | ------- | |
95 | Daemon | |
96 | ~~~~~~ | |
97 | option:-b, option:--background:: | |
98 | Start as Unix daemon, but keep file descriptors (console) open. | |
99 | Use the option:--daemonize option instead to close the file | |
100 | descriptors. | |
101 | ||
102 | option:-d, option:--daemonize:: | |
103 | Start as Unix daemon, and close file descriptors (console). Use the | |
104 | option:--background option instead to keep the file descriptors | |
105 | open. | |
106 | ||
107 | option:-g, option:--group='GROUP':: | |
108 | Use 'GROUP' as Unix tracing group (default: `tracing`). | |
109 | ||
110 | option:-o, option:--output='PATH':: | |
111 | Set base directory of written trace data to 'PATH'. | |
112 | + | |
113 | See the <<output-directory,Output directory>> section above for more | |
114 | information. | |
115 | ||
116 | option:-v, option:--verbose:: | |
117 | Increase verbosity. | |
118 | + | |
119 | Three levels of verbosity are available, which are triggered by | |
120 | appending additional `v` letters to the option | |
121 | (that is, `-vv` and `-vvv`). | |
122 | ||
123 | ||
124 | Ports | |
125 | ~~~~~ | |
126 | See the <<url-format,URL format>> section above for more information | |
127 | about the syntax of the following options' 'URL' argument. | |
128 | ||
129 | option:-C, option:--control-port='URL':: | |
130 | Listen to control data on URL 'URL' (default: `tcp://0.0.0.0:5342`). | |
131 | ||
132 | option:-D, option:--data-port='URL':: | |
133 | Listen to trace data on URL 'URL' (default: `tcp://0.0.0.0:5343`). | |
134 | ||
135 | option:-L, option:--live-port='URL':: | |
136 | Listen to LTTng live connections on URL 'URL' | |
137 | (default: `tcp://0.0.0.0:5344`). | |
138 | ||
139 | ||
140 | Program information | |
141 | ~~~~~~~~~~~~~~~~~~~ | |
142 | option:-h, option:--help:: | |
143 | Show help. | |
144 | ||
145 | option:-V, option:--version:: | |
146 | Show version. | |
147 | ||
148 | ||
149 | ENVIRONMENT VARIABLES | |
150 | --------------------- | |
151 | `LTTNG_NETWORK_SOCKET_TIMEOUT`:: | |
152 | Socket connection, receive and send timeout (milliseconds). A value | |
153 | of 0 or -1 uses the timeout of the operating system (default). | |
154 | ||
155 | `LTTNG_RELAYD_HEALTH`:: | |
156 | Path to relay daemon health's socket. | |
157 | ||
158 | ||
159 | EXIT STATUS | |
160 | ----------- | |
161 | *0*:: | |
162 | Success | |
163 | ||
164 | *1*:: | |
165 | Error | |
166 | ||
167 | *3*:: | |
168 | Fatal error | |
169 | ||
170 | ||
171 | LIMITATIONS | |
172 | ----------- | |
173 | As of this version, only the TCP protocol is supported for both control | |
174 | and data ports. In future versions, TCP will remain the sole available | |
175 | protocol for control data since those communications are low-volume and | |
176 | need absolute reliability; trace data could be carried over UDP. | |
177 | ||
178 | For an unprivileged user running `lttng-relayd`, the maximum number of | |
179 | file descriptors per process is usually 1024. This limits the number of | |
180 | connections and opened trace files. This limit can be configured with | |
181 | *ulimit*(3). | |
182 | ||
183 | ||
184 | include::common-footer.txt[] | |
185 | ||
186 | ||
187 | SEE ALSO | |
188 | -------- | |
189 | linklttng:lttng(1), | |
190 | linklttng:lttng-sessiond(8), | |
191 | linklttng:lttng-crash(1), | |
192 | linklttng:lttng-ust(3), | |
193 | linklttng:babeltrace(1) |