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