| 1 | .TH "LTTNG-SESSIOND" "8" "January 31, 2012" "" "" |
| 2 | |
| 3 | .SH "NAME" |
| 4 | lttng-sessiond \(em LTTng 2.x central tracing registry session daemon. |
| 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 | |
| 20 | The session daemon, acting as a tracing registry, allow you to interact with |
| 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 |
| 23 | (lttng-ust(3)). Aggregating those traces is done using a viewer, like the |
| 24 | babeltrace(1) text viewer. |
| 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 |
| 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 |
| 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 |
| 35 | them when the time has come. The user don't need to manage the lttng-consumerd. |
| 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 |
| 59 | .BR "-b, --background" |
| 60 | Start as a daemon, keeping console open |
| 61 | .TP |
| 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" |
| 69 | Send SIGUSR1 to parent pid to notify readiness. |
| 70 | |
| 71 | This is used by \fBlttng(1)\fP to get notified when the session daemon is ready |
| 72 | to accept command. When building a third party tool over liblttng-ctl, this option |
| 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 |
| 81 | .BR " --agent-tcp-port" |
| 82 | Agent application registration TCP port (default: 5345) |
| 83 | .TP |
| 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 |
| 89 | .BR " --extra-kmod-probes=probe1, probe2, ..." |
| 90 | Specify extra kernel modules containing LTTng probes to be loaded by the session |
| 91 | daemon. The list follows the format of the \fB--kmod-probes\fP option. |
| 92 | This list is appended to the list provided by \fB--kmod-probes\fP or, if |
| 93 | \fB--kmod-probes\fP is missing, to the default list of probes. |
| 94 | .TP |
| 95 | .BR "-c, --client-sock=PATH" |
| 96 | Specify path for the client unix socket |
| 97 | .TP |
| 98 | .BR "-a, --apps-sock PATH" |
| 99 | Specify path for apps unix socket |
| 100 | .TP |
| 101 | .BR " --kconsumerd-err-sock=PATH" |
| 102 | Specify path for the kernel consumer error socket |
| 103 | .TP |
| 104 | .BR " --kconsumerd-cmd-sock=PATH |
| 105 | Specify path for the kernel consumer command socket |
| 106 | .TP |
| 107 | .BR " --ustconsumerd32-err-sock=PATH |
| 108 | Specify path for the 32-bit UST consumer error socket |
| 109 | .TP |
| 110 | .BR " --ustconsumerd64-err-sock=PATH |
| 111 | Specify path for the 64-bit UST consumer error socket |
| 112 | .TP |
| 113 | .BR " --ustconsumerd32-cmd-sock=PATH |
| 114 | Specify path for the 32-bit UST consumer command socket |
| 115 | .TP |
| 116 | .BR " --ustconsumerd64-cmd-sock=PATH |
| 117 | Specify path for the 64-bit UST consumer command socket |
| 118 | .TP |
| 119 | .BR " --consumerd32-path=PATH |
| 120 | Specify path for the 32-bit UST consumer daemon binary |
| 121 | .TP |
| 122 | .BR " --consumerd32-libdir=PATH |
| 123 | Specify path for the 32-bit UST consumer daemon libraries |
| 124 | .TP |
| 125 | .BR " --consumerd64-path=PATH |
| 126 | Specify path for the 64-bit UST consumer daemon binary |
| 127 | .TP |
| 128 | .BR " --consumerd64-libdir=PATH |
| 129 | Specify path for the 64-bit UST consumer daemon libraries |
| 130 | .TP |
| 131 | .BR "-l, --load PATH |
| 132 | Specify path from which to automatically load session configuration(s). |
| 133 | |
| 134 | .SH "LOADING SESSIONS" |
| 135 | |
| 136 | .PP |
| 137 | By default, the session daemon tries to load session configuration(s) located |
| 138 | in the user default directory \fB~/.lttng/sessions/auto/\fP and in the system |
| 139 | wide one in \fB/etc/lttng/sessions/auto/\fP. Note that the directory containing |
| 140 | the session's configuration and lttng-sessiond MUST have the same UID for them |
| 141 | to be automatically loaded. |
| 142 | |
| 143 | Specifying a path with \-l, \-\-load PATH overrides the default directory and |
| 144 | UID check. The lttng-sessiond will simply check if it's accessible and try to |
| 145 | load every session file in it. |
| 146 | .PP |
| 147 | |
| 148 | .SH "ENVIRONMENT VARIABLES" |
| 149 | |
| 150 | .PP |
| 151 | Note that all command line options will override environment variables. |
| 152 | .PP |
| 153 | |
| 154 | .PP |
| 155 | .IP "LTTNG_CONSUMERD32_BIN" |
| 156 | Specify the 32-bit consumer binary path. \fB--consumerd32-path\fP |
| 157 | override this variable. |
| 158 | .IP "LTTNG_CONSUMERD64_BIN" |
| 159 | Specify the 64-bit consumer binary path. \fB--consumerd64-path\fP |
| 160 | override this variable. |
| 161 | .IP "LTTNG_CONSUMERD32_LIBDIR" |
| 162 | Specify the 64-bit library path containing libconsumer.so. |
| 163 | \fB--consumerd32-libdir\fP override this variable. |
| 164 | .IP "LTTNG_CONSUMERD64_LIBDIR" |
| 165 | Specify the 32-bit library path containing libconsumer.so. |
| 166 | \fB--consumerd64-libdir\fP override this variable. |
| 167 | .IP "LTTNG_DEBUG_NOCLONE" |
| 168 | Debug-mode disabling use of clone/fork. Insecure, but required to allow |
| 169 | debuggers to work with sessiond on some operating systems. |
| 170 | .IP "LTTNG_APP_SOCKET_TIMEOUT" |
| 171 | Control the timeout of application's socket when sending and receiving |
| 172 | commands. Takes an integer parameter: the timeout value, in seconds. |
| 173 | After this period of time, the application is unregistered by the |
| 174 | session daemon. A value of 0 or -1 means an infinite timeout. Default |
| 175 | value is 5 seconds. |
| 176 | .IP "LTTNG_NETWORK_SOCKET_TIMEOUT" |
| 177 | Control timeout of socket connection, receive and send. Takes an integer |
| 178 | parameter: the timeout value, in milliseconds. A value of 0 or -1 uses |
| 179 | the timeout of the operating system (this is the default). |
| 180 | .IP "LTTNG_SESSION_CONFIG_XSD_PATH" |
| 181 | Specify the path that contains the XML session configuration schema (xsd). |
| 182 | .IP "LTTNG_KMOD_PROBES" |
| 183 | Specify the kernel modules probes that should be loaded by the session daemon. |
| 184 | .IP "LTTNG_EXTRA_KMOD_PROBES" |
| 185 | Specify extra kernel modules probes that should be loaded by the session daemon. |
| 186 | .SH "SEE ALSO" |
| 187 | |
| 188 | .PP |
| 189 | babeltrace(1), lttng-ust(3), lttng(1) |
| 190 | .PP |
| 191 | |
| 192 | .SH "LIMITATIONS" |
| 193 | |
| 194 | .PP |
| 195 | For unprivileged user running lttng-sessiond, the maximum number of file |
| 196 | descriptors per process is usually 1024. This limits the number of traceable |
| 197 | applications since for each instrumented application there is two file |
| 198 | descriptors per-CPU and one more socket for bidirectional communication. |
| 199 | |
| 200 | For the root user, the limit is bumped to 65535. Future version will deal with |
| 201 | this limitation. |
| 202 | .PP |
| 203 | |
| 204 | .SH "BUGS" |
| 205 | |
| 206 | .PP |
| 207 | No show stopper bugs are known yet in this version. |
| 208 | |
| 209 | If you encounter any issues or usability problem, please report it on our |
| 210 | mailing list <lttng-dev@lists.lttng.org> to help improve this project. |
| 211 | .SH "CREDITS" |
| 212 | |
| 213 | .PP |
| 214 | lttng-sessiond is distributed under the GNU General Public License version 2. See the |
| 215 | file COPYING for details. |
| 216 | .PP |
| 217 | A Web site is available at http://lttng.org for more information on the LTTng |
| 218 | project. |
| 219 | .PP |
| 220 | You can also find our git tree at http://git.lttng.org. |
| 221 | .PP |
| 222 | Mailing lists for support and development: <lttng-dev@lists.lttng.org>. |
| 223 | .PP |
| 224 | You can find us on IRC server irc.oftc.net (OFTC) in #lttng. |
| 225 | .PP |
| 226 | .SH "THANKS" |
| 227 | |
| 228 | .PP |
| 229 | Thanks to Yannick Brosseau without whom this project would never have been so |
| 230 | lean and mean! Also thanks to the Ericsson teams working on tracing which helped |
| 231 | us greatly with detailed bug reports and unusual test cases. |
| 232 | |
| 233 | Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA |
| 234 | maintainer) and Jon Bernard for our Debian packages. |
| 235 | |
| 236 | Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de |
| 237 | Montreal for the LTTng journey. |
| 238 | .PP |
| 239 | .SH "AUTHORS" |
| 240 | |
| 241 | .PP |
| 242 | lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and |
| 243 | David Goulet. More people have since contributed to it. It is currently |
| 244 | maintained by Jérémie Galarneau <jeremie.galarneau@efficios.com>. |
| 245 | .PP |