Commit | Line | Data |
---|---|---|
6991b181 DG |
1 | .TH "LTTNG-SESSIOND" "8" "January 31, 2012" "" "" |
2 | ||
3 | .SH "NAME" | |
c5db699c | 4 | lttng-sessiond \(em LTTng 2.x central tracing registry session daemon. |
6991b181 DG |
5 | |
6 | .SH "SYNOPSIS" | |
7 | ||
8 | .PP | |
9 | .nf | |
10 | lttng-sessiond [OPTIONS] | |
11 | .fi | |
12 | .SH "DESCRIPTION" | |
13 | ||
14 | .PP | |
15 | The LTTng project aims at providing highly efficient tracing tools for Linux. | |
16 | It's tracers help tracking down performance issues and debugging problems | |
17 | involving multiple concurrent processes and threads. Tracing across multiple | |
18 | systems is also possible. | |
19 | ||
fa072eae | 20 | The session daemon, acting as a tracing registry, allow you to interact with |
6991b181 DG |
21 | multiple tracers (kernel and user-space) inside the same container, a tracing |
22 | session. Trace can be gathered from the kernel and/or instrumented applications | |
95dc6256 | 23 | (lttng-ust(3)). Aggregating those traces is done using a viewer, like the |
fa072eae | 24 | babeltrace(1) text viewer. |
6991b181 DG |
25 | |
26 | In order to trace the kernel, the session daemon needs to be running as root. | |
27 | LTTng provides the use of a \fBtracing group\fP (default: tracing). Whomever is | |
28 | in that group can interact with the root session daemon and thus trace the | |
29 | kernel. Session daemons can co-exist meaning that you can have a session daemon | |
fa072eae YB |
30 | running as Alice that can be used to trace her applications along side with a |
31 | root daemon or even a Bob daemon. We highly recommend to start the session | |
6991b181 DG |
32 | daemon at boot time for stable and long term tracing. |
33 | ||
34 | The session daemon is in charge of managing trace data consumers by spawning | |
fa072eae | 35 | them when the time has come. The user don't need to manage the lttng-consumerd. |
6991b181 DG |
36 | .SH "OPTIONS" |
37 | ||
38 | .PP | |
39 | This program follow the usual GNU command line syntax with long options starting with | |
40 | two dashes. Below is a summary of the available options. | |
41 | .PP | |
42 | ||
43 | .TP | |
44 | .BR "-h, --help" | |
45 | Show summary of possible options and commands | |
46 | .TP | |
47 | .BR "-v, --verbose" | |
48 | Increase verbosity | |
49 | ||
50 | There is three debugging level which will print on stderr. Maximum verbosity is | |
51 | \fB-vvv\fP. | |
52 | .TP | |
53 | .BR " --verbose-consumer" | |
54 | Verbose mode for consumer. Activate DBG() macro. | |
55 | .TP | |
56 | .BR "-d, --daemonize" | |
57 | Start as a daemon | |
58 | .TP | |
72dd7491 MD |
59 | .BR "-b, --background" |
60 | Start as a daemon, keeping console open | |
61 | .TP | |
6991b181 DG |
62 | .BR "-g, --group=NAME" |
63 | Specify the tracing group name. (default: tracing) | |
64 | .TP | |
65 | .BR "-V, --version" | |
66 | Show version number | |
67 | .TP | |
68 | .BR "-S, --sig-parent" | |
7fe6d2c5 | 69 | Send SIGUSR1 to parent pid to notify readiness. |
6991b181 DG |
70 | |
71 | This is used by \fBlttng(1)\fP to get notified when the session daemon is ready | |
fa072eae | 72 | to accept command. When building a third party tool over liblttng-ctl, this option |
6991b181 DG |
73 | can be very handy to synchronize the control tool and the session daemon. |
74 | .TP | |
75 | .BR "-q, --quiet" | |
76 | No output at all. | |
77 | .TP | |
78 | .BR " --no-kernel" | |
79 | No kernel tracer support | |
80 | .TP | |
1b2ef7fe DG |
81 | .BR " --agent-tcp-port" |
82 | Agent application registration TCP port (default: 5345) | |
00e4a0a9 | 83 | .TP |
fbb9748b JG |
84 | .BR " --kmod-probes=probe1, probe2, ..." |
85 | Specify the kernel modules containing LTTng probes to load by the session daemon. | |
86 | Only the component name of the probe needs to be specified, e.g. to load the | |
87 | lttng-probe-irq and lttng-probe-sched use: --kmod-probes="irq, sched". | |
88 | .TP | |
6991b181 DG |
89 | .BR "-c, --client-sock=PATH" |
90 | Specify path for the client unix socket | |
91 | .TP | |
92 | .BR "-a, --apps-sock PATH" | |
93 | Specify path for apps unix socket | |
94 | .TP | |
95 | .BR " --kconsumerd-err-sock=PATH" | |
96 | Specify path for the kernel consumer error socket | |
97 | .TP | |
98 | .BR " --kconsumerd-cmd-sock=PATH | |
99 | Specify path for the kernel consumer command socket | |
100 | .TP | |
101 | .BR " --ustconsumerd32-err-sock=PATH | |
102 | Specify path for the 32-bit UST consumer error socket | |
103 | .TP | |
104 | .BR " --ustconsumerd64-err-sock=PATH | |
105 | Specify path for the 64-bit UST consumer error socket | |
106 | .TP | |
107 | .BR " --ustconsumerd32-cmd-sock=PATH | |
108 | Specify path for the 32-bit UST consumer command socket | |
109 | .TP | |
110 | .BR " --ustconsumerd64-cmd-sock=PATH | |
111 | Specify path for the 64-bit UST consumer command socket | |
112 | .TP | |
113 | .BR " --consumerd32-path=PATH | |
114 | Specify path for the 32-bit UST consumer daemon binary | |
115 | .TP | |
116 | .BR " --consumerd32-libdir=PATH | |
117 | Specify path for the 32-bit UST consumer daemon libraries | |
118 | .TP | |
119 | .BR " --consumerd64-path=PATH | |
120 | Specify path for the 64-bit UST consumer daemon binary | |
121 | .TP | |
122 | .BR " --consumerd64-libdir=PATH | |
123 | Specify path for the 64-bit UST consumer daemon libraries | |
6d601a32 JG |
124 | .TP |
125 | .BR "-l, --load PATH | |
bc68dab3 DG |
126 | Specify path from which to automatically load session configuration(s). |
127 | ||
128 | .SH "LOADING SESSIONS" | |
129 | ||
130 | .PP | |
131 | By default, the session daemon tries to load session configuration(s) located | |
132 | in the user default directory \fB~/.lttng/sessions/auto/\fP and in the system | |
cf53c06d | 133 | wide one in \fB/etc/lttng/sessions/auto/\fP. Note that the directory containing |
bc68dab3 DG |
134 | the session's configuration and lttng-sessiond MUST have the same UID for them |
135 | to be automatically loaded. | |
136 | ||
eb82f91d | 137 | Specifying a path with \-l, \-\-load PATH overrides the default directory and |
bc68dab3 DG |
138 | UID check. The lttng-sessiond will simply check if it's accessible and try to |
139 | load every session file in it. | |
140 | .PP | |
141 | ||
6991b181 DG |
142 | .SH "ENVIRONMENT VARIABLES" |
143 | ||
144 | .PP | |
fa072eae | 145 | Note that all command line options will override environment variables. |
6991b181 DG |
146 | .PP |
147 | ||
148 | .PP | |
149 | .IP "LTTNG_CONSUMERD32_BIN" | |
fa072eae | 150 | Specify the 32-bit consumer binary path. \fB--consumerd32-path\fP |
6991b181 DG |
151 | override this variable. |
152 | .IP "LTTNG_CONSUMERD64_BIN" | |
fa072eae | 153 | Specify the 64-bit consumer binary path. \fB--consumerd64-path\fP |
6991b181 DG |
154 | override this variable. |
155 | .IP "LTTNG_CONSUMERD32_LIBDIR" | |
eb82f91d | 156 | Specify the 64-bit library path containing libconsumer.so. |
6991b181 DG |
157 | \fB--consumerd32-libdir\fP override this variable. |
158 | .IP "LTTNG_CONSUMERD64_LIBDIR" | |
eb82f91d | 159 | Specify the 32-bit library path containing libconsumer.so. |
6991b181 | 160 | \fB--consumerd64-libdir\fP override this variable. |
2d85a600 MD |
161 | .IP "LTTNG_DEBUG_NOCLONE" |
162 | Debug-mode disabling use of clone/fork. Insecure, but required to allow | |
163 | debuggers to work with sessiond on some operating systems. | |
6be3d49a DG |
164 | .IP "LTTNG_APP_SOCKET_TIMEOUT" |
165 | Control the timeout of application's socket when sending and receiving | |
554831e7 MD |
166 | commands. Takes an integer parameter: the timeout value, in seconds. |
167 | After this period of time, the application is unregistered by the | |
168 | session daemon. A value of 0 or -1 means an infinite timeout. Default | |
169 | value is 5 seconds. | |
170 | .IP "LTTNG_NETWORK_SOCKET_TIMEOUT" | |
171 | Control timeout of socket connection, receive and send. Takes an integer | |
172 | parameter: the timeout value, in milliseconds. A value of 0 or -1 uses | |
173 | the timeout of the operating system (this is the default). | |
54e399cb JG |
174 | .IP "LTTNG_SESSION_CONFIG_XSD_PATH" |
175 | Specify the path that contains the XML session configuration schema (xsd). | |
fbb9748b JG |
176 | .IP "LTTNG_KMOD_PROBES" |
177 | Specify the kernel modules probes that should be loaded by the session daemon. | |
6991b181 DG |
178 | .SH "SEE ALSO" |
179 | ||
180 | .PP | |
181 | babeltrace(1), lttng-ust(3), lttng(1) | |
182 | .PP | |
95dc6256 DG |
183 | |
184 | .SH "LIMITATIONS" | |
185 | ||
186 | .PP | |
187 | For unprivileged user running lttng-sessiond, the maximum number of file | |
188 | descriptors per process is usually 1024. This limits the number of traceable | |
189 | applications since for each instrumented application there is two file | |
eb82f91d | 190 | descriptors per-CPU and one more socket for bidirectional communication. |
95dc6256 DG |
191 | |
192 | For the root user, the limit is bumped to 65535. Future version will deal with | |
193 | this limitation. | |
194 | .PP | |
195 | ||
6991b181 DG |
196 | .SH "BUGS" |
197 | ||
198 | .PP | |
fa072eae | 199 | No show stopper bugs are known yet in this version. |
6991b181 DG |
200 | |
201 | If you encounter any issues or usability problem, please report it on our | |
202 | mailing list <lttng-dev@lists.lttng.org> to help improve this project. | |
203 | .SH "CREDITS" | |
204 | ||
205 | .PP | |
c9e32613 | 206 | lttng-sessiond is distributed under the GNU General Public License version 2. See the |
6991b181 DG |
207 | file COPYING for details. |
208 | .PP | |
209 | A Web site is available at http://lttng.org for more information on the LTTng | |
210 | project. | |
211 | .PP | |
212 | You can also find our git tree at http://git.lttng.org. | |
213 | .PP | |
214 | Mailing lists for support and development: <lttng-dev@lists.lttng.org>. | |
215 | .PP | |
216 | You can find us on IRC server irc.oftc.net (OFTC) in #lttng. | |
217 | .PP | |
218 | .SH "THANKS" | |
219 | ||
220 | .PP | |
221 | Thanks to Yannick Brosseau without whom this project would never have been so | |
95dc6256 DG |
222 | lean and mean! Also thanks to the Ericsson teams working on tracing which helped |
223 | us greatly with detailed bug reports and unusual test cases. | |
6991b181 DG |
224 | |
225 | Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA | |
226 | maintainer) and Jon Bernard for our Debian packages. | |
227 | ||
228 | Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de | |
229 | Montreal for the LTTng journey. | |
c9e32613 | 230 | .PP |
6991b181 DG |
231 | .SH "AUTHORS" |
232 | ||
233 | .PP | |
234 | lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and | |
235 | David Goulet. More people have since contributed to it. It is currently | |
236 | maintained by David Goulet <dgoulet@efficios.com>. | |
237 | .PP |