lttng-sessiond(8)

1LTTNG-SESSIOND(8)                LTTng Manual                LTTNG-SESSIOND(8)
2
3
4

NAME

6       lttng-sessiond - LTTng session daemon
7

SYNOPSIS

9       lttng-sessiond [--background | --daemonize] [--sig-parent]
10                      [--config=PATH] [--group=GROUP] [--load=PATH]
11                      [--agent-tcp-port=PORT]
12                      [--apps-sock=PATH] [--client-sock=PATH]
13                      [--no-kernel | [--kmod-probes=PROBE[,PROBE]...]
14                                     [--extra-kmod-probes=PROBE[,PROBE]...]
15                                     [--kconsumerd-err-sock=PATH]
16                                     [--kconsumerd-cmd-sock=PATH]]
17                      [--ustconsumerd32-err-sock=PATH]
18                      [--ustconsumerd64-err-sock=PATH]
19                      [--ustconsumerd32-cmd-sock=PATH]
20                      [--ustconsumerd64-cmd-sock=PATH]
21                      [--consumerd32-path=PATH] [--consumerd32-libdir=PATH]
22                      [--consumerd64-path=PATH] [--consumerd64-libdir=PATH]
23                      [--event-notifier-error-buffer-size-kernel=SLOTS]
24                      [--event-notifier-error-buffer-size-userspace=SLOTS]
25                      [--quiet | [--verbose]... [--verbose-consumer]]
26

DESCRIPTION

28       The Linux Trace Toolkit: next generation <https://lttng.org/> is an
29       open-source software package used for correlated tracing of the Linux
30       kernel, user applications, and user libraries.
31
32       LTTng consists of Linux kernel modules (for Linux kernel tracing) and
33       dynamically loaded libraries (for user application and library
34       tracing).
35
36       An LTTng session daemon, lttng-sessiond, is a program which:
37
38       •   Manages recording sessions (see lttng-concepts(7) to learn more
39           about recording sessions).
40
41       •   Controls the various components (like tracers and consumer daemons)
42           of LTTng.
43
44       •   Sends asynchronous notifications to user applications.
45
46       A session daemon receives commands from the lttng(1) command-line tool,
47       as well as from any user application linked with the LTTng control
48       library (liblttng-ctl).
49
50       Each Unix user may have its own independent running session daemon.
51       However, the lttng(1) tool must connect to the session daemon of the
52       root user (the root session daemon) to control Linux kernel tracing.
53
54       When you start lttng-sessiond as the root Unix user, a non-root Unix
55       user can connect to it if it’s part of the Unix tracing group. By
56       default, the name of the tracing group is tracing. Override the tracing
57       group name with the --group option.
58
59       See the “Session daemon connection” section of lttng(1) to learn how a
60       user application connects to a session daemon.
61
62       A session daemon manages trace data consumer daemons, spawning them
63       when necessary. You do NOT need to manage the consumer daemons
64       yourself.
65
66       By default, lttng-sessiond doesn’t start as a daemon. Make it a daemon
67       with the --daemonize or --background option. With those options, lttng-
68       sessiond ensures the daemon is ready to receive client commands before
69       it exits.
70
71       Note
72           The LTTng project recommends that you start the session daemon at
73           boot time for stable and long-term tracing.
74
75       Note
76           For an unprivileged Unix user running lttng-sessiond, the maximum
77           number of file descriptors per process is usually 1024. This limits
78           the number of traceable applications, since, for each instrumented
79           application, there are two file descriptors per CPU as well as one
80           socket for bidirectional communication.
81
82           For the root user, the limit is usually 65,535.
83
84   Daemon configuration
85       When you run lttng-sessiond, it configures itself from, in this order:
86
87        1. The INI configuration file /usr/local/etc/lttng/lttng.conf, if any.
88
89        2. The INI configuration file $LTTNG_HOME/.lttng/lttng.conf, if any.
90
91           $LTTNG_HOME defaults to $HOME.
92
93        3. With the --config=PATH option: the INI configuration file PATH.
94
95        4. The command-line options.
96
97       Each step can override a previous configuration property.
98
99       In INI configuration files, the session daemon only reads the
100       properties under the sessiond INI section. Each INI property is:
101
102       Key
103           The long name of a command-line option to set (see the “OPTIONS”
104           section below).
105
106       Value
107
108           The selected command-line option accepts an argument
109               Option argument (string).
110
111           The selected command-line option is a switch
112
113               true, yes, on
114                   Enable the option.
115
116               false, no, off
117                   Disable the option.
118
119       INI configuration file example:
120
121           [sessiond]
122           daemonize=yes
123           extra-kmod-probes=my-driver,other-module
124
125   Recording session configuration loading
126       When the session daemon starts, it loads recording session
127       configurations from:
128
129       Without the --load option
130           In this order:
131
132            1. All the files in $LTTNG_HOME/.lttng/sessions/auto.
133
134               $LTTNG_HOME defaults to $HOME.
135
136            2. All the files in /usr/local/etc/lttng/sessions/auto.
137
138           lttng-sessiond only loads recording session configuration files
139           from the directories above if its UID and their UID are the same.
140
141       With the --load=PATH option
142
143           PATH is a directory
144               All the files in PATH.
145
146           PATH is a file
147               The file PATH.
148

OPTIONS

150   General daemon configuration
151       -b, --background
152           Start as a Unix daemon, but keep file descriptors (console) open.
153
154           With this option, lttng-sessiond ensures the daemon is ready to
155           receive client commands before it exits.
156
157           Use the --daemonize option instead to close the file descriptors.
158
159       -f PATH, --config=PATH
160           Configure the daemon using the INI configuration file PATH in
161           addition to the default configuration files and the command-line
162           options.
163
164           See the “Daemon configuration” section above.
165
166       -d, --daemonize
167           Start as a Unix daemon and close file descriptors (console).
168
169           With this option, lttng-sessiond ensures the daemon is ready to
170           receive client commands before it exits.
171
172           Use the --background option instead to keep the file descriptors
173           open.
174
175       -g GROUP, --group=GROUP
176           Set the Unix tracing group to GROUP instead of tracing.
177
178           This option is only meaningful when the root Unix user starts
179           lttng-sessiond.
180
181           Members of the Unix tracing group may connect to the root session
182           daemon and, therefore, control LTTng kernel tracing.
183
184       -l PATH, --load=PATH
185           Load recording session configurations from PATH, either a directory
186           or a file, instead of loading them from the default search
187           directories.
188
189           See the “Recording session configuration loading” section above.
190
191       -S, --sig-parent
192           Send the USR1 signal to the parent process to notify readiness.
193
194           You can also use the --daemonize or --background option, in which
195           case lttng-sessiond ensures the daemon is ready to receive client
196           commands before it exits.
197
198   Linux kernel tracing
199       At most one of:
200
201       --extra-kmod-probes=PROBE[,PROBE]...
202           For each PROBE argument, load the LTTng kernel probe module named
203           lttng-probe-PROBE.ko, in addition to loading the default LTTng
204           kernel probe modules.
205
206           See also the LTTNG_EXTRA_KMOD_PROBES environment variable.
207
208       --kmod-probes=PROBE[,PROBE]...
209           Only load, for each PROBE argument, the LTTng kernel probe module
210           named lttng-probe-PROBE.ko, instead of loading the default LTTng
211           kernel probe modules.
212
213           See also the LTTNG_KMOD_PROBES environment variable.
214
215       --no-kernel
216           Disable Linux kernel tracing.
217
218   Paths and ports
219       --agent-tcp-port=PORT
220           Listen on TCP port PORT for agent application registration instead
221           of a port within the range [5345, 5354]).
222
223       -a PATH, --apps-sock=PATH
224           Set the application Unix socket path to PATH.
225
226       -c PATH, --client-sock=PATH
227           Set the client Unix socket path to PATH.
228
229       --consumerd32-libdir=PATH
230           Set the 32-bit consumer daemon library directory to PATH.
231
232           See also the LTTNG_CONSUMERD32_LIBDIR environment variable.
233
234       --consumerd32-path=PATH
235           Set the 32-bit consumer daemon binary path to PATH.
236
237           See also the LTTNG_CONSUMERD32_BIN environment variable.
238
239       --consumerd64-libdir=PATH
240           Set the 64-bit consumer daemon library directory to PATH.
241
242           See also the LTTNG_CONSUMERD64_LIBDIR environment variable.
243
244       --consumerd64-path=PATH
245           Set the 64-bit consumer daemon binary path to PATH.
246
247           See also the LTTNG_CONSUMERD32_BIN environment variable.
248
249       --kconsumerd-cmd-sock=PATH
250           Set the command Unix socket path of the Linux kernel consumer
251           daemon to PATH.
252
253       --kconsumerd-err-sock=PATH
254           Set the error Unix socket path of the Linux kernel consumer daemon
255           to PATH.
256
257       --ustconsumerd32-cmd-sock=PATH
258           Set the Unix socket path of the 32-bit consumer daemon command to
259           PATH.
260
261       --ustconsumerd64-cmd-sock=PATH
262           Set the Unix socket path of the 64-bit consumer daemon command to
263           PATH.
264
265       --ustconsumerd32-err-sock=PATH
266           Set the Unix socket path of the 32-bit consumer daemon error to
267           PATH.
268
269       --ustconsumerd64-err-sock=PATH
270           Set the Unix socket path of the 64-bit consumer daemon error to
271           PATH.
272
273   Buffer size of event notifier error counters
274       --event-notifier-error-buffer-size-kernel=SLOTS
275           Set the size of the kernel event notifier error counter buffers to
276           SLOTS slots.
277
278       --event-notifier-error-buffer-size-userspace=SLOTS
279           Set the size of the user space event notifier error counter buffers
280           to SLOTS slots.
281
282       As of LTTng 2.13.7, a slot is a 32-bit counter, but this may change in
283       the future.
284
285   Verbosity
286       -q, --quiet
287           Suppress all messages, including warnings and errors.
288
289           You may NOT use this option with the --verbose and --verbose-
290           consumer options.
291
292       -v, --verbose
293           Increase verbosity.
294
295           Specify this option up to three times to get more levels of
296           verbosity.
297
298           You may NOT use this option with the --quiet option.
299
300       --verbose-consumer
301           Increase the verbosity of the consumer daemons which this session
302           daemon spawns.
303
304           You may NOT use this option with the --quiet option.
305
306   Program information
307       -h, --help
308           Show help.
309
310           This option attempts to launch /usr/bin/man to view this manual
311           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
312           environment variable.
313
314       --list-options
315           List available command options and quit.
316
317       -V, --version
318           Show version and quit.
319

EXIT STATUS

321       0
322           Success
323
324       1
325           Error
326
327       3
328           Fatal error
329

ENVIRONMENT

331       LTTNG_ABORT_ON_ERROR
332           Set to 1 to abort the process after the first error is encountered.
333
334       LTTNG_APP_SOCKET_TIMEOUT
335           Timeout (in seconds) of the application socket when
336           sending/receiving commands.
337
338           After this period of time, lttng-sessiond unregisters the
339           application.
340
341           Set to 0 or -1 to set an infinite timeout.
342
343           Default: 5.
344
345       LTTNG_CONSUMERD32_BIN
346           32-bit consumer daemon binary path.
347
348           The --consumerd32-path option overrides this environment variable.
349
350       LTTNG_CONSUMERD32_LIBDIR
351           32-bit consumer daemon library directory path.
352
353           The --consumerd32-libdir option overrides this environment
354           variable.
355
356       LTTNG_CONSUMERD64_BIN
357           64-bit consumer daemon binary path.
358
359           The --consumerd64-path option overrides this environment variable.
360
361       LTTNG_CONSUMERD64_LIBDIR
362           64-bit consumer daemon library directory path.
363
364           The --consumerd64-libdir option overrides this environment
365           variable.
366
367       LTTNG_DEBUG_NOCLONE
368           Set to 1 to disable the use of clone(2)/fork(2).
369
370           Setting this environment variable is considered insecure, but it’s
371           required to allow debuggers to work with lttng-sessiond on some
372           operating systems.
373
374       LTTNG_EXTRA_KMOD_PROBES
375           Extra LTTng kernel probe modules to load.
376
377           See the --extra-kmod-probes option which overrides this environment
378           variable.
379
380       LTTNG_KMOD_PROBES
381           Exclusive LTTng kernel probe modules to load.
382
383           See the --kmod-probes option which overrides this environment
384           variable.
385
386       LTTNG_NETWORK_SOCKET_TIMEOUT
387           Socket connection, receive, and send timeout (milliseconds).
388
389           Set to 0 or -1 to use the timeout of the operating system
390           (default).
391
392       LTTNG_SESSION_CONFIG_XSD_PATH
393           Recording session configuration XML schema definition (XSD) path.
394

FILES

396       $LTTNG_HOME/.lttng
397           Unix user’s LTTng runtime and configuration directory.
398
399       $LTTNG_HOME/lttng-traces
400           Default output directory of LTTng traces in local and snapshot
401           modes.
402
403           Override this path with the --output option of the lttng-create(1)
404           command.
405
406       $LTTNG_HOME/.lttng/sessions/auto
407           Directory from which lttng-sessiond loads Unix user recording
408           session configurations when starting.
409
410           See the “Recording session configuration loading” section above to
411           learn more.
412
413       /usr/local/etc/lttng/sessions/auto
414           Directory from which lttng-sessiond loads system-wide recording
415           session configurations when starting.
416
417           See the “Recording session configuration loading” section above to
418           learn more.
419
420       $LTTNG_HOME/.lttng/lttng.conf
421           Unix user’s LTTng daemon INI configuration file.
422
423           See the “Daemon configuration” section above to learn more.
424
425       /usr/local/etc/lttng/lttng.conf
426           System-wide LTTng daemon INI configuration file.
427
428           See the “Daemon configuration” section above to learn more.
429
430       Note
431           $LTTNG_HOME defaults to $HOME.
432

RESOURCES

434       •   LTTng project website <https://lttng.org>
435
436       •   LTTng documentation <https://lttng.org/docs>
437
438       •   LTTng bug tracker <https://bugs.lttng.org>
439
440       •   Git repositories <https://git.lttng.org>
441
442       •   GitHub organization <https://github.com/lttng>
443
444       •   Continuous integration <https://ci.lttng.org/>
445
446       •   Mailing list <https://lists.lttng.org/> for support and
447           development: lttng-dev@lists.lttng.org
448
449       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
450

COPYRIGHT

452       This program is part of the LTTng-tools project.
453
454       LTTng-tools is distributed under the GNU General Public License
455       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
456       See the LICENSE <https://github.com/lttng/lttng-
457       tools/blob/master/LICENSE> file for details.
458

THANKS

460       Special thanks to Michel Dagenais and the DORSAL laboratory
461       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
462       the LTTng journey.
463
464       Also thanks to the Ericsson teams working on tracing which helped us
465       greatly with detailed bug reports and unusual test cases.
466