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