3 :revdate: 21 April 2021
4 :daemon-bin-name: lttng-sessiond
5 :daemon-ini-section: sessiond
10 lttng-sessiond - LTTng session daemon
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']
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]]
37 include::common-intro.txt[]
39 An LTTng session daemon, `lttng-sessiond`, is a program which:
41 * Manages tracing sessions (see man:lttng-concepts(7) to learn more
42 about tracing sessions).
44 * Controls the various components (like tracers and consumer daemons) of
47 * Sends asynchronous notifications to user applications.
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`).
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.
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.
62 See the ``Session daemon connection'' section of man:lttng(1) to learn
63 how a user application connects to a session daemon.
65 A session daemon manages trace data consumer daemons, spawning them when
66 necessary. You do :not: need to manage the consumer daemons yourself.
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.
73 NOTE: The LTTng project recommends that you start the session daemon at
74 boot time for stable and long-term tracing.
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.
84 For the `root` user, the limit is usually 65,535.
88 include::common-daemon-cfg.txt[]
90 INI configuration file example:
96 extra-kmod-probes=my-driver,other-module
101 Tracing session configuration loading
102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103 When the session daemon starts, it loads tracing session configurations
106 Without the option:--load option::
110 . All the files in `$LTTNG_HOME/.lttng/sessions/auto`.
112 `$LTTNG_HOME` defaults to `$HOME`.
114 . All the files in +{system_sessions_auto_dir}+.
117 `lttng-sessiond` only loads tracing configuration files from the
118 directories above if its UID and their UID are the same.
120 With the option:--load='PATH' option::
121 'PATH' is a directory:::
122 All the files in 'PATH'.
131 General daemon configuration
132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 option:-b, option:--background::
134 Start as a Unix daemon, but keep file descriptors (console) open.
136 With this option, `lttng-sessiond` ensures the daemon is ready to
137 receive client commands before it exits.
139 Use the option:--daemonize option instead to close the file descriptors.
141 option:-f 'PATH', option:--config='PATH'::
142 Configure the daemon using the INI configuration file 'PATH' in
143 addition to the default configuration files and the command-line
146 See the ``<<cfg,Daemon configuration>>'' section above.
148 option:-d, option:--daemonize::
149 Start as a Unix daemon and close file descriptors (console).
151 With this option, `lttng-sessiond` ensures the daemon is ready to
152 receive client commands before it exits.
154 Use the option:--background option instead to keep the file descriptors
157 option:-g 'GROUP', option:--group='GROUP'::
158 Set the Unix tracing group to 'GROUP' instead of `tracing`.
160 This option is only meaningful when the `root` Unix user starts
163 Members of the Unix tracing group may connect to the root session daemon
164 and, therefore, control LTTng kernel tracing.
166 option:-l 'PATH', option:--load='PATH'::
167 Load tracing session configurations from 'PATH', either a directory
168 or a file, instead of loading them from the default search
171 See the ``<<load,Tracing session configuration loading>>'' section
174 option:-S, option:--sig-parent::
175 Send the `USR1` signal to the parent process to notify readiness.
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.
186 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
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.
191 See also the `LTTNG_EXTRA_KMOD_PROBES` environment variable.
193 option:--kmod-probes='PROBE'[,'PROBE']...::
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.
198 See also the `LTTNG_KMOD_PROBES` environment variable.
201 Disable Linux kernel tracing.
206 option:--agent-tcp-port='PORT'::
207 Listen on TCP port 'PORT' for agent application registration
208 instead of a port within the range
209 [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
211 option:-a 'PATH', option:--apps-sock='PATH'::
212 Set the application Unix socket path to 'PATH'.
214 option:-c 'PATH', option:--client-sock='PATH'::
215 Set the client Unix socket path to 'PATH'.
217 option:--consumerd32-libdir='PATH'::
218 Set the 32-bit consumer daemon library directory to 'PATH'.
220 See also the `LTTNG_CONSUMERD32_LIBDIR` environment variable.
222 option:--consumerd32-path='PATH'::
223 Set the 32-bit consumer daemon binary path to 'PATH'.
225 See also the `LTTNG_CONSUMERD32_BIN` environment variable.
227 option:--consumerd64-libdir='PATH'::
228 Set the 64-bit consumer daemon library directory to 'PATH'.
230 See also the `LTTNG_CONSUMERD64_LIBDIR` environment variable.
232 option:--consumerd64-path='PATH'::
233 Set the 64-bit consumer daemon binary path to 'PATH'.
235 See also the `LTTNG_CONSUMERD32_BIN` environment variable.
237 option:--kconsumerd-cmd-sock='PATH'::
238 Set the command Unix socket path of the Linux kernel consumer daemon
241 option:--kconsumerd-err-sock='PATH'::
242 Set the error Unix socket path of the Linux kernel consumer daemon
245 option:--ustconsumerd32-cmd-sock='PATH'::
246 Set the Unix socket path of the 32-bit consumer daemon command to
249 option:--ustconsumerd64-cmd-sock='PATH'::
250 Set the Unix socket path of the 64-bit consumer daemon command to
253 option:--ustconsumerd32-err-sock='PATH'::
254 Set the Unix socket path of the 32-bit consumer daemon error to
257 option:--ustconsumerd64-err-sock='PATH'::
258 Set the Unix socket path of the 64-bit consumer daemon error to
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
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.
272 As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
273 may change in the future.
278 option:-q, option:--quiet::
279 Suppress all messages, including warnings and errors.
281 You may :not: use this option with the option:--verbose and
282 option:--verbose-consumer options.
284 option:-v, option:--verbose::
287 Specify this option up to three times to get more levels of verbosity.
289 You may :not: use this option with the option:--quiet option.
291 option:--verbose-consumer::
292 Increase the verbosity of the consumer daemons which this session
295 You may :not: use this option with the option:--quiet option.
300 include::common-help-option.txt[]
302 option:-V, option:--version::
303 Show version and quit.
320 `LTTNG_ABORT_ON_ERROR`::
321 Set to `1` to abort the process after the first error is
324 `LTTNG_APP_SOCKET_TIMEOUT`::
325 Timeout (in seconds) of the application socket when
326 sending/receiving commands.
328 After this period of time, `lttng-sessiond` unregisters the application.
330 Set to `0` or `-1` to set an infinite timeout.
332 Default: +{default_app_socket_rw_timeout}+.
334 `LTTNG_CONSUMERD32_BIN`::
335 32-bit consumer daemon binary path.
337 The option:--consumerd32-path option overrides this environment
340 `LTTNG_CONSUMERD32_LIBDIR`::
341 32-bit consumer daemon library directory path.
343 The option:--consumerd32-libdir option overrides this environment
346 `LTTNG_CONSUMERD64_BIN`::
347 64-bit consumer daemon binary path.
349 The option:--consumerd64-path option overrides this environment
352 `LTTNG_CONSUMERD64_LIBDIR`::
353 64-bit consumer daemon library directory path.
355 The option:--consumerd64-libdir option overrides this environment
358 `LTTNG_DEBUG_NOCLONE`::
359 Set to `1` to disable the use of man:clone(2)/man:fork(2).
361 Setting this environment variable is considered insecure, but it's
362 required to allow debuggers to work with `lttng-sessiond` on some
365 `LTTNG_EXTRA_KMOD_PROBES`::
366 Extra LTTng kernel probe modules to load.
368 See the option:--extra-kmod-probes option which overrides this
369 environment variable.
371 `LTTNG_KMOD_PROBES`::
372 Exclusive LTTng kernel probe modules to load.
374 See the option:--kmod-probes option which overrides this environment
377 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
378 Socket connection, receive, and send timeout (milliseconds).
380 Set to `0` or `-1` to use the timeout of the operating system (default).
382 `LTTNG_SESSION_CONFIG_XSD_PATH`::
383 Tracing session configuration XML schema definition (XSD) path.
388 `$LTTNG_HOME/.lttng`::
389 Unix user's LTTng runtime and configuration directory.
391 `$LTTNG_HOME/lttng-traces`::
392 Default output directory of LTTng traces in local and snapshot
395 Override this path with the nloption:--output option of the
396 man:lttng-create(1) command.
398 `$LTTNG_HOME/.lttng/sessions/auto`::
399 Directory from which `lttng-sessiond` loads Unix user tracing
400 session configurations when starting.
402 See the ``<<load,Tracing session configuration loading>>'' section above
405 +{system_sessions_auto_dir}+::
406 Directory from which `lttng-sessiond` loads system-wide tracing
407 session configurations when starting.
409 See the ``<<load,Tracing session configuration loading>>'' section above
412 `$LTTNG_HOME/.lttng/lttng.conf`::
413 Unix user's LTTng daemon INI configuration file.
415 See the ``<<cfg,Daemon configuration>>'' section above to learn more.
417 +{system_lttng_conf}+::
418 System-wide LTTng daemon INI configuration file.
420 See the ``<<cfg,Daemon configuration>>'' section above to learn more.
422 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
425 include::common-footer.txt[]
431 man:lttng-concepts(7)