.gitignore: add register-some-triggers trigger test utility
[lttng-tools.git] / doc / man / lttng-sessiond.8.txt
CommitLineData
ee717bf0
PP
1lttng-sessiond(8)
2=================
4605890e 3:revdate: 17 September 2018
ee717bf0
PP
4
5
6NAME
7----
8lttng-sessiond - LTTng 2 tracing session daemon
9
10
11SYNOPSIS
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']
761ffce2
FD
28 [option:--event-notifier-error-buffer-size-kernel='SIZE']
29 [option:--event-notifier-error-buffer-size-userspace='SIZE']
ee717bf0
PP
30 [option:--quiet | [option:-v | option:-vv | option:-vvv] [option:--verbose-consumer]]
31
32
33DESCRIPTION
34-----------
a18d9544 35The https://lttng.org/[_Linux Trace Toolkit: next generation_] is an open
ee717bf0
PP
36source software package used for correlated tracing of the Linux kernel,
37user applications, and user libraries.
38
39LTTng consists of Linux kernel modules (for Linux kernel tracing) and
40dynamically loaded libraries (for user application and library tracing).
41
42The _LTTng session daemon_ is a tracing registry which allows the user
43to interact with multiple tracers (kernel and user space) within the
44same container, a _tracing session_. Traces can be gathered from the
45Linux kernel and/or from instrumented applications (see
7c1a4458 46man:lttng-ust(3)). You can aggregate and read the events of LTTng
32357a9a 47traces using man:babeltrace2(1).
ee717bf0
PP
48
49To 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
51with the root session daemon. The default tracing group name is
52`tracing`. You can use the option:--group option to set the tracing
53group name to use.
54
55Session daemons can coexist. You can have a session daemon running as
56user Alice that can be used to trace her applications alongside a root
57session daemon or a session daemon running as user Bob.
58
59The LTTng session daemon manages trace data consumer daemons by spawning
60them when necessary. You do not need to manage the consumer daemons
61manually.
62
63NOTE: It is highly recommended to start the session daemon at boot time
64for stable and long-term tracing.
65
66
41c9a411
PP
67Automatic loading of tracing session configurations
68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69When the session daemon starts, it automatically loads session
70configuration files.
71
72The following directories are searched, non-recursively, in this order
73for configuration files to load on launch:
74
75. `$LTTNG_HOME/.lttng/sessions/auto` (`$LTTNG_HOME` defaults to `$HOME`)
76. +{system_sessions_auto_dir}+
77
ee717bf0 78Note that both the directory containing the tracing session
41c9a411 79configurations _and_ the session daemon binary _must_ share the same UID
ee717bf0
PP
80for the configurations to be automatically loaded.
81
41c9a411
PP
82The option:--load option overrides the default directories _and_ the UID
83check. The session daemon simply checks if the path is accessible and
84tries to load every tracing session configuration in it. When this
85option is specified, the default directories are :not: searched for
86configuration files. When the option is not specified, _both_ default
87directories are searched for configuration files.
88
89If the option:--load option's argument is a directory, then all the
90tracing session configurations found in all the files in this directory
91are loaded. If the argument is a file, then all the tracing session
92configurations found in this file are loaded.
ee717bf0
PP
93
94
95OPTIONS
96-------
97Daemon configuration
98~~~~~~~~~~~~~~~~~~~~
99option:-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
102 descriptors.
103
63e7895a 104option:-f 'PATH', option:--config='PATH'::
6a0e3480
PP
105 Load session daemon configuration from path 'PATH'.
106
ee717bf0
PP
107option:-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
110 open.
111
63e7895a 112option:-g 'GROUP', option:--group='GROUP'::
ee717bf0
PP
113 Use 'GROUP' as Unix tracing group (default: `tracing`).
114
63e7895a 115option:-l 'PATH', option:--load='PATH'::
41c9a411
PP
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.
ee717bf0
PP
119
120option:-S, option:--sig-parent::
121 Send `SIGUSR1` to parent process to notify readiness.
122+
7c1a4458 123NOTE: This is used by man:lttng(1) to get notified when the
ee717bf0
PP
124session daemon is ready to accept commands. When building a third party
125tool on liblttng-ctl, this option can be very handy to synchronize the
126control tool and the session daemon.
127
761ffce2
FD
128option:--event-notifier-error-buffer-size-kernel='SIZE'::
129 Set the size of the kernel event notifier error counter buffers to 'SIZE.
130
131option:--event-notifier-error-buffer-size-userspace='SIZE'::
132 Set the size of the userspace event notifier error counter buffers to
133 'SIZE.
134
ee717bf0
PP
135
136Linux kernel tracing
137~~~~~~~~~~~~~~~~~~~~
138option:--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.
142+
143Only the name of the probe needs to be specified, without the
144`lttng-probe-` prefix and without the kernel module extension suffix.
145For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
146module.
147
148option:--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).
151+
152Only the name of the probe needs to be specified, without the
153`lttng-probe-` prefix and without the kernel module extension suffix.
154For example, specify `sched` to load the `lttng-probe-sched.ko` kernel
155module.
156
157option:--no-kernel::
158 Disable Linux kernel tracing.
159
160
161Paths and ports
162~~~~~~~~~~~~~~~
163option:--agent-tcp-port='PORT'::
164 Listen on TCP port 'PORT' for agent application registrations
cb7d437c 165 (default: a port within the range
2288467f 166 [{default_agent_tcp_port_range_begin},{nbsp}{default_agent_tcp_port_range_end}]).
ee717bf0 167
59b19c3c 168option:-a 'PATH', option:--apps-sock='PATH'::
ee717bf0
PP
169 Set application Unix socket path to 'PATH'.
170
59b19c3c 171option:-c 'PATH', option:--client-sock='PATH'::
ee717bf0
PP
172 Set client Unix socket path to 'PATH'.
173
174option:--consumerd32-libdir='PATH'::
175 Set 32-bit consumer daemon library directory to 'PATH'.
176
177option:--consumerd32-path='PATH'::
178 Set 32-bit consumer daemon binary path to 'PATH'.
179
180option:--consumerd64-libdir='PATH'::
181 Set 64-bit consumer daemon library directory to 'PATH'.
182
183option:--consumerd64-path='PATH'::
184 Set 64-bit consumer daemon binary path to 'PATH'.
185
186option:--kconsumerd-cmd-sock='PATH'::
187 Set Linux kernel consumer daemon's command Unix socket path
188 to 'PATH'.
189
190option:--kconsumerd-err-sock='PATH'::
191 Set Linux kernel consumer daemon's error Unix socket path
192 to 'PATH'.
193
194option:--ustconsumerd32-cmd-sock='PATH'::
195 Set 32-bit consumer daemon's command Unix socket path to 'PATH'.
196
197option:--ustconsumerd64-cmd-sock='PATH'::
198 Set 64-bit consumer daemon's command Unix socket path to 'PATH'.
199
200option:--ustconsumerd32-err-sock='PATH'::
201 Set 32-bit consumer daemon's error Unix socket path to 'PATH'.
202
203option:--ustconsumerd64-err-sock='PATH'::
204 Set 64-bit consumer daemon's error Unix socket path to 'PATH'.
205
206
207Verbosity
208~~~~~~~~~
209option:-q, option:--quiet::
210 Suppress all messages, including warnings and errors.
211
212option:-v, option:--verbose::
213 Increase verbosity.
214+
215Three levels of verbosity are available, which are triggered by
216appending additional `v` letters to the option
217(that is, `-vv` and `-vvv`).
218
219option:--verbose-consumer::
220 Increase verbosity of consumer daemons spawned by this session
221 daemon.
222
223
224Program information
225~~~~~~~~~~~~~~~~~~~
226option:-h, option:--help::
227 Show help.
228
229option:-V, option:--version::
230 Show version.
231
232
233ENVIRONMENT VARIABLES
234---------------------
235Note that command-line options override their equivalent environment
236variable.
237
9bbd8e06
MD
238`LTTNG_ABORT_ON_ERROR`::
239 Set to 1 to abort the process after the first error is encountered.
240
ee717bf0
PP
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.
c93eadad 245 Default value: {default_app_socket_rw_timeout}.
ee717bf0
PP
246
247`LTTNG_CONSUMERD32_BIN`::
248 32-bit consumer daemon binary path.
249+
250The option:--consumerd32-path option overrides this variable.
251
252`LTTNG_CONSUMERD32_LIBDIR`::
253 32-bit consumer daemon library path.
254+
255The option:--consumerd32-libdir option overrides this variable.
256
257`LTTNG_CONSUMERD64_BIN`::
258 64-bit consumer daemon binary path.
259+
260The option:--consumerd64-path option overrides this variable.
261
262`LTTNG_CONSUMERD64_LIBDIR`::
263 64-bit consumer daemon library path.
264+
265The option:--consumerd64-libdir option overrides this variable.
266
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.
271
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.
276+
277The option:--extra-kmod-probes option overrides this variable.
278
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).
282+
283The option:--kmod-probes option overrides this variable.
284
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).
288
289`LTTNG_SESSION_CONFIG_XSD_PATH`::
290 Tracing session configuration XML schema definition (XSD) path.
291
292
900690ca
PP
293FILES
294-----
295`$LTTNG_HOME/.lttng`::
296 User LTTng runtime and configuration directory.
297
298`$LTTNG_HOME/lttng-traces`::
299 Default output directory of LTTng traces. This can be overridden
7c1a4458 300 with the nloption:--output option of the man:lttng-create(1)
900690ca
PP
301 command.
302
41c9a411
PP
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).
308
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).
900690ca
PP
314
315`$LTTNG_HOME/.lttng/lttng.conf`::
316 Default location of the session daemon configuration file (see the
317 option:--config option).
318
d8065e7e 319+{system_lttng_conf}+::
900690ca
PP
320 System-wide location of the session daemon configuration file (see
321 the option:--config option).
322
323NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set.
324
325
ee717bf0
PP
326EXIT STATUS
327-----------
328*0*::
329 Success
330
331*1*::
332 Error
333
334*3*::
335 Fatal error
336
337
338LIMITATIONS
339-----------
340For an unprivileged user running `lttng-sessiond`, the maximum number of
341file descriptors per process is usually 1024. This limits the number of
342traceable applications, since for each instrumented application, there
343is two file descriptors per CPU and one more socket for bidirectional
344communication.
345
346For the root user, the limit is bumped to 65535. A future version will
347deal with this limitation.
348
349
350include::common-footer.txt[]
351
352
353SEE ALSO
354--------
7c1a4458
PP
355man:lttng(1),
356man:lttng-relayd(8),
357man:lttng-crash(1),
358man:lttng-ust(3),
32357a9a 359man:babeltrace2(1)
This page took 0.069481 seconds and 4 git commands to generate.