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