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

NAME

6       lttng-sessiond - LTTng 2 tracing 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                      [--quiet | [-v | -vv | -vvv] [--verbose-consumer]]
24

DESCRIPTION

26       The Linux Trace Toolkit: next generation <https://lttng.org/> is an
27       open source software package used for correlated tracing of the Linux
28       kernel, user applications, and user libraries.
29
30       LTTng consists of Linux kernel modules (for Linux kernel tracing) and
31       dynamically loaded libraries (for user application and library
32       tracing).
33
34       The LTTng session daemon is a tracing registry which allows the user to
35       interact with multiple tracers (kernel and user space) within the same
36       container, a tracing session. Traces can be gathered from the Linux
37       kernel and/or from instrumented applications (see lttng-ust(3)). You
38       can aggregate and read the events of LTTng traces using babeltrace2(1).
39
40       To trace the Linux kernel, the session daemon needs to be running as
41       root. LTTng uses a tracing group to allow specific users to interact
42       with the root session daemon. The default tracing group name is
43       tracing. You can use the --group option to set the tracing group name
44       to use.
45
46       Session daemons can coexist. You can have a session daemon running as
47       user Alice that can be used to trace her applications alongside a root
48       session daemon or a session daemon running as user Bob.
49
50       The LTTng session daemon manages trace data consumer daemons by
51       spawning them when necessary. You do not need to manage the consumer
52       daemons manually.
53
54           Note
55           It is highly recommended to start the session daemon at boot time
56           for stable and long-term tracing.
57
58   Automatic loading of tracing session configurations
59       When the session daemon starts, it automatically loads session
60       configuration files.
61
62       The following directories are searched, non-recursively, in this order
63       for configuration files to load on launch:
64
65        1. $LTTNG_HOME/.lttng/sessions/auto ($LTTNG_HOME defaults to $HOME)
66
67        2. /usr/local/etc/lttng/sessions/auto
68
69       Note that both the directory containing the tracing session
70       configurations and the session daemon binary must share the same UID
71       for the configurations to be automatically loaded.
72
73       The --load option overrides the default directories and the UID check.
74       The session daemon simply checks if the path is accessible and tries to
75       load every tracing session configuration in it. When this option is
76       specified, the default directories are NOT searched for configuration
77       files. When the option is not specified, both default directories are
78       searched for configuration files.
79
80       If the --load option’s argument is a directory, then all the tracing
81       session configurations found in all the files in this directory are
82       loaded. If the argument is a file, then all the tracing session
83       configurations found in this file are loaded.
84

OPTIONS

86   Daemon configuration
87       -b, --background
88           Start as Unix daemon, but keep file descriptors (console) open. Use
89           the --daemonize option instead to close the file descriptors.
90
91       -f PATH, --config=PATH
92           Load session daemon configuration from path PATH.
93
94       -d, --daemonize
95           Start as Unix daemon, and close file descriptors (console). Use the
96           --background option instead to keep the file descriptors open.
97
98       -g GROUP, --group=GROUP
99           Use GROUP as Unix tracing group (default: tracing).
100
101       -l PATH, --load=PATH
102           Automatically load tracing session configurations from PATH, either
103           a directory or a file, instead of loading them from the default
104           search directories.
105
106       -S, --sig-parent
107           Send SIGUSR1 to parent process to notify readiness.
108
109               Note
110               This is used by lttng(1) to get notified when the session
111               daemon is ready to accept commands. When building a third party
112               tool on liblttng-ctl, this option can be very handy to
113               synchronize the control tool and the session daemon.
114
115   Linux kernel tracing
116       --extra-kmod-probes=PROBE[,PROBE]...
117           Load specific LTTng Linux kernel modules when kernel tracing is
118           enabled (--no-kernel option is NOT specified), in addition to
119           loading the default list of LTTng kernel modules.
120
121           Only the name of the probe needs to be specified, without the
122           lttng-probe- prefix and without the kernel module extension suffix.
123           For example, specify sched to load the lttng-probe-sched.ko kernel
124           module.
125
126       --kmod-probes=PROBE[,PROBE]...
127           Only load specific LTTng Linux kernel modules when kernel tracing
128           is enabled (--no-kernel option is NOT specified).
129
130           Only the name of the probe needs to be specified, without the
131           lttng-probe- prefix and without the kernel module extension suffix.
132           For example, specify sched to load the lttng-probe-sched.ko kernel
133           module.
134
135       --no-kernel
136           Disable Linux kernel tracing.
137
138   Paths and ports
139       --agent-tcp-port=PORT
140           Listen on TCP port PORT for agent application registrations
141           (default: a port within the range [5345, 5354]).
142
143       -a PATH, --apps-sock=PATH
144           Set application Unix socket path to PATH.
145
146       -c PATH, --client-sock=PATH
147           Set client Unix socket path to PATH.
148
149       --consumerd32-libdir=PATH
150           Set 32-bit consumer daemon library directory to PATH.
151
152       --consumerd32-path=PATH
153           Set 32-bit consumer daemon binary path to PATH.
154
155       --consumerd64-libdir=PATH
156           Set 64-bit consumer daemon library directory to PATH.
157
158       --consumerd64-path=PATH
159           Set 64-bit consumer daemon binary path to PATH.
160
161       --kconsumerd-cmd-sock=PATH
162           Set Linux kernel consumer daemon’s command Unix socket path to
163           PATH.
164
165       --kconsumerd-err-sock=PATH
166           Set Linux kernel consumer daemon’s error Unix socket path to PATH.
167
168       --ustconsumerd32-cmd-sock=PATH
169           Set 32-bit consumer daemon’s command Unix socket path to PATH.
170
171       --ustconsumerd64-cmd-sock=PATH
172           Set 64-bit consumer daemon’s command Unix socket path to PATH.
173
174       --ustconsumerd32-err-sock=PATH
175           Set 32-bit consumer daemon’s error Unix socket path to PATH.
176
177       --ustconsumerd64-err-sock=PATH
178           Set 64-bit consumer daemon’s error Unix socket path to PATH.
179
180   Verbosity
181       -q, --quiet
182           Suppress all messages, including warnings and errors.
183
184       -v, --verbose
185           Increase verbosity.
186
187           Three levels of verbosity are available, which are triggered by
188           appending additional v letters to the option (that is, -vv and
189           -vvv).
190
191       --verbose-consumer
192           Increase verbosity of consumer daemons spawned by this session
193           daemon.
194
195   Program information
196       -h, --help
197           Show help.
198
199       -V, --version
200           Show version.
201

ENVIRONMENT VARIABLES

203       Note that command-line options override their equivalent environment
204       variable.
205
206       LTTNG_ABORT_ON_ERROR
207           Set to 1 to abort the process after the first error is encountered.
208
209       LTTNG_APP_SOCKET_TIMEOUT
210           Application socket’s timeout (seconds) when sending/receiving
211           commands. After this period of time, the application is
212           unregistered by the session daemon. A value of 0 or -1 means an
213           infinite timeout. Default value: 5.
214
215       LTTNG_CONSUMERD32_BIN
216           32-bit consumer daemon binary path.
217
218           The --consumerd32-path option overrides this variable.
219
220       LTTNG_CONSUMERD32_LIBDIR
221           32-bit consumer daemon library path.
222
223           The --consumerd32-libdir option overrides this variable.
224
225       LTTNG_CONSUMERD64_BIN
226           64-bit consumer daemon binary path.
227
228           The --consumerd64-path option overrides this variable.
229
230       LTTNG_CONSUMERD64_LIBDIR
231           64-bit consumer daemon library path.
232
233           The --consumerd64-libdir option overrides this variable.
234
235       LTTNG_DEBUG_NOCLONE
236           Set to 1 to disable the use of clone()/fork(). Setting this
237           variable is considered insecure, but it is required to allow
238           debuggers to work with the session daemon on some operating
239           systems.
240
241       LTTNG_EXTRA_KMOD_PROBES
242           Load specific LTTng Linux kernel modules when kernel tracing is
243           enabled (--no-kernel option is NOT specified), in addition to
244           loading the default list of LTTng kernel modules.
245
246           The --extra-kmod-probes option overrides this variable.
247
248       LTTNG_KMOD_PROBES
249           Only load specific LTTng Linux kernel modules when kernel tracing
250           is enabled (--no-kernel option is NOT specified).
251
252           The --kmod-probes option overrides this variable.
253
254       LTTNG_NETWORK_SOCKET_TIMEOUT
255           Socket connection, receive and send timeout (milliseconds). A value
256           of 0 or -1 uses the timeout of the operating system (default).
257
258       LTTNG_SESSION_CONFIG_XSD_PATH
259           Tracing session configuration XML schema definition (XSD) path.
260

FILES

262       $LTTNG_HOME/.lttng
263           User LTTng runtime and configuration directory.
264
265       $LTTNG_HOME/lttng-traces
266           Default output directory of LTTng traces. This can be overridden
267           with the --output option of the lttng-create(1) command.
268
269       $LTTNG_HOME/.lttng/sessions/auto
270           Directory from which user tracing configuration files are
271           automatically loaded when the session daemon starts (see lttng-
272           save(1) and lttng-load(1) for saving and loading tracing sessions).
273
274       /usr/local/etc/lttng/sessions/auto
275           Directory from which system-wide tracing configuration files are
276           automatically loaded when the session daemon starts (see lttng-
277           save(1) and lttng-load(1) for saving and loading tracing sessions).
278
279       $LTTNG_HOME/.lttng/lttng.conf
280           Default location of the session daemon configuration file (see the
281           --config option).
282
283       /usr/local/etc/lttng/lttng.conf
284           System-wide location of the session daemon configuration file (see
285           the --config option).
286
287           Note
288           $LTTNG_HOME defaults to $HOME when not explicitly set.
289

EXIT STATUS

291       0
292           Success
293
294       1
295           Error
296
297       3
298           Fatal error
299

LIMITATIONS

301       For an unprivileged user running lttng-sessiond, the maximum number of
302       file descriptors per process is usually 1024. This limits the number of
303       traceable applications, since for each instrumented application, there
304       is two file descriptors per CPU and one more socket for bidirectional
305       communication.
306
307       For the root user, the limit is bumped to 65535. A future version will
308       deal with this limitation.
309

BUGS

311       If you encounter any issue or usability problem, please report it on
312       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
313

RESOURCES

315       ·   LTTng project website <https://lttng.org>
316
317       ·   LTTng documentation <https://lttng.org/docs>
318
319       ·   Git repositories <http://git.lttng.org>
320
321       ·   GitHub organization <http://github.com/lttng>
322
323       ·   Continuous integration <http://ci.lttng.org/>
324
325       ·   Mailing list <http://lists.lttng.org> for support and development:
326           lttng-dev@lists.lttng.org
327
328       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
329

COPYRIGHTS

331       This program is part of the LTTng-tools project.
332
333       LTTng-tools is distributed under the GNU General Public License version
334       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
335       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
336       for details.
337

THANKS

339       Special thanks to Michel Dagenais and the DORSAL laboratory
340       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
341       the LTTng journey.
342
343       Also thanks to the Ericsson teams working on tracing which helped us
344       greatly with detailed bug reports and unusual test cases.
345

SEE ALSO

347       lttng(1), lttng-relayd(8), lttng-crash(1), lttng-ust(3), babeltrace2(1)
348
349
350
351LTTng 2.12.2                   17 September 2018             LTTNG-SESSIOND(8)
Impressum