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