Commit | Line | Data |
---|---|---|
ee717bf0 PP |
1 | lttng-sessiond(8) |
2 | ================= | |
4605890e | 3 | :revdate: 17 September 2018 |
ee717bf0 PP |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
8 | lttng-sessiond - LTTng 2 tracing session daemon | |
9 | ||
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
13 | [verse] | |
14 | *lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent] | |
15 | [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH'] | |
16 | [option:--agent-tcp-port='PORT'] | |
17 | [option:--apps-sock='PATH'] [option:--client-sock='PATH'] | |
18 | [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...] | |
19 | [option:--extra-kmod-probes='PROBE'[,'PROBE']...] | |
20 | [option:--kconsumerd-err-sock='PATH'] | |
21 | [option:--kconsumerd-cmd-sock='PATH']] | |
22 | [option:--ustconsumerd32-err-sock='PATH'] | |
23 | [option:--ustconsumerd64-err-sock='PATH'] | |
24 | [option:--ustconsumerd32-cmd-sock='PATH'] | |
25 | [option:--ustconsumerd64-cmd-sock='PATH'] | |
26 | [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH'] | |
27 | [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH'] | |
28 | [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]] | |
29 | ||
30 | ||
31 | DESCRIPTION | |
32 | ----------- | |
a18d9544 | 33 | The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open |
ee717bf0 PP |
34 | source software package used for correlated tracing of the Linux kernel, |
35 | user applications, and user libraries. | |
36 | ||
37 | LTTng consists of Linux kernel modules (for Linux kernel tracing) and | |
38 | dynamically loaded libraries (for user application and library tracing). | |
39 | ||
40 | The _LTTng session daemon_ is a tracing registry which allows the user | |
41 | to interact with multiple tracers (kernel and user space) within the | |
42 | same container, a _tracing session_. Traces can be gathered from the | |
43 | Linux kernel and/or from instrumented applications (see | |
7c1a4458 PP |
44 | man:lttng-ust(3)). You can aggregate and read the events of LTTng |
45 | traces using man:babeltrace(1). | |
ee717bf0 PP |
46 | |
47 | To trace the Linux kernel, the session daemon needs to be running as | |
48 | `root`. LTTng uses a _tracing group_ to allow specific users to interact | |
49 | with the root session daemon. The default tracing group name is | |
50 | `tracing`. You can use the option:--group option to set the tracing | |
51 | group name to use. | |
52 | ||
53 | Session daemons can coexist. You can have a session daemon running as | |
54 | user Alice that can be used to trace her applications alongside a root | |
55 | session daemon or a session daemon running as user Bob. | |
56 | ||
57 | The LTTng session daemon manages trace data consumer daemons by spawning | |
58 | them when necessary. You do not need to manage the consumer daemons | |
59 | manually. | |
60 | ||
61 | NOTE: It is highly recommended to start the session daemon at boot time | |
62 | for stable and long-term tracing. | |
63 | ||
64 | ||
41c9a411 PP |
65 | Automatic loading of tracing session configurations |
66 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
67 | When the session daemon starts, it automatically loads session | |
68 | configuration files. | |
69 | ||
70 | The following directories are searched, non-recursively, in this order | |
71 | for configuration files to load on launch: | |
72 | ||
73 | . `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`) | |
74 | . +{system_sessions_auto_dir}+ | |
75 | ||
ee717bf0 | 76 | Note that both the directory containing the tracing session |
41c9a411 | 77 | configurations _and_ the session daemon binary _must_ share the same UID |
ee717bf0 PP |
78 | for the configurations to be automatically loaded. |
79 | ||
41c9a411 PP |
80 | The option:--load option overrides the default directories _and_ the UID |
81 | check. The session daemon simply checks if the path is accessible and | |
82 | tries to load every tracing session configuration in it. When this | |
83 | option is specified, the default directories are :not: searched for | |
84 | configuration files. When the option is not specified, _both_ default | |
85 | directories are searched for configuration files. | |
86 | ||
87 | If the option:--load option's argument is a directory, then all the | |
88 | tracing session configurations found in all the files in this directory | |
89 | are loaded. If the argument is a file, then all the tracing session | |
90 | configurations found in this file are loaded. | |
ee717bf0 PP |
91 | |
92 | ||
93 | OPTIONS | |
94 | ------- | |
95 | Daemon configuration | |
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:-f, option:--config='PATH':: | |
108 | Load session daemon configuration from path 'PATH'. | |
109 | ||
110 | option:-g, option:--group='GROUP':: | |
111 | Use 'GROUP' as Unix tracing group (default: `tracing`). | |
112 | ||
113 | option:-l, option:--load='PATH':: | |
41c9a411 PP |
114 | Automatically load tracing session configurations from 'PATH', |
115 | either a directory or a file, instead of loading them from the | |
116 | default search directories. | |
ee717bf0 PP |
117 | |
118 | option:-S, option:--sig-parent:: | |
119 | Send `SIGUSR1` to parent process to notify readiness. | |
120 | + | |
7c1a4458 | 121 | NOTE: This is used by man:lttng(1) to get notified when the |
ee717bf0 PP |
122 | session daemon is ready to accept commands. When building a third party |
123 | tool on liblttng-ctl, this option can be very handy to synchronize the | |
124 | control tool and the session daemon. | |
125 | ||
126 | ||
127 | Linux kernel tracing | |
128 | ~~~~~~~~~~~~~~~~~~~~ | |
129 | option:--extra-kmod-probes='PROBE'[,'PROBE']...:: | |
130 | Load specific LTTng Linux kernel modules when kernel tracing | |
131 | is enabled (option:--no-kernel option is :not: specified), in | |
132 | addition to loading the default list of LTTng kernel modules. | |
133 | + | |
134 | Only the name of the probe needs to be specified, without the | |
135 | `lttng-probe-` prefix and without the kernel module extension suffix. | |
136 | For example, specify `sched` to load the `lttng-probe-sched.ko` kernel | |
137 | module. | |
138 | ||
139 | option:--kmod-probes='PROBE'[,'PROBE']...:: | |
140 | Only load specific LTTng Linux kernel modules when kernel tracing | |
141 | is enabled (option:--no-kernel option is :not: specified). | |
142 | + | |
143 | Only the name of the probe needs to be specified, without the | |
144 | `lttng-probe-` prefix and without the kernel module extension suffix. | |
145 | For example, specify `sched` to load the `lttng-probe-sched.ko` kernel | |
146 | module. | |
147 | ||
148 | option:--no-kernel:: | |
149 | Disable Linux kernel tracing. | |
150 | ||
151 | ||
152 | Paths and ports | |
153 | ~~~~~~~~~~~~~~~ | |
154 | option:--agent-tcp-port='PORT':: | |
155 | Listen on TCP port 'PORT' for agent application registrations | |
cb7d437c | 156 | (default: a port within the range |
2288467f | 157 | [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]). |
ee717bf0 | 158 | |
59b19c3c | 159 | option:-a 'PATH', option:--apps-sock='PATH':: |
ee717bf0 PP |
160 | Set application Unix socket path to 'PATH'. |
161 | ||
59b19c3c | 162 | option:-c 'PATH', option:--client-sock='PATH':: |
ee717bf0 PP |
163 | Set client Unix socket path to 'PATH'. |
164 | ||
165 | option:--consumerd32-libdir='PATH':: | |
166 | Set 32-bit consumer daemon library directory to 'PATH'. | |
167 | ||
168 | option:--consumerd32-path='PATH':: | |
169 | Set 32-bit consumer daemon binary path to 'PATH'. | |
170 | ||
171 | option:--consumerd64-libdir='PATH':: | |
172 | Set 64-bit consumer daemon library directory to 'PATH'. | |
173 | ||
174 | option:--consumerd64-path='PATH':: | |
175 | Set 64-bit consumer daemon binary path to 'PATH'. | |
176 | ||
177 | option:--kconsumerd-cmd-sock='PATH':: | |
178 | Set Linux kernel consumer daemon's command Unix socket path | |
179 | to 'PATH'. | |
180 | ||
181 | option:--kconsumerd-err-sock='PATH':: | |
182 | Set Linux kernel consumer daemon's error Unix socket path | |
183 | to 'PATH'. | |
184 | ||
185 | option:--ustconsumerd32-cmd-sock='PATH':: | |
186 | Set 32-bit consumer daemon's command Unix socket path to 'PATH'. | |
187 | ||
188 | option:--ustconsumerd64-cmd-sock='PATH':: | |
189 | Set 64-bit consumer daemon's command Unix socket path to 'PATH'. | |
190 | ||
191 | option:--ustconsumerd32-err-sock='PATH':: | |
192 | Set 32-bit consumer daemon's error Unix socket path to 'PATH'. | |
193 | ||
194 | option:--ustconsumerd64-err-sock='PATH':: | |
195 | Set 64-bit consumer daemon's error Unix socket path to 'PATH'. | |
196 | ||
197 | ||
198 | Verbosity | |
199 | ~~~~~~~~~ | |
200 | option:-q, option:--quiet:: | |
201 | Suppress all messages, including warnings and errors. | |
202 | ||
203 | option:-v, option:--verbose:: | |
204 | Increase verbosity. | |
205 | + | |
206 | Three levels of verbosity are available, which are triggered by | |
207 | appending additional `v` letters to the option | |
208 | (that is, `-vv` and `-vvv`). | |
209 | ||
210 | option:--verbose-consumer:: | |
211 | Increase verbosity of consumer daemons spawned by this session | |
212 | daemon. | |
213 | ||
214 | ||
215 | Program information | |
216 | ~~~~~~~~~~~~~~~~~~~ | |
217 | option:-h, option:--help:: | |
218 | Show help. | |
219 | ||
220 | option:-V, option:--version:: | |
221 | Show version. | |
222 | ||
223 | ||
224 | ENVIRONMENT VARIABLES | |
225 | --------------------- | |
226 | Note that command-line options override their equivalent environment | |
227 | variable. | |
228 | ||
9bbd8e06 MD |
229 | `LTTNG_ABORT_ON_ERROR`:: |
230 | Set to 1 to abort the process after the first error is encountered. | |
231 | ||
ee717bf0 PP |
232 | `LTTNG_APP_SOCKET_TIMEOUT`:: |
233 | Application socket's timeout (seconds) when sending/receiving | |
234 | commands. After this period of time, the application is unregistered | |
235 | by the session daemon. A value of 0 or -1 means an infinite timeout. | |
c93eadad | 236 | Default value: {default_app_socket_rw_timeout}. |
ee717bf0 PP |
237 | |
238 | `LTTNG_CONSUMERD32_BIN`:: | |
239 | 32-bit consumer daemon binary path. | |
240 | + | |
241 | The option:--consumerd32-path option overrides this variable. | |
242 | ||
243 | `LTTNG_CONSUMERD32_LIBDIR`:: | |
244 | 32-bit consumer daemon library path. | |
245 | + | |
246 | The option:--consumerd32-libdir option overrides this variable. | |
247 | ||
248 | `LTTNG_CONSUMERD64_BIN`:: | |
249 | 64-bit consumer daemon binary path. | |
250 | + | |
251 | The option:--consumerd64-path option overrides this variable. | |
252 | ||
253 | `LTTNG_CONSUMERD64_LIBDIR`:: | |
254 | 64-bit consumer daemon library path. | |
255 | + | |
256 | The option:--consumerd64-libdir option overrides this variable. | |
257 | ||
258 | `LTTNG_DEBUG_NOCLONE`:: | |
259 | Set to 1 to disable the use of `clone()`/`fork()`. Setting this | |
260 | variable is considered insecure, but it is required to allow | |
261 | debuggers to work with the session daemon on some operating systems. | |
262 | ||
263 | `LTTNG_EXTRA_KMOD_PROBES`:: | |
264 | Load specific LTTng Linux kernel modules when kernel tracing | |
265 | is enabled (option:--no-kernel option is :not: specified), in | |
266 | addition to loading the default list of LTTng kernel modules. | |
267 | + | |
268 | The option:--extra-kmod-probes option overrides this variable. | |
269 | ||
270 | `LTTNG_KMOD_PROBES`:: | |
271 | Only load specific LTTng Linux kernel modules when kernel tracing | |
272 | is enabled (option:--no-kernel option is :not: specified). | |
273 | + | |
274 | The option:--kmod-probes option overrides this variable. | |
275 | ||
276 | `LTTNG_NETWORK_SOCKET_TIMEOUT`:: | |
277 | Socket connection, receive and send timeout (milliseconds). A value | |
278 | of 0 or -1 uses the timeout of the operating system (default). | |
279 | ||
280 | `LTTNG_SESSION_CONFIG_XSD_PATH`:: | |
281 | Tracing session configuration XML schema definition (XSD) path. | |
282 | ||
283 | ||
900690ca PP |
284 | FILES |
285 | ----- | |
286 | `$LTTNG_HOME/.lttng`:: | |
287 | User LTTng runtime and configuration directory. | |
288 | ||
289 | `$LTTNG_HOME/lttng-traces`:: | |
290 | Default output directory of LTTng traces. This can be overridden | |
7c1a4458 | 291 | with the nloption:--output option of the man:lttng-create(1) |
900690ca PP |
292 | command. |
293 | ||
41c9a411 PP |
294 | `$LTTNG_HOME/.lttng/sessions/auto`:: |
295 | Directory from which user tracing configuration files are | |
296 | automatically loaded when the session daemon starts (see | |
297 | man:lttng-save(1) and man:lttng-load(1) for saving | |
298 | and loading tracing sessions). | |
299 | ||
300 | +{system_sessions_auto_dir}+:: | |
301 | Directory from which system-wide tracing configuration files are | |
302 | automatically loaded when the session daemon starts (see | |
303 | man:lttng-save(1) and man:lttng-load(1) for saving | |
304 | and loading tracing sessions). | |
900690ca PP |
305 | |
306 | `$LTTNG_HOME/.lttng/lttng.conf`:: | |
307 | Default location of the session daemon configuration file (see the | |
308 | option:--config option). | |
309 | ||
d8065e7e | 310 | +{system_lttng_conf}+:: |
900690ca PP |
311 | System-wide location of the session daemon configuration file (see |
312 | the option:--config option). | |
313 | ||
314 | NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. | |
315 | ||
316 | ||
ee717bf0 PP |
317 | EXIT STATUS |
318 | ----------- | |
319 | *0*:: | |
320 | Success | |
321 | ||
322 | *1*:: | |
323 | Error | |
324 | ||
325 | *3*:: | |
326 | Fatal error | |
327 | ||
328 | ||
329 | LIMITATIONS | |
330 | ----------- | |
331 | For an unprivileged user running `lttng-sessiond`, the maximum number of | |
332 | file descriptors per process is usually 1024. This limits the number of | |
333 | traceable applications, since for each instrumented application, there | |
334 | is two file descriptors per CPU and one more socket for bidirectional | |
335 | communication. | |
336 | ||
337 | For the root user, the limit is bumped to 65535. A future version will | |
338 | deal with this limitation. | |
339 | ||
340 | ||
341 | include::common-footer.txt[] | |
342 | ||
343 | ||
344 | SEE ALSO | |
345 | -------- | |
7c1a4458 PP |
346 | man:lttng(1), |
347 | man:lttng-relayd(8), | |
348 | man:lttng-crash(1), | |
349 | man:lttng-ust(3), | |
350 | man:babeltrace(1) |