Commit | Line | Data |
---|---|---|
ee717bf0 PP |
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 http://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 | |
7c1a4458 PP |
43 | man:lttng-ust(3)). You can aggregate and read the events of LTTng |
44 | traces using man:babeltrace(1). | |
ee717bf0 PP |
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 | ||
41c9a411 PP |
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 | ||
ee717bf0 | 75 | Note that both the directory containing the tracing session |
41c9a411 | 76 | configurations _and_ the session daemon binary _must_ share the same UID |
ee717bf0 PP |
77 | for the configurations to be automatically loaded. |
78 | ||
41c9a411 PP |
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. | |
ee717bf0 PP |
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':: | |
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 | |
117 | option:-S, option:--sig-parent:: | |
118 | Send `SIGUSR1` to parent process to notify readiness. | |
119 | + | |
7c1a4458 | 120 | NOTE: This is used by man:lttng(1) to get notified when the |
ee717bf0 PP |
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 | |
c93eadad | 155 | (default: {default_agent_tcp_port}). |
ee717bf0 | 156 | |
59b19c3c | 157 | option:-a 'PATH', option:--apps-sock='PATH':: |
ee717bf0 PP |
158 | Set application Unix socket path to 'PATH'. |
159 | ||
59b19c3c | 160 | option:-c 'PATH', option:--client-sock='PATH':: |
ee717bf0 PP |
161 | Set client Unix socket path to 'PATH'. |
162 | ||
163 | option:--consumerd32-libdir='PATH':: | |
164 | Set 32-bit consumer daemon library directory to 'PATH'. | |
165 | ||
166 | option:--consumerd32-path='PATH':: | |
167 | Set 32-bit consumer daemon binary path to 'PATH'. | |
168 | ||
169 | option:--consumerd64-libdir='PATH':: | |
170 | Set 64-bit consumer daemon library directory to 'PATH'. | |
171 | ||
172 | option:--consumerd64-path='PATH':: | |
173 | Set 64-bit consumer daemon binary path to 'PATH'. | |
174 | ||
175 | option:--kconsumerd-cmd-sock='PATH':: | |
176 | Set Linux kernel consumer daemon's command Unix socket path | |
177 | to 'PATH'. | |
178 | ||
179 | option:--kconsumerd-err-sock='PATH':: | |
180 | Set Linux kernel consumer daemon's error Unix socket path | |
181 | to 'PATH'. | |
182 | ||
183 | option:--ustconsumerd32-cmd-sock='PATH':: | |
184 | Set 32-bit consumer daemon's command Unix socket path to 'PATH'. | |
185 | ||
186 | option:--ustconsumerd64-cmd-sock='PATH':: | |
187 | Set 64-bit consumer daemon's command Unix socket path to 'PATH'. | |
188 | ||
189 | option:--ustconsumerd32-err-sock='PATH':: | |
190 | Set 32-bit consumer daemon's error Unix socket path to 'PATH'. | |
191 | ||
192 | option:--ustconsumerd64-err-sock='PATH':: | |
193 | Set 64-bit consumer daemon's error Unix socket path to 'PATH'. | |
194 | ||
195 | ||
196 | Verbosity | |
197 | ~~~~~~~~~ | |
198 | option:-q, option:--quiet:: | |
199 | Suppress all messages, including warnings and errors. | |
200 | ||
201 | option:-v, option:--verbose:: | |
202 | Increase verbosity. | |
203 | + | |
204 | Three levels of verbosity are available, which are triggered by | |
205 | appending additional `v` letters to the option | |
206 | (that is, `-vv` and `-vvv`). | |
207 | ||
208 | option:--verbose-consumer:: | |
209 | Increase verbosity of consumer daemons spawned by this session | |
210 | daemon. | |
211 | ||
212 | ||
213 | Program information | |
214 | ~~~~~~~~~~~~~~~~~~~ | |
215 | option:-h, option:--help:: | |
216 | Show help. | |
217 | ||
218 | option:-V, option:--version:: | |
219 | Show version. | |
220 | ||
221 | ||
222 | ENVIRONMENT VARIABLES | |
223 | --------------------- | |
224 | Note that command-line options override their equivalent environment | |
225 | variable. | |
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 | + | |
239 | The option:--consumerd32-path option overrides this variable. | |
240 | ||
241 | `LTTNG_CONSUMERD32_LIBDIR`:: | |
242 | 32-bit consumer daemon library path. | |
243 | + | |
244 | The option:--consumerd32-libdir option overrides this variable. | |
245 | ||
246 | `LTTNG_CONSUMERD64_BIN`:: | |
247 | 64-bit consumer daemon binary path. | |
248 | + | |
249 | The option:--consumerd64-path option overrides this variable. | |
250 | ||
251 | `LTTNG_CONSUMERD64_LIBDIR`:: | |
252 | 64-bit consumer daemon library path. | |
253 | + | |
254 | The 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 | + | |
266 | The 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 | + | |
272 | The 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 |
282 | FILES |
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 | ||
312 | NOTE: `$LTTNG_HOME` defaults to `$HOME` when not explicitly set. | |
313 | ||
314 | ||
ee717bf0 PP |
315 | EXIT STATUS |
316 | ----------- | |
317 | *0*:: | |
318 | Success | |
319 | ||
320 | *1*:: | |
321 | Error | |
322 | ||
323 | *3*:: | |
324 | Fatal error | |
325 | ||
326 | ||
327 | LIMITATIONS | |
328 | ----------- | |
329 | For an unprivileged user running `lttng-sessiond`, the maximum number of | |
330 | file descriptors per process is usually 1024. This limits the number of | |
331 | traceable applications, since for each instrumented application, there | |
332 | is two file descriptors per CPU and one more socket for bidirectional | |
333 | communication. | |
334 | ||
335 | For the root user, the limit is bumped to 65535. A future version will | |
336 | deal with this limitation. | |
337 | ||
338 | ||
339 | include::common-footer.txt[] | |
340 | ||
341 | ||
342 | SEE ALSO | |
343 | -------- | |
7c1a4458 PP |
344 | man:lttng(1), |
345 | man:lttng-relayd(8), | |
346 | man:lttng-crash(1), | |
347 | man:lttng-ust(3), | |
348 | man:babeltrace(1) |