3 :revdate: 21 April 2021
8 lttng-sessiond - LTTng session daemon
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:--event-notifier-error-buffer-size-kernel='SLOTS']
29 [option:--event-notifier-error-buffer-size-userspace='SLOTS']
30 [option:--quiet | [option:--verbose]... [option:--verbose-consumer]]
35 include::common-intro.txt[]
37 An LTTng session daemon, `lttng-sessiond`, is a program which:
39 * Manages tracing sessions (see man:lttng-create(1) to learn more about
42 * Controls the various components (like tracers and consumer daemons) of
45 * Sends asynchronous notifications to user applications.
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`).
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.
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.
60 See the ``Session daemon connection'' section of man:lttng(1) to learn
61 how a user application connects to a session daemon.
63 A session daemon manages trace data consumer daemons, spawning them when
64 necessary. You do :not: need to manage the consumer daemons yourself.
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.
71 NOTE: The LTTng project recommends that you start the session daemon at
72 boot time for stable and long-term tracing.
78 When you run `lttng-sessiond`, it configures itself from, in this order:
80 . The INI configuration file +{system_lttng_conf}+, if any.
82 . The INI configuration file `$LTTNG_HOME/.lttng/lttng.conf`, if any.
84 `$LTTNG_HOME` defaults to `$HOME`.
86 . With the option:--config='PATH' option: the INI configuration file
89 . The command-line options.
91 Each step can override a previous configuration property.
93 In INI configuration files, the session daemon only reads the properties
94 under the `sessiond` INI section. Each INI property is:
97 The long name of a command-line option to set (see the
98 <<options,OPTIONS>> section below).
101 The selected command-line option accepts an argument:::
102 Option argument (string).
104 The selected command-line option is a switch:::
115 INI configuration file example:
121 extra-kmod-probes=my-driver,other-module
126 Tracing session configuration loading
127 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128 When the session daemon starts, it loads tracing session configurations
131 Without the option:--load option::
135 . All the files in `$LTTNG_HOME/.lttng/sessions/auto`.
137 `$LTTNG_HOME` defaults to `$HOME`.
139 . All the files in +{system_sessions_auto_dir}+.
142 `lttng-sessiond` only loads tracing configuration files from the
143 directories above if its UID and their UID are the same.
145 With the option:--load='PATH' option::
146 'PATH' is a directory:::
147 All the files in 'PATH'.
158 option:-b, option:--background::
159 Start as a Unix daemon, but keep file descriptors (console) open.
161 With this option, `lttng-sessiond` ensures the daemon is ready to
162 receive client commands before it exits.
164 Use the option:--daemonize option instead to close the file descriptors.
166 option:-f 'PATH', option:--config='PATH'::
167 Configure the daemon using the INI configuration file 'PATH' in
168 addition to the default configuration files and the command-line
171 See the <<cfg,Daemon configuration>> section above.
173 option:-d, option:--daemonize::
174 Start as a Unix daemon and close file descriptors (console).
176 With this option, `lttng-sessiond` ensures the daemon is ready to
177 receive client commands before it exits.
179 Use the option:--background option instead to keep the file descriptors
182 option:-g 'GROUP', option:--group='GROUP'::
183 Set the Unix tracing group to 'GROUP' instead of `tracing`.
185 This option is only meaningful when the `root` Unix user starts
188 Members of the Unix tracing group may connect to the root session daemon
189 and, therefore, control LTTng kernel tracing.
191 option:-l 'PATH', option:--load='PATH'::
192 Load tracing session configurations from 'PATH', either a directory
193 or a file, instead of loading them from the default search
196 See the <<load,Tracing session configuration loading>> section above.
198 option:-S, option:--sig-parent::
199 Send the `USR1` signal to the parent process to notify readiness.
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.
210 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
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.
215 option:--kmod-probes='PROBE'[,'PROBE']...::
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.
221 Disable Linux kernel tracing.
226 option:--agent-tcp-port='PORT'::
227 Listen on TCP port 'PORT' for agent application registration
228 instead of a port within the range
229 [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
231 option:-a 'PATH', option:--apps-sock='PATH'::
232 Set the application Unix socket path to 'PATH'.
234 option:-c 'PATH', option:--client-sock='PATH'::
235 Set the client Unix socket path to 'PATH'.
237 option:--consumerd32-libdir='PATH'::
238 Set the 32-bit consumer daemon library directory to 'PATH'.
240 option:--consumerd32-path='PATH'::
241 Set the 32-bit consumer daemon binary path to 'PATH'.
243 option:--consumerd64-libdir='PATH'::
244 Set the 64-bit consumer daemon library directory to 'PATH'.
246 option:--consumerd64-path='PATH'::
247 Set the 64-bit consumer daemon binary path to 'PATH'.
249 option:--kconsumerd-cmd-sock='PATH'::
250 Set the command Unix socket path of the Linux kernel consumer daemon
253 option:--kconsumerd-err-sock='PATH'::
254 Set the error Unix socket path of the Linux kernel consumer daemon
257 option:--ustconsumerd32-cmd-sock='PATH'::
258 Set the Unix socket path of the 32-bit consumer daemon command to
261 option:--ustconsumerd64-cmd-sock='PATH'::
262 Set the Unix socket path of the 64-bit consumer daemon command to
265 option:--ustconsumerd32-err-sock='PATH'::
266 Set the Unix socket path of the 32-bit consumer daemon error to
269 option:--ustconsumerd64-err-sock='PATH'::
270 Set the Unix socket path of the 64-bit consumer daemon error to
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
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.
284 As of LTTng{nbsp}{lttng_version}, a _slot_ is a 32-bit counter, but this
285 may change in the future.
290 option:-q, option:--quiet::
291 Suppress all messages, including warnings and errors.
293 You may :not: use this option with the option:--verbose and
294 option:--verbose-consumer options.
296 option:-v, option:--verbose::
299 Specify this option up to three times to get more levels of verbosity.
301 You may :not: use this option with the option:--quiet option.
303 option:--verbose-consumer::
304 Increase the verbosity of the consumer daemons which this session
307 You may :not: use this option with the option:--quiet option.
312 include::common-help-option.txt[]
314 option:-V, option:--version::
315 Show version and quit.
318 ENVIRONMENT VARIABLES
319 ---------------------
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 variable.
339 `LTTNG_CONSUMERD32_LIBDIR`::
340 32-bit consumer daemon library directory path.
342 The option:--consumerd32-libdir option overrides this variable.
344 `LTTNG_CONSUMERD64_BIN`::
345 64-bit consumer daemon binary path.
347 The option:--consumerd64-path option overrides this variable.
349 `LTTNG_CONSUMERD64_LIBDIR`::
350 64-bit consumer daemon library directory path.
352 The option:--consumerd64-libdir option overrides this variable.
354 `LTTNG_DEBUG_NOCLONE`::
355 Set to `1` to disable the use of man:clone(2)/man:fork(2).
357 Setting this variable is considered insecure, but it's required to allow
358 debuggers to work with `lttng-sessiond` on some operating systems.
360 `LTTNG_EXTRA_KMOD_PROBES`::
361 Extra LTTng kernel probe modules to load.
363 See the option:--extra-kmod-probes option which overrides this
364 environment variable.
366 `LTTNG_KMOD_PROBES`::
367 Exclusive LTTng kernel probe modules to load.
369 See the option:--kmod-probes option which overrides this environment
372 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
373 Socket connection, receive, and send timeout (milliseconds).
375 Set to `0` or `-1` to use the timeout of the operating system (default).
377 `LTTNG_SESSION_CONFIG_XSD_PATH`::
378 Tracing session configuration XML schema definition (XSD) path.
383 `$LTTNG_HOME/.lttng`::
384 Unix user's LTTng runtime and configuration directory.
386 `$LTTNG_HOME/lttng-traces`::
387 Default output directory of LTTng traces in local and snapshot
390 Override this path with the nloption:--output option of the
391 man:lttng-create(1) command.
393 `$LTTNG_HOME/.lttng/sessions/auto`::
394 Directory from which `lttng-sessiond` loads Unix user tracing
395 session configurations when starting.
397 See the <<load,Tracing session configuration loading>> section above to
400 +{system_sessions_auto_dir}+::
401 Directory from which `lttng-sessiond` loads system-wide tracing
402 session configurations when starting.
404 See the <<load,Tracing session configuration loading>> section above to
407 `$LTTNG_HOME/.lttng/lttng.conf`::
408 Unix user's LTTng daemon INI configuration file.
410 See the <<cfg,Daemon configuration>> section above to learn more.
412 +{system_lttng_conf}+::
413 System-wide LTTng daemon INI configuration file.
415 See the <<cfg,Daemon configuration>> section above to learn more.
417 NOTE: `$LTTNG_HOME` defaults to `$HOME`.
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.
440 For the `root` user, the limit is usually 65,535.
443 include::common-footer.txt[]