Commit | Line | Data |
---|---|---|
ee717bf0 PP |
1 | lttng-sessiond(8) |
2 | ================= | |
484b2a0c | 3 | :revdate: 21 April 2021 |
26f0c779 PP |
4 | :daemon-bin-name: lttng-sessiond |
5 | :daemon-ini-section: sessiond | |
ee717bf0 PP |
6 | |
7 | ||
8 | NAME | |
9 | ---- | |
484b2a0c | 10 | lttng-sessiond - LTTng session daemon |
ee717bf0 PP |
11 | |
12 | ||
13 | SYNOPSIS | |
14 | -------- | |
15 | [verse] | |
16 | *lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent] | |
17 | [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH'] | |
18 | [option:--agent-tcp-port='PORT'] | |
19 | [option:--apps-sock='PATH'] [option:--client-sock='PATH'] | |
20 | [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...] | |
21 | [option:--extra-kmod-probes='PROBE'[,'PROBE']...] | |
22 | [option:--kconsumerd-err-sock='PATH'] | |
23 | [option:--kconsumerd-cmd-sock='PATH']] | |
24 | [option:--ustconsumerd32-err-sock='PATH'] | |
25 | [option:--ustconsumerd64-err-sock='PATH'] | |
26 | [option:--ustconsumerd32-cmd-sock='PATH'] | |
27 | [option:--ustconsumerd64-cmd-sock='PATH'] | |
28 | [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH'] | |
29 | [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH'] | |
484b2a0c PP |
30 | [option:--event-notifier-error-buffer-size-kernel='SLOTS'] |
31 | [option:--event-notifier-error-buffer-size-userspace='SLOTS'] | |
32 | [option:--quiet | [option:--verbose]... [option:--verbose-consumer]] | |
ee717bf0 PP |
33 | |
34 | ||
35 | DESCRIPTION | |
36 | ----------- | |
484b2a0c | 37 | include::common-intro.txt[] |
ee717bf0 | 38 | |
484b2a0c | 39 | An LTTng session daemon, `lttng-sessiond`, is a program which: |
ee717bf0 | 40 | |
26f0c779 PP |
41 | * Manages tracing sessions (see man:lttng-concepts(7) to learn more |
42 | about tracing sessions). | |
ee717bf0 | 43 | |
484b2a0c PP |
44 | * Controls the various components (like tracers and consumer daemons) of |
45 | LTTng. | |
ee717bf0 | 46 | |
484b2a0c | 47 | * Sends asynchronous notifications to user applications. |
ee717bf0 | 48 | |
484b2a0c PP |
49 | A session daemon receives commands from the man:lttng(1) command-line |
50 | tool, as well as from any user application linked with the LTTng control | |
51 | library (`liblttng-ctl`). | |
ee717bf0 | 52 | |
484b2a0c PP |
53 | Each Unix user may have its own independent running session daemon. |
54 | However, the man:lttng(1) tool must connect to the session daemon of the | |
55 | `root` user (the root session daemon) to control Linux kernel tracing. | |
ee717bf0 | 56 | |
484b2a0c PP |
57 | When you start `lttng-sessiond` as the `root` Unix user, a non-root Unix |
58 | user can connect to it if it's part of the Unix tracing group. By | |
59 | default, the name of the tracing group is `tracing`. Override the | |
60 | tracing group name with the option:--group option. | |
ee717bf0 | 61 | |
484b2a0c PP |
62 | See the ``Session daemon connection'' section of man:lttng(1) to learn |
63 | how a user application connects to a session daemon. | |
41c9a411 | 64 | |
484b2a0c PP |
65 | A session daemon manages trace data consumer daemons, spawning them when |
66 | necessary. You do :not: need to manage the consumer daemons yourself. | |
41c9a411 | 67 | |
484b2a0c PP |
68 | By default, `lttng-sessiond` doesn't start as a daemon. Make it a daemon |
69 | with the option:--daemonize or option:--background option. With those | |
70 | options, `lttng-sessiond` ensures the daemon is ready to receive client | |
71 | commands before it exits. | |
41c9a411 | 72 | |
484b2a0c PP |
73 | NOTE: The LTTng project recommends that you start the session daemon at |
74 | boot time for stable and long-term tracing. | |
ee717bf0 | 75 | |
26f0c779 PP |
76 | [NOTE] |
77 | ==== | |
78 | For an unprivileged Unix user running `lttng-sessiond`, the maximum | |
79 | number of file descriptors per process is usually 1024. This limits the | |
80 | number of traceable applications, since, for each instrumented | |
81 | application, there are two file descriptors per CPU as well as one | |
82 | socket for bidirectional communication. | |
41c9a411 | 83 | |
26f0c779 PP |
84 | For the `root` user, the limit is usually 65,535. |
85 | ==== | |
484b2a0c | 86 | |
484b2a0c | 87 | |
26f0c779 | 88 | include::common-daemon-cfg.txt[] |
484b2a0c PP |
89 | |
90 | INI configuration file example: | |
91 | ||
92 | [source,ini] | |
93 | ---- | |
94 | [sessiond] | |
95 | daemonize=yes | |
96 | extra-kmod-probes=my-driver,other-module | |
97 | ---- | |
98 | ||
99 | ||
100 | [[load]] | |
101 | Tracing session configuration loading | |
102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
103 | When the session daemon starts, it loads tracing session configurations | |
104 | from: | |
ee717bf0 | 105 | |
484b2a0c PP |
106 | Without the option:--load option:: |
107 | In this order: | |
108 | + | |
109 | -- | |
110 | . All the files in `$LTTNG_HOME/.lttng/sessions/auto`. | |
111 | + | |
112 | `$LTTNG_HOME` defaults to `$HOME`. | |
113 | ||
114 | . All the files in +{system_sessions_auto_dir}+. | |
115 | -- | |
116 | + | |
117 | `lttng-sessiond` only loads tracing configuration files from the | |
118 | directories above if its UID and their UID are the same. | |
ee717bf0 | 119 | |
484b2a0c PP |
120 | With the option:--load='PATH' option:: |
121 | 'PATH' is a directory::: | |
122 | All the files in 'PATH'. | |
123 | ||
124 | 'PATH' is a file::: | |
125 | The file 'PATH'. | |
126 | ||
127 | ||
128 | [[options]] | |
ee717bf0 PP |
129 | OPTIONS |
130 | ------- | |
26f0c779 PP |
131 | General daemon configuration |
132 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
ee717bf0 | 133 | option:-b, option:--background:: |
484b2a0c PP |
134 | Start as a Unix daemon, but keep file descriptors (console) open. |
135 | + | |
136 | With this option, `lttng-sessiond` ensures the daemon is ready to | |
137 | receive client commands before it exits. | |
138 | + | |
139 | Use the option:--daemonize option instead to close the file descriptors. | |
ee717bf0 | 140 | |
63e7895a | 141 | option:-f 'PATH', option:--config='PATH':: |
484b2a0c PP |
142 | Configure the daemon using the INI configuration file 'PATH' in |
143 | addition to the default configuration files and the command-line | |
144 | options. | |
145 | + | |
146 | See the <<cfg,Daemon configuration>> section above. | |
6a0e3480 | 147 | |
ee717bf0 | 148 | option:-d, option:--daemonize:: |
484b2a0c PP |
149 | Start as a Unix daemon and close file descriptors (console). |
150 | + | |
151 | With this option, `lttng-sessiond` ensures the daemon is ready to | |
152 | receive client commands before it exits. | |
153 | + | |
154 | Use the option:--background option instead to keep the file descriptors | |
155 | open. | |
ee717bf0 | 156 | |
63e7895a | 157 | option:-g 'GROUP', option:--group='GROUP':: |
484b2a0c PP |
158 | Set the Unix tracing group to 'GROUP' instead of `tracing`. |
159 | + | |
160 | This option is only meaningful when the `root` Unix user starts | |
161 | `lttng-sessiond`. | |
162 | + | |
163 | Members of the Unix tracing group may connect to the root session daemon | |
164 | and, therefore, control LTTng kernel tracing. | |
ee717bf0 | 165 | |
63e7895a | 166 | option:-l 'PATH', option:--load='PATH':: |
484b2a0c PP |
167 | Load tracing session configurations from 'PATH', either a directory |
168 | or a file, instead of loading them from the default search | |
169 | directories. | |
170 | + | |
171 | See the <<load,Tracing session configuration loading>> section above. | |
ee717bf0 PP |
172 | |
173 | option:-S, option:--sig-parent:: | |
484b2a0c | 174 | Send the `USR1` signal to the parent process to notify readiness. |
ee717bf0 | 175 | + |
484b2a0c PP |
176 | You can also use the option:--daemonize or option:--background option, |
177 | in which case `lttng-sessiond` ensures the daemon is ready to receive | |
178 | client commands before it exits. | |
761ffce2 | 179 | |
ee717bf0 PP |
180 | |
181 | Linux kernel tracing | |
182 | ~~~~~~~~~~~~~~~~~~~~ | |
484b2a0c PP |
183 | At most one of: |
184 | ||
ee717bf0 | 185 | option:--extra-kmod-probes='PROBE'[,'PROBE']...:: |
484b2a0c PP |
186 | For each 'PROBE' argument, load the LTTng kernel probe module |
187 | named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the | |
188 | default LTTng kernel probe modules. | |
26f0c779 PP |
189 | + |
190 | See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable. | |
ee717bf0 PP |
191 | |
192 | option:--kmod-probes='PROBE'[,'PROBE']...:: | |
484b2a0c PP |
193 | Only load, for each 'PROBE' argument, the LTTng kernel probe |
194 | module named ++lttng-probe-++__PROBE__++.ko++, instead of loading | |
195 | the default LTTng kernel probe modules. | |
26f0c779 PP |
196 | + |
197 | See also the `LTTNG_KMOD_PROBES` environment variable. | |
ee717bf0 PP |
198 | |
199 | option:--no-kernel:: | |
200 | Disable Linux kernel tracing. | |
201 | ||
202 | ||
203 | Paths and ports | |
204 | ~~~~~~~~~~~~~~~ | |
205 | option:--agent-tcp-port='PORT':: | |
484b2a0c PP |
206 | Listen on TCP port 'PORT' for agent application registration |
207 | instead of a port within the range | |
2288467f | 208 | [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]). |
ee717bf0 | 209 | |
59b19c3c | 210 | option:-a 'PATH', option:--apps-sock='PATH':: |
484b2a0c | 211 | Set the application Unix socket path to 'PATH'. |
ee717bf0 | 212 | |
59b19c3c | 213 | option:-c 'PATH', option:--client-sock='PATH':: |
484b2a0c | 214 | Set the client Unix socket path to 'PATH'. |
ee717bf0 PP |
215 | |
216 | option:--consumerd32-libdir='PATH':: | |
484b2a0c | 217 | Set the 32-bit consumer daemon library directory to 'PATH'. |
26f0c779 PP |
218 | + |
219 | See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable. | |
ee717bf0 PP |
220 | |
221 | option:--consumerd32-path='PATH':: | |
484b2a0c | 222 | Set the 32-bit consumer daemon binary path to 'PATH'. |
26f0c779 PP |
223 | + |
224 | See also the `LTTNG_CONSUMERD32_BIN` environment variable. | |
ee717bf0 PP |
225 | |
226 | option:--consumerd64-libdir='PATH':: | |
484b2a0c | 227 | Set the 64-bit consumer daemon library directory to 'PATH'. |
26f0c779 PP |
228 | + |
229 | See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable. | |
ee717bf0 PP |
230 | |
231 | option:--consumerd64-path='PATH':: | |
484b2a0c | 232 | Set the 64-bit consumer daemon binary path to 'PATH'. |
26f0c779 PP |
233 | + |
234 | See also the `LTTNG_CONSUMERD32_BIN` environment variable. | |
ee717bf0 PP |
235 | |
236 | option:--kconsumerd-cmd-sock='PATH':: | |
484b2a0c | 237 | Set the command Unix socket path of the Linux kernel consumer daemon |
ee717bf0 PP |
238 | to 'PATH'. |
239 | ||
240 | option:--kconsumerd-err-sock='PATH':: | |
484b2a0c | 241 | Set the error Unix socket path of the Linux kernel consumer daemon |
ee717bf0 PP |
242 | to 'PATH'. |
243 | ||
244 | option:--ustconsumerd32-cmd-sock='PATH':: | |
484b2a0c PP |
245 | Set the Unix socket path of the 32-bit consumer daemon command to |
246 | 'PATH'. | |
ee717bf0 PP |
247 | |
248 | option:--ustconsumerd64-cmd-sock='PATH':: | |
484b2a0c PP |
249 | Set the Unix socket path of the 64-bit consumer daemon command to |
250 | 'PATH'. | |
ee717bf0 PP |
251 | |
252 | option:--ustconsumerd32-err-sock='PATH':: | |
484b2a0c PP |
253 | Set the Unix socket path of the 32-bit consumer daemon error to |
254 | 'PATH'. | |
ee717bf0 PP |
255 | |
256 | option:--ustconsumerd64-err-sock='PATH':: | |
484b2a0c PP |
257 | Set the Unix socket path of the 64-bit consumer daemon error to |
258 | 'PATH'. | |
259 | ||
260 | ||
261 | Buffer size of event notifier error counters | |
262 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
263 | option:--event-notifier-error-buffer-size-kernel='SLOTS':: | |
264 | Set the size of the kernel event notifier error counter buffers to | |
265 | 'SLOTS'{nbsp}slots. | |
266 | ||
267 | option:--event-notifier-error-buffer-size-userspace='SLOTS':: | |
268 | Set the size of the user space event notifier error counter buffers | |
269 | to 'SLOTS'{nbsp}slots. | |
270 | ||
271 | As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this | |
272 | may change in the future. | |
ee717bf0 PP |
273 | |
274 | ||
275 | Verbosity | |
276 | ~~~~~~~~~ | |
277 | option:-q, option:--quiet:: | |
278 | Suppress all messages, including warnings and errors. | |
484b2a0c PP |
279 | + |
280 | You may :not: use this option with the option:--verbose and | |
281 | option:--verbose-consumer options. | |
ee717bf0 PP |
282 | |
283 | option:-v, option:--verbose:: | |
284 | Increase verbosity. | |
285 | + | |
484b2a0c PP |
286 | Specify this option up to three times to get more levels of verbosity. |
287 | + | |
288 | You may :not: use this option with the option:--quiet option. | |
ee717bf0 PP |
289 | |
290 | option:--verbose-consumer:: | |
484b2a0c PP |
291 | Increase the verbosity of the consumer daemons which this session |
292 | daemon spawns. | |
293 | + | |
294 | You may :not: use this option with the option:--quiet option. | |
ee717bf0 PP |
295 | |
296 | ||
297 | Program information | |
298 | ~~~~~~~~~~~~~~~~~~~ | |
484b2a0c | 299 | include::common-help-option.txt[] |
ee717bf0 PP |
300 | |
301 | option:-V, option:--version:: | |
484b2a0c | 302 | Show version and quit. |
ee717bf0 PP |
303 | |
304 | ||
af1c4164 PP |
305 | EXIT STATUS |
306 | ----------- | |
307 | *0*:: | |
308 | Success | |
309 | ||
310 | *1*:: | |
311 | Error | |
312 | ||
313 | *3*:: | |
314 | Fatal error | |
315 | ||
316 | ||
317 | ENVIRONMENT | |
318 | ----------- | |
9bbd8e06 | 319 | `LTTNG_ABORT_ON_ERROR`:: |
484b2a0c PP |
320 | Set to `1` to abort the process after the first error is |
321 | encountered. | |
9bbd8e06 | 322 | |
ee717bf0 | 323 | `LTTNG_APP_SOCKET_TIMEOUT`:: |
484b2a0c PP |
324 | Timeout (in seconds) of the application socket when |
325 | sending/receiving commands. | |
326 | + | |
327 | After this period of time, `lttng-sessiond` unregisters the application. | |
328 | + | |
329 | Set to `0` or `-1` to set an infinite timeout. | |
330 | + | |
331 | Default: +{default_app_socket_rw_timeout}+. | |
ee717bf0 PP |
332 | |
333 | `LTTNG_CONSUMERD32_BIN`:: | |
334 | 32-bit consumer daemon binary path. | |
335 | + | |
26f0c779 PP |
336 | The option:--consumerd32-path option overrides this environment |
337 | variable. | |
ee717bf0 PP |
338 | |
339 | `LTTNG_CONSUMERD32_LIBDIR`:: | |
484b2a0c | 340 | 32-bit consumer daemon library directory path. |
ee717bf0 | 341 | + |
26f0c779 PP |
342 | The option:--consumerd32-libdir option overrides this environment |
343 | variable. | |
ee717bf0 PP |
344 | |
345 | `LTTNG_CONSUMERD64_BIN`:: | |
346 | 64-bit consumer daemon binary path. | |
347 | + | |
26f0c779 PP |
348 | The option:--consumerd64-path option overrides this environment |
349 | variable. | |
ee717bf0 PP |
350 | |
351 | `LTTNG_CONSUMERD64_LIBDIR`:: | |
484b2a0c | 352 | 64-bit consumer daemon library directory path. |
ee717bf0 | 353 | + |
26f0c779 PP |
354 | The option:--consumerd64-libdir option overrides this environment |
355 | variable. | |
ee717bf0 PP |
356 | |
357 | `LTTNG_DEBUG_NOCLONE`:: | |
484b2a0c PP |
358 | Set to `1` to disable the use of man:clone(2)/man:fork(2). |
359 | + | |
26f0c779 PP |
360 | Setting this environment variable is considered insecure, but it's |
361 | required to allow debuggers to work with `lttng-sessiond` on some | |
362 | operating systems. | |
ee717bf0 PP |
363 | |
364 | `LTTNG_EXTRA_KMOD_PROBES`:: | |
484b2a0c | 365 | Extra LTTng kernel probe modules to load. |
ee717bf0 | 366 | + |
484b2a0c PP |
367 | See the option:--extra-kmod-probes option which overrides this |
368 | environment variable. | |
ee717bf0 PP |
369 | |
370 | `LTTNG_KMOD_PROBES`:: | |
484b2a0c | 371 | Exclusive LTTng kernel probe modules to load. |
ee717bf0 | 372 | + |
484b2a0c PP |
373 | See the option:--kmod-probes option which overrides this environment |
374 | variable. | |
ee717bf0 PP |
375 | |
376 | `LTTNG_NETWORK_SOCKET_TIMEOUT`:: | |
484b2a0c PP |
377 | Socket connection, receive, and send timeout (milliseconds). |
378 | + | |
379 | Set to `0` or `-1` to use the timeout of the operating system (default). | |
ee717bf0 PP |
380 | |
381 | `LTTNG_SESSION_CONFIG_XSD_PATH`:: | |
382 | Tracing session configuration XML schema definition (XSD) path. | |
383 | ||
384 | ||
900690ca PP |
385 | FILES |
386 | ----- | |
387 | `$LTTNG_HOME/.lttng`:: | |
484b2a0c | 388 | Unix user's LTTng runtime and configuration directory. |
900690ca PP |
389 | |
390 | `$LTTNG_HOME/lttng-traces`:: | |
484b2a0c PP |
391 | Default output directory of LTTng traces in local and snapshot |
392 | modes. | |
393 | + | |
394 | Override this path with the nloption:--output option of the | |
395 | man:lttng-create(1) command. | |
900690ca | 396 | |
41c9a411 | 397 | `$LTTNG_HOME/.lttng/sessions/auto`:: |
484b2a0c PP |
398 | Directory from which `lttng-sessiond` loads Unix user tracing |
399 | session configurations when starting. | |
400 | + | |
401 | See the <<load,Tracing session configuration loading>> section above to | |
402 | learn more. | |
41c9a411 PP |
403 | |
404 | +{system_sessions_auto_dir}+:: | |
484b2a0c PP |
405 | Directory from which `lttng-sessiond` loads system-wide tracing |
406 | session configurations when starting. | |
407 | + | |
408 | See the <<load,Tracing session configuration loading>> section above to | |
409 | learn more. | |
900690ca PP |
410 | |
411 | `$LTTNG_HOME/.lttng/lttng.conf`:: | |
484b2a0c PP |
412 | Unix user's LTTng daemon INI configuration file. |
413 | + | |
414 | See the <<cfg,Daemon configuration>> section above to learn more. | |
900690ca | 415 | |
d8065e7e | 416 | +{system_lttng_conf}+:: |
484b2a0c PP |
417 | System-wide LTTng daemon INI configuration file. |
418 | + | |
419 | See the <<cfg,Daemon configuration>> section above to learn more. | |
900690ca | 420 | |
484b2a0c | 421 | NOTE: `$LTTNG_HOME` defaults to `$HOME`. |
900690ca PP |
422 | |
423 | ||
ee717bf0 PP |
424 | include::common-footer.txt[] |
425 | ||
426 | ||
427 | SEE ALSO | |
428 | -------- | |
26f0c779 PP |
429 | man:lttng(1), |
430 | man:lttng-concepts(7) |