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