Commit | Line | Data |
---|---|---|
ee717bf0 PP |
1 | lttng-sessiond(8) |
2 | ================= | |
aaae4813 | 3 | :revdate: 14 June 2021 |
188419c4 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 | |
aaae4813 PP |
41 | * Manages recording sessions (see man:lttng-concepts(7) to learn more |
42 | about recording 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 | |
188419c4 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 | |
188419c4 PP |
84 | For the `root` user, the limit is usually 65,535. |
85 | ==== | |
484b2a0c | 86 | |
484b2a0c | 87 | |
188419c4 | 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]] | |
aaae4813 PP |
101 | Recording session configuration loading |
102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
103 | When the session daemon starts, it loads recording session | |
104 | configurations 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 | + | |
aaae4813 PP |
117 | `lttng-sessiond` only loads recording session configuration files from |
118 | the 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 | ------- | |
188419c4 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 | + | |
7d259724 | 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':: |
aaae4813 PP |
167 | Load recording session configurations from 'PATH', either a |
168 | directory or a file, instead of loading them from the default search | |
484b2a0c PP |
169 | directories. |
170 | + | |
aaae4813 | 171 | See the ``<<load,Recording session configuration loading>>'' section |
7d259724 | 172 | above. |
ee717bf0 PP |
173 | |
174 | option:-S, option:--sig-parent:: | |
484b2a0c | 175 | Send the `USR1` signal to the parent process to notify readiness. |
ee717bf0 | 176 | + |
484b2a0c PP |
177 | You can also use the option:--daemonize or option:--background option, |
178 | in which case `lttng-sessiond` ensures the daemon is ready to receive | |
179 | client commands before it exits. | |
761ffce2 | 180 | |
ee717bf0 PP |
181 | |
182 | Linux kernel tracing | |
183 | ~~~~~~~~~~~~~~~~~~~~ | |
484b2a0c PP |
184 | At most one of: |
185 | ||
ee717bf0 | 186 | option:--extra-kmod-probes='PROBE'[,'PROBE']...:: |
484b2a0c PP |
187 | For each 'PROBE' argument, load the LTTng kernel probe module |
188 | named ++lttng-probe-++__PROBE__++.ko++, in addition to loading the | |
189 | default LTTng kernel probe modules. | |
188419c4 PP |
190 | + |
191 | See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable. | |
ee717bf0 PP |
192 | |
193 | option:--kmod-probes='PROBE'[,'PROBE']...:: | |
484b2a0c PP |
194 | Only load, for each 'PROBE' argument, the LTTng kernel probe |
195 | module named ++lttng-probe-++__PROBE__++.ko++, instead of loading | |
196 | the default LTTng kernel probe modules. | |
188419c4 PP |
197 | + |
198 | See also the `LTTNG_KMOD_PROBES` environment variable. | |
ee717bf0 PP |
199 | |
200 | option:--no-kernel:: | |
201 | Disable Linux kernel tracing. | |
202 | ||
203 | ||
204 | Paths and ports | |
205 | ~~~~~~~~~~~~~~~ | |
206 | option:--agent-tcp-port='PORT':: | |
484b2a0c PP |
207 | Listen on TCP port 'PORT' for agent application registration |
208 | instead of a port within the range | |
2288467f | 209 | [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]). |
ee717bf0 | 210 | |
59b19c3c | 211 | option:-a 'PATH', option:--apps-sock='PATH':: |
484b2a0c | 212 | Set the application Unix socket path to 'PATH'. |
ee717bf0 | 213 | |
59b19c3c | 214 | option:-c 'PATH', option:--client-sock='PATH':: |
484b2a0c | 215 | Set the client Unix socket path to 'PATH'. |
ee717bf0 PP |
216 | |
217 | option:--consumerd32-libdir='PATH':: | |
484b2a0c | 218 | Set the 32-bit consumer daemon library directory to 'PATH'. |
188419c4 PP |
219 | + |
220 | See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable. | |
ee717bf0 PP |
221 | |
222 | option:--consumerd32-path='PATH':: | |
484b2a0c | 223 | Set the 32-bit consumer daemon binary path to 'PATH'. |
188419c4 PP |
224 | + |
225 | See also the `LTTNG_CONSUMERD32_BIN` environment variable. | |
ee717bf0 PP |
226 | |
227 | option:--consumerd64-libdir='PATH':: | |
484b2a0c | 228 | Set the 64-bit consumer daemon library directory to 'PATH'. |
188419c4 PP |
229 | + |
230 | See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable. | |
ee717bf0 PP |
231 | |
232 | option:--consumerd64-path='PATH':: | |
484b2a0c | 233 | Set the 64-bit consumer daemon binary path to 'PATH'. |
188419c4 PP |
234 | + |
235 | See also the `LTTNG_CONSUMERD32_BIN` environment variable. | |
ee717bf0 PP |
236 | |
237 | option:--kconsumerd-cmd-sock='PATH':: | |
484b2a0c | 238 | Set the command Unix socket path of the Linux kernel consumer daemon |
ee717bf0 PP |
239 | to 'PATH'. |
240 | ||
241 | option:--kconsumerd-err-sock='PATH':: | |
484b2a0c | 242 | Set the error Unix socket path of the Linux kernel consumer daemon |
ee717bf0 PP |
243 | to 'PATH'. |
244 | ||
245 | option:--ustconsumerd32-cmd-sock='PATH':: | |
484b2a0c PP |
246 | Set the Unix socket path of the 32-bit consumer daemon command to |
247 | 'PATH'. | |
ee717bf0 PP |
248 | |
249 | option:--ustconsumerd64-cmd-sock='PATH':: | |
484b2a0c PP |
250 | Set the Unix socket path of the 64-bit consumer daemon command to |
251 | 'PATH'. | |
ee717bf0 PP |
252 | |
253 | option:--ustconsumerd32-err-sock='PATH':: | |
484b2a0c PP |
254 | Set the Unix socket path of the 32-bit consumer daemon error to |
255 | 'PATH'. | |
ee717bf0 PP |
256 | |
257 | option:--ustconsumerd64-err-sock='PATH':: | |
484b2a0c PP |
258 | Set the Unix socket path of the 64-bit consumer daemon error to |
259 | 'PATH'. | |
260 | ||
261 | ||
262 | Buffer size of event notifier error counters | |
263 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
264 | option:--event-notifier-error-buffer-size-kernel='SLOTS':: | |
265 | Set the size of the kernel event notifier error counter buffers to | |
266 | 'SLOTS'{nbsp}slots. | |
267 | ||
268 | option:--event-notifier-error-buffer-size-userspace='SLOTS':: | |
269 | Set the size of the user space event notifier error counter buffers | |
270 | to 'SLOTS'{nbsp}slots. | |
271 | ||
272 | As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this | |
273 | may change in the future. | |
ee717bf0 PP |
274 | |
275 | ||
276 | Verbosity | |
277 | ~~~~~~~~~ | |
278 | option:-q, option:--quiet:: | |
279 | Suppress all messages, including warnings and errors. | |
484b2a0c PP |
280 | + |
281 | You may :not: use this option with the option:--verbose and | |
282 | option:--verbose-consumer options. | |
ee717bf0 PP |
283 | |
284 | option:-v, option:--verbose:: | |
285 | Increase verbosity. | |
286 | + | |
484b2a0c PP |
287 | Specify this option up to three times to get more levels of verbosity. |
288 | + | |
289 | You may :not: use this option with the option:--quiet option. | |
ee717bf0 PP |
290 | |
291 | option:--verbose-consumer:: | |
484b2a0c PP |
292 | Increase the verbosity of the consumer daemons which this session |
293 | daemon spawns. | |
294 | + | |
295 | You may :not: use this option with the option:--quiet option. | |
ee717bf0 PP |
296 | |
297 | ||
298 | Program information | |
299 | ~~~~~~~~~~~~~~~~~~~ | |
484b2a0c | 300 | include::common-help-option.txt[] |
ee717bf0 PP |
301 | |
302 | option:-V, option:--version:: | |
484b2a0c | 303 | Show version and quit. |
ee717bf0 PP |
304 | |
305 | ||
21b35b3a PP |
306 | EXIT STATUS |
307 | ----------- | |
308 | *0*:: | |
309 | Success | |
310 | ||
311 | *1*:: | |
312 | Error | |
313 | ||
314 | *3*:: | |
315 | Fatal error | |
316 | ||
317 | ||
318 | ENVIRONMENT | |
319 | ----------- | |
9bbd8e06 | 320 | `LTTNG_ABORT_ON_ERROR`:: |
484b2a0c PP |
321 | Set to `1` to abort the process after the first error is |
322 | encountered. | |
9bbd8e06 | 323 | |
ee717bf0 | 324 | `LTTNG_APP_SOCKET_TIMEOUT`:: |
484b2a0c PP |
325 | Timeout (in seconds) of the application socket when |
326 | sending/receiving commands. | |
327 | + | |
328 | After this period of time, `lttng-sessiond` unregisters the application. | |
329 | + | |
330 | Set to `0` or `-1` to set an infinite timeout. | |
331 | + | |
332 | Default: +{default_app_socket_rw_timeout}+. | |
ee717bf0 PP |
333 | |
334 | `LTTNG_CONSUMERD32_BIN`:: | |
335 | 32-bit consumer daemon binary path. | |
336 | + | |
188419c4 PP |
337 | The option:--consumerd32-path option overrides this environment |
338 | variable. | |
ee717bf0 PP |
339 | |
340 | `LTTNG_CONSUMERD32_LIBDIR`:: | |
484b2a0c | 341 | 32-bit consumer daemon library directory path. |
ee717bf0 | 342 | + |
188419c4 PP |
343 | The option:--consumerd32-libdir option overrides this environment |
344 | variable. | |
ee717bf0 PP |
345 | |
346 | `LTTNG_CONSUMERD64_BIN`:: | |
347 | 64-bit consumer daemon binary path. | |
348 | + | |
188419c4 PP |
349 | The option:--consumerd64-path option overrides this environment |
350 | variable. | |
ee717bf0 PP |
351 | |
352 | `LTTNG_CONSUMERD64_LIBDIR`:: | |
484b2a0c | 353 | 64-bit consumer daemon library directory path. |
ee717bf0 | 354 | + |
188419c4 PP |
355 | The option:--consumerd64-libdir option overrides this environment |
356 | variable. | |
ee717bf0 PP |
357 | |
358 | `LTTNG_DEBUG_NOCLONE`:: | |
484b2a0c PP |
359 | Set to `1` to disable the use of man:clone(2)/man:fork(2). |
360 | + | |
188419c4 PP |
361 | Setting this environment variable is considered insecure, but it's |
362 | required to allow debuggers to work with `lttng-sessiond` on some | |
363 | operating systems. | |
ee717bf0 PP |
364 | |
365 | `LTTNG_EXTRA_KMOD_PROBES`:: | |
484b2a0c | 366 | Extra LTTng kernel probe modules to load. |
ee717bf0 | 367 | + |
484b2a0c PP |
368 | See the option:--extra-kmod-probes option which overrides this |
369 | environment variable. | |
ee717bf0 PP |
370 | |
371 | `LTTNG_KMOD_PROBES`:: | |
484b2a0c | 372 | Exclusive LTTng kernel probe modules to load. |
ee717bf0 | 373 | + |
484b2a0c PP |
374 | See the option:--kmod-probes option which overrides this environment |
375 | variable. | |
ee717bf0 PP |
376 | |
377 | `LTTNG_NETWORK_SOCKET_TIMEOUT`:: | |
484b2a0c PP |
378 | Socket connection, receive, and send timeout (milliseconds). |
379 | + | |
380 | Set to `0` or `-1` to use the timeout of the operating system (default). | |
ee717bf0 PP |
381 | |
382 | `LTTNG_SESSION_CONFIG_XSD_PATH`:: | |
aaae4813 | 383 | Recording session configuration XML schema definition (XSD) path. |
ee717bf0 PP |
384 | |
385 | ||
900690ca PP |
386 | FILES |
387 | ----- | |
388 | `$LTTNG_HOME/.lttng`:: | |
484b2a0c | 389 | Unix user's LTTng runtime and configuration directory. |
900690ca PP |
390 | |
391 | `$LTTNG_HOME/lttng-traces`:: | |
484b2a0c PP |
392 | Default output directory of LTTng traces in local and snapshot |
393 | modes. | |
394 | + | |
395 | Override this path with the nloption:--output option of the | |
396 | man:lttng-create(1) command. | |
900690ca | 397 | |
41c9a411 | 398 | `$LTTNG_HOME/.lttng/sessions/auto`:: |
aaae4813 | 399 | Directory from which `lttng-sessiond` loads Unix user recording |
484b2a0c PP |
400 | session configurations when starting. |
401 | + | |
aaae4813 PP |
402 | See the ``<<load,Recording session configuration loading>>'' section |
403 | above to learn more. | |
41c9a411 PP |
404 | |
405 | +{system_sessions_auto_dir}+:: | |
aaae4813 | 406 | Directory from which `lttng-sessiond` loads system-wide recording |
484b2a0c PP |
407 | session configurations when starting. |
408 | + | |
aaae4813 PP |
409 | See the ``<<load,Recording session configuration loading>>'' section |
410 | above to learn more. | |
900690ca PP |
411 | |
412 | `$LTTNG_HOME/.lttng/lttng.conf`:: | |
484b2a0c PP |
413 | Unix user's LTTng daemon INI configuration file. |
414 | + | |
7d259724 | 415 | See the ``<<cfg,Daemon configuration>>'' section above to learn more. |
900690ca | 416 | |
d8065e7e | 417 | +{system_lttng_conf}+:: |
484b2a0c PP |
418 | System-wide LTTng daemon INI configuration file. |
419 | + | |
7d259724 | 420 | See the ``<<cfg,Daemon configuration>>'' section above to learn more. |
900690ca | 421 | |
484b2a0c | 422 | NOTE: `$LTTNG_HOME` defaults to `$HOME`. |
900690ca PP |
423 | |
424 | ||
ee717bf0 PP |
425 | include::common-footer.txt[] |
426 | ||
427 | ||
428 | SEE ALSO | |
429 | -------- | |
188419c4 PP |
430 | man:lttng(1), |
431 | man:lttng-concepts(7) |