3 :revdate: 17 September 2018
8 lttng-sessiond - LTTng 2 tracing 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='SIZE']
29 [option:--event-notifier-error-buffer-size-userspace='SIZE']
30 [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]
35 The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
36 source software package used for correlated tracing of the Linux kernel,
37 user applications, and user libraries.
39 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
40 dynamically loaded libraries (for user application and library tracing).
42 The _LTTng session daemon_ is a tracing registry which allows the user
43 to interact with multiple tracers (kernel and user space) within the
44 same container, a _tracing session_. Traces can be gathered from the
45 Linux kernel and/or from instrumented applications (see
46 man:lttng-ust(3)). You can aggregate and read the events of LTTng
47 traces using man:babeltrace2(1).
49 To trace the Linux kernel, the session daemon needs to be running as
50 `root`. LTTng uses a _tracing group_ to allow specific users to interact
51 with the root session daemon. The default tracing group name is
52 `tracing`. You can use the option:--group option to set the tracing
55 Session daemons can coexist. You can have a session daemon running as
56 user Alice that can be used to trace her applications alongside a root
57 session daemon or a session daemon running as user Bob.
59 The LTTng session daemon manages trace data consumer daemons by spawning
60 them when necessary. You do not need to manage the consumer daemons
63 NOTE: It is highly recommended to start the session daemon at boot time
64 for stable and long-term tracing.
67 Automatic loading of tracing session configurations
68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69 When the session daemon starts, it automatically loads session
72 The following directories are searched, non-recursively, in this order
73 for configuration files to load on launch:
75 . `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`)
76 . +{system_sessions_auto_dir}+
78 Note that both the directory containing the tracing session
79 configurations _and_ the session daemon binary _must_ share the same UID
80 for the configurations to be automatically loaded.
82 The option:--load option overrides the default directories _and_ the UID
83 check. The session daemon simply checks if the path is accessible and
84 tries to load every tracing session configuration in it. When this
85 option is specified, the default directories are :not: searched for
86 configuration files. When the option is not specified, _both_ default
87 directories are searched for configuration files.
89 If the option:--load option's argument is a directory, then all the
90 tracing session configurations found in all the files in this directory
91 are loaded. If the argument is a file, then all the tracing session
92 configurations found in this file are loaded.
99 option:-b, option:--background::
100 Start as Unix daemon, but keep file descriptors (console) open.
101 Use the option:--daemonize option instead to close the file
104 option:-f 'PATH', option:--config='PATH'::
105 Load session daemon configuration from path 'PATH'.
107 option:-d, option:--daemonize::
108 Start as Unix daemon, and close file descriptors (console). Use the
109 option:--background option instead to keep the file descriptors
112 option:-g 'GROUP', option:--group='GROUP'::
113 Use 'GROUP' as Unix tracing group (default: `tracing`).
115 option:-l 'PATH', option:--load='PATH'::
116 Automatically load tracing session configurations from 'PATH',
117 either a directory or a file, instead of loading them from the
118 default search directories.
120 option:-S, option:--sig-parent::
121 Send `SIGUSR1` to parent process to notify readiness.
123 NOTE: This is used by man:lttng(1) to get notified when the
124 session daemon is ready to accept commands. When building a third party
125 tool on liblttng-ctl, this option can be very handy to synchronize the
126 control tool and the session daemon.
128 option:--event-notifier-error-buffer-size-kernel='SIZE'::
129 Set the size of the kernel event notifier error counter buffers to 'SIZE.
131 option:--event-notifier-error-buffer-size-userspace='SIZE'::
132 Set the size of the userspace event notifier error counter buffers to
138 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
139 Load specific LTTng Linux kernel modules when kernel tracing
140 is enabled (option:--no-kernel option is :not: specified), in
141 addition to loading the default list of LTTng kernel modules.
143 Only the name of the probe needs to be specified, without the
144 `lttng-probe-` prefix and without the kernel module extension suffix.
145 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
148 option:--kmod-probes='PROBE'[,'PROBE']...::
149 Only load specific LTTng Linux kernel modules when kernel tracing
150 is enabled (option:--no-kernel option is :not: specified).
152 Only the name of the probe needs to be specified, without the
153 `lttng-probe-` prefix and without the kernel module extension suffix.
154 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
158 Disable Linux kernel tracing.
163 option:--agent-tcp-port='PORT'::
164 Listen on TCP port 'PORT' for agent application registrations
165 (default: a port within the range
166 [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
168 option:-a 'PATH', option:--apps-sock='PATH'::
169 Set application Unix socket path to 'PATH'.
171 option:-c 'PATH', option:--client-sock='PATH'::
172 Set client Unix socket path to 'PATH'.
174 option:--consumerd32-libdir='PATH'::
175 Set 32-bit consumer daemon library directory to 'PATH'.
177 option:--consumerd32-path='PATH'::
178 Set 32-bit consumer daemon binary path to 'PATH'.
180 option:--consumerd64-libdir='PATH'::
181 Set 64-bit consumer daemon library directory to 'PATH'.
183 option:--consumerd64-path='PATH'::
184 Set 64-bit consumer daemon binary path to 'PATH'.
186 option:--kconsumerd-cmd-sock='PATH'::
187 Set Linux kernel consumer daemon's command Unix socket path
190 option:--kconsumerd-err-sock='PATH'::
191 Set Linux kernel consumer daemon's error Unix socket path
194 option:--ustconsumerd32-cmd-sock='PATH'::
195 Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
197 option:--ustconsumerd64-cmd-sock='PATH'::
198 Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
200 option:--ustconsumerd32-err-sock='PATH'::
201 Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
203 option:--ustconsumerd64-err-sock='PATH'::
204 Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
209 option:-q, option:--quiet::
210 Suppress all messages, including warnings and errors.
212 option:-v, option:--verbose::
215 Three levels of verbosity are available, which are triggered by
216 appending additional `v` letters to the option
217 (that is, `-vv` and `-vvv`).
219 option:--verbose-consumer::
220 Increase verbosity of consumer daemons spawned by this session
226 option:-h, option:--help::
229 option:-V, option:--version::
233 ENVIRONMENT VARIABLES
234 ---------------------
235 Note that command-line options override their equivalent environment
238 `LTTNG_ABORT_ON_ERROR`::
239 Set to 1 to abort the process after the first error is encountered.
241 `LTTNG_APP_SOCKET_TIMEOUT`::
242 Application socket's timeout (seconds) when sending/receiving
243 commands. After this period of time, the application is unregistered
244 by the session daemon. A value of 0 or -1 means an infinite timeout.
245 Default value: {default_app_socket_rw_timeout}.
247 `LTTNG_CONSUMERD32_BIN`::
248 32-bit consumer daemon binary path.
250 The option:--consumerd32-path option overrides this variable.
252 `LTTNG_CONSUMERD32_LIBDIR`::
253 32-bit consumer daemon library path.
255 The option:--consumerd32-libdir option overrides this variable.
257 `LTTNG_CONSUMERD64_BIN`::
258 64-bit consumer daemon binary path.
260 The option:--consumerd64-path option overrides this variable.
262 `LTTNG_CONSUMERD64_LIBDIR`::
263 64-bit consumer daemon library path.
265 The option:--consumerd64-libdir option overrides this variable.
267 `LTTNG_DEBUG_NOCLONE`::
268 Set to 1 to disable the use of `clone()`/`fork()`. Setting this
269 variable is considered insecure, but it is required to allow
270 debuggers to work with the session daemon on some operating systems.
272 `LTTNG_EXTRA_KMOD_PROBES`::
273 Load specific LTTng Linux kernel modules when kernel tracing
274 is enabled (option:--no-kernel option is :not: specified), in
275 addition to loading the default list of LTTng kernel modules.
277 The option:--extra-kmod-probes option overrides this variable.
279 `LTTNG_KMOD_PROBES`::
280 Only load specific LTTng Linux kernel modules when kernel tracing
281 is enabled (option:--no-kernel option is :not: specified).
283 The option:--kmod-probes option overrides this variable.
285 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
286 Socket connection, receive and send timeout (milliseconds). A value
287 of 0 or -1 uses the timeout of the operating system (default).
289 `LTTNG_SESSION_CONFIG_XSD_PATH`::
290 Tracing session configuration XML schema definition (XSD) path.
295 `$LTTNG_HOME/.lttng`::
296 User LTTng runtime and configuration directory.
298 `$LTTNG_HOME/lttng-traces`::
299 Default output directory of LTTng traces. This can be overridden
300 with the nloption:--output option of the man:lttng-create(1)
303 `$LTTNG_HOME/.lttng/sessions/auto`::
304 Directory from which user tracing configuration files are
305 automatically loaded when the session daemon starts (see
306 man:lttng-save(1) and man:lttng-load(1) for saving
307 and loading tracing sessions).
309 +{system_sessions_auto_dir}+::
310 Directory from which system-wide tracing configuration files are
311 automatically loaded when the session daemon starts (see
312 man:lttng-save(1) and man:lttng-load(1) for saving
313 and loading tracing sessions).
315 `$LTTNG_HOME/.lttng/lttng.conf`::
316 Default location of the session daemon configuration file (see the
317 option:--config option).
319 +{system_lttng_conf}+::
320 System-wide location of the session daemon configuration file (see
321 the option:--config option).
323 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
340 For an unprivileged user running `lttng-sessiond`, the maximum number of
341 file descriptors per process is usually 1024. This limits the number of
342 traceable applications, since for each instrumented application, there
343 is two file descriptors per CPU and one more socket for bidirectional
346 For the root user, the limit is bumped to 65535. A future version will
347 deal with this limitation.
350 include::common-footer.txt[]