7 lttng-sessiond - LTTng 2 tracing session daemon
13 *lttng-sessiond* [option:--background | option:--daemonize] [option:--sig-parent]
14 [option:--config='PATH'] [option:--group='GROUP'] [option:--load='PATH']
15 [option:--agent-tcp-port='PORT']
16 [option:--apps-sock='PATH'] [option:--client-sock='PATH']
17 [option:--no-kernel | [option:--kmod-probes='PROBE'[,'PROBE']...]
18 [option:--extra-kmod-probes='PROBE'[,'PROBE']...]
19 [option:--kconsumerd-err-sock='PATH']
20 [option:--kconsumerd-cmd-sock='PATH']]
21 [option:--ustconsumerd32-err-sock='PATH']
22 [option:--ustconsumerd64-err-sock='PATH']
23 [option:--ustconsumerd32-cmd-sock='PATH']
24 [option:--ustconsumerd64-cmd-sock='PATH']
25 [option:--consumerd32-path='PATH'] [option:--consumerd32-libdir='PATH']
26 [option:--consumerd64-path='PATH'] [option:--consumerd64-libdir='PATH']
27 [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]
32 The http://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
33 source software package used for correlated tracing of the Linux kernel,
34 user applications, and user libraries.
36 LTTng consists of Linux kernel modules (for Linux kernel tracing) and
37 dynamically loaded libraries (for user application and library tracing).
39 The _LTTng session daemon_ is a tracing registry which allows the user
40 to interact with multiple tracers (kernel and user space) within the
41 same container, a _tracing session_. Traces can be gathered from the
42 Linux kernel and/or from instrumented applications (see
43 man:lttng-ust(3)). You can aggregate and read the events of LTTng
44 traces using man:babeltrace(1).
46 To trace the Linux kernel, the session daemon needs to be running as
47 `root`. LTTng uses a _tracing group_ to allow specific users to interact
48 with the root session daemon. The default tracing group name is
49 `tracing`. You can use the option:--group option to set the tracing
52 Session daemons can coexist. You can have a session daemon running as
53 user Alice that can be used to trace her applications alongside a root
54 session daemon or a session daemon running as user Bob.
56 The LTTng session daemon manages trace data consumer daemons by spawning
57 them when necessary. You do not need to manage the consumer daemons
60 NOTE: It is highly recommended to start the session daemon at boot time
61 for stable and long-term tracing.
64 Loading tracing session configurations
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 By default, the LTTng session daemon tries to load tracing session
67 configurations located in the user default directory
68 `$HOME/.lttng/sessions` and in the system one, +{system_sessions_dir}+.
69 Note that both the directory containing the tracing session
70 configurations and the session daemon binary _must_ have the same UID
71 for the configurations to be automatically loaded.
73 Specifying a path with the option:--load option overrides the default
74 directory _and_ the UID check. The session daemon simply checks if the
75 path is accessible and tries to load every tracing session configuration
83 option:-b, option:--background::
84 Start as Unix daemon, but keep file descriptors (console) open.
85 Use the option:--daemonize option instead to close the file
88 option:-d, option:--daemonize::
89 Start as Unix daemon, and close file descriptors (console). Use the
90 option:--background option instead to keep the file descriptors
93 option:-f, option:--config='PATH'::
94 Load session daemon configuration from path 'PATH'.
96 option:-g, option:--group='GROUP'::
97 Use 'GROUP' as Unix tracing group (default: `tracing`).
99 option:-l, option:--load='PATH'::
100 Automatically load tracing session configurations from path 'PATH'.
102 option:-S, option:--sig-parent::
103 Send `SIGUSR1` to parent process to notify readiness.
105 NOTE: This is used by man:lttng(1) to get notified when the
106 session daemon is ready to accept commands. When building a third party
107 tool on liblttng-ctl, this option can be very handy to synchronize the
108 control tool and the session daemon.
113 option:--extra-kmod-probes='PROBE'[,'PROBE']...::
114 Load specific LTTng Linux kernel modules when kernel tracing
115 is enabled (option:--no-kernel option is :not: specified), in
116 addition to loading the default list of LTTng kernel modules.
118 Only the name of the probe needs to be specified, without the
119 `lttng-probe-` prefix and without the kernel module extension suffix.
120 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
123 option:--kmod-probes='PROBE'[,'PROBE']...::
124 Only load specific LTTng Linux kernel modules when kernel tracing
125 is enabled (option:--no-kernel option is :not: specified).
127 Only the name of the probe needs to be specified, without the
128 `lttng-probe-` prefix and without the kernel module extension suffix.
129 For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
133 Disable Linux kernel tracing.
138 option:--agent-tcp-port='PORT'::
139 Listen on TCP port 'PORT' for agent application registrations
142 option:-a, option:--apps-sock='PATH'::
143 Set application Unix socket path to 'PATH'.
145 option:-c, option:--client-sock='PATH'::
146 Set client Unix socket path to 'PATH'.
148 option:--consumerd32-libdir='PATH'::
149 Set 32-bit consumer daemon library directory to 'PATH'.
151 option:--consumerd32-path='PATH'::
152 Set 32-bit consumer daemon binary path to 'PATH'.
154 option:--consumerd64-libdir='PATH'::
155 Set 64-bit consumer daemon library directory to 'PATH'.
157 option:--consumerd64-path='PATH'::
158 Set 64-bit consumer daemon binary path to 'PATH'.
160 option:--kconsumerd-cmd-sock='PATH'::
161 Set Linux kernel consumer daemon's command Unix socket path
164 option:--kconsumerd-err-sock='PATH'::
165 Set Linux kernel consumer daemon's error Unix socket path
168 option:--ustconsumerd32-cmd-sock='PATH'::
169 Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
171 option:--ustconsumerd64-cmd-sock='PATH'::
172 Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
174 option:--ustconsumerd32-err-sock='PATH'::
175 Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
177 option:--ustconsumerd64-err-sock='PATH'::
178 Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
183 option:-q, option:--quiet::
184 Suppress all messages, including warnings and errors.
186 option:-v, option:--verbose::
189 Three levels of verbosity are available, which are triggered by
190 appending additional `v` letters to the option
191 (that is, `-vv` and `-vvv`).
193 option:--verbose-consumer::
194 Increase verbosity of consumer daemons spawned by this session
200 option:-h, option:--help::
203 option:-V, option:--version::
207 ENVIRONMENT VARIABLES
208 ---------------------
209 Note that command-line options override their equivalent environment
212 `LTTNG_APP_SOCKET_TIMEOUT`::
213 Application socket's timeout (seconds) when sending/receiving
214 commands. After this period of time, the application is unregistered
215 by the session daemon. A value of 0 or -1 means an infinite timeout.
218 `LTTNG_CONSUMERD32_BIN`::
219 32-bit consumer daemon binary path.
221 The option:--consumerd32-path option overrides this variable.
223 `LTTNG_CONSUMERD32_LIBDIR`::
224 32-bit consumer daemon library path.
226 The option:--consumerd32-libdir option overrides this variable.
228 `LTTNG_CONSUMERD64_BIN`::
229 64-bit consumer daemon binary path.
231 The option:--consumerd64-path option overrides this variable.
233 `LTTNG_CONSUMERD64_LIBDIR`::
234 64-bit consumer daemon library path.
236 The option:--consumerd64-libdir option overrides this variable.
238 `LTTNG_DEBUG_NOCLONE`::
239 Set to 1 to disable the use of `clone()`/`fork()`. Setting this
240 variable is considered insecure, but it is required to allow
241 debuggers to work with the session daemon on some operating systems.
243 `LTTNG_EXTRA_KMOD_PROBES`::
244 Load specific LTTng Linux kernel modules when kernel tracing
245 is enabled (option:--no-kernel option is :not: specified), in
246 addition to loading the default list of LTTng kernel modules.
248 The option:--extra-kmod-probes option overrides this variable.
250 `LTTNG_KMOD_PROBES`::
251 Only load specific LTTng Linux kernel modules when kernel tracing
252 is enabled (option:--no-kernel option is :not: specified).
254 The option:--kmod-probes option overrides this variable.
256 `LTTNG_NETWORK_SOCKET_TIMEOUT`::
257 Socket connection, receive and send timeout (milliseconds). A value
258 of 0 or -1 uses the timeout of the operating system (default).
260 `LTTNG_SESSION_CONFIG_XSD_PATH`::
261 Tracing session configuration XML schema definition (XSD) path.
266 `$LTTNG_HOME/.lttng`::
267 User LTTng runtime and configuration directory.
269 `$LTTNG_HOME/lttng-traces`::
270 Default output directory of LTTng traces. This can be overridden
271 with the nloption:--output option of the man:lttng-create(1)
274 `$LTTNG_HOME/.lttng/sessions`::
275 Default location of saved user tracing sessions (see
276 man:lttng-save(1) and man:lttng-load(1)).
278 +{system_sessions_dir}+::
279 System-wide location of saved tracing sessions
280 (see man:lttng-save(1) and man:lttng-load(1)).
282 `$LTTNG_HOME/.lttng/lttng.conf`::
283 Default location of the session daemon configuration file (see the
284 option:--config option).
286 +{system_lttng_conf}+::
287 System-wide location of the session daemon configuration file (see
288 the option:--config option).
290 NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
307 For an unprivileged user running `lttng-sessiond`, the maximum number of
308 file descriptors per process is usually 1024. This limits the number of
309 traceable applications, since for each instrumented application, there
310 is two file descriptors per CPU and one more socket for bidirectional
313 For the root user, the limit is bumped to 65535. A future version will
314 deal with this limitation.
317 include::common-footer.txt[]