| 1 | lttng(1) |
| 2 | ======== |
| 3 | :doctype: manpage |
| 4 | |
| 5 | |
| 6 | NAME |
| 7 | ---- |
| 8 | lttng - LTTng 2.x tracer control command line tool |
| 9 | |
| 10 | |
| 11 | SYNOPSIS |
| 12 | -------- |
| 13 | *lttng* ['general-options'] 'command' ['command-options'] |
| 14 | |
| 15 | |
| 16 | DESCRIPTION |
| 17 | ----------- |
| 18 | The LTTng project aims at providing highly efficient tracing tools for Linux. |
| 19 | Its tracers help track down performance issues and debug problems |
| 20 | involving multiple concurrent processes and threads. Tracing across multiple |
| 21 | systems is also possible. |
| 22 | |
| 23 | The *lttng* command line tool from the lttng-tools package is used to control |
| 24 | both kernel and user-space tracing. Every interaction with the tracer should |
| 25 | be done by this tool or by the liblttng-ctl library provided by the lttng-tools |
| 26 | package. |
| 27 | |
| 28 | LTTng uses a session daemon (*lttng-sessiond*(8)), acting as a tracing registry, |
| 29 | which allows you to interact with multiple tracers (kernel and user-space) |
| 30 | inside the same container, a tracing session. Traces can be gathered from the |
| 31 | kernel and/or instrumented applications (*lttng-ust*(3)). Aggregating and |
| 32 | reading those traces is done using the *babeltrace*(1) text viewer. |
| 33 | |
| 34 | We introduce the notion of _tracing domains_ which is essentially a type of |
| 35 | tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we |
| 36 | could see more tracer like for instance an hypervisor. For some commands, |
| 37 | you'll need to specify on which domain the command operates (*-u*, *-k*, *-l*, |
| 38 | *-j* or *-p*). For instance, the kernel domain must be specified when enabling a |
| 39 | kernel event. |
| 40 | |
| 41 | In order to trace the kernel, the session daemon needs to be running as root. |
| 42 | LTTng provides the use of a _tracing group_ (default: *tracing*). Whomever is |
| 43 | in that group can interact with the root session daemon and thus trace the |
| 44 | kernel. Session daemons can co-exist, meaning that you can have a session daemon |
| 45 | running as Alice that can be used to trace her applications along side with a |
| 46 | root daemon or even a Bob daemon. We highly recommend starting the session |
| 47 | daemon at boot time for stable and long term tracing. |
| 48 | |
| 49 | Each user-space application instrumented with *lttng-ust*(3) will automatically |
| 50 | register with the root session daemon and its user session daemon. This allows |
| 51 | each daemon to list the available traceable applications and tracepoints at any |
| 52 | given moment (See the *list* command). |
| 53 | |
| 54 | |
| 55 | OPTIONS |
| 56 | ------- |
| 57 | This program follows the usual GNU command line syntax with long options |
| 58 | starting with two dashes. Below is a summary of the available options. |
| 59 | |
| 60 | *-h, --help*:: |
| 61 | Show summary of possible options and commands. |
| 62 | |
| 63 | *-V, --version*:: |
| 64 | Show version. |
| 65 | |
| 66 | *-v, --verbose*:: |
| 67 | Increase verbosity. |
| 68 | + |
| 69 | Three levels of verbosity are available which are triggered by putting |
| 70 | additional *v* to the option (*-vv* or *-vvv*). |
| 71 | |
| 72 | *-q, --quiet*:: |
| 73 | Suppress all messages (even errors). |
| 74 | |
| 75 | *-g, --group='GROUP'*:: |
| 76 | Set unix tracing group name. (default: *tracing*) |
| 77 | |
| 78 | *-n, --no-sessiond*:: |
| 79 | Don't automatically spawn a session daemon. |
| 80 | |
| 81 | *--sessiond-path='PATH'*:: |
| 82 | Set session daemon full binary path. |
| 83 | |
| 84 | *--list-options*:: |
| 85 | Simple listing of lttng commands. |
| 86 | |
| 87 | *-m, --mi='TYPE'*:: |
| 88 | Machine interface |
| 89 | + |
| 90 | 'TYPE' supported: *xml* |
| 91 | + |
| 92 | Machine interface (MI) mode converts the traditional pretty printing to a |
| 93 | machine output syntax. MI mode provides a format change-resistant way to |
| 94 | access information generated via the lttng command line. |
| 95 | + |
| 96 | When using MI mode, the data is printed on the standard output. Error and |
| 97 | warning are printed on the standard error with the pretty print default |
| 98 | format. |
| 99 | + |
| 100 | If any errors occur during the execution of a command, the return value of the |
| 101 | command will be different than zero. In this case, lttng does NOT guarantee the |
| 102 | syntax and data validity of the generated MI output. |
| 103 | + |
| 104 | For XML output type, a schema definition (XSD) file used for validation can be |
| 105 | found under *src/common/mi_lttng.xsd*. |
| 106 | |
| 107 | |
| 108 | COMMANDS |
| 109 | -------- |
| 110 | |
| 111 | *lttng-add-context*(1):: |
| 112 | Add context to event and/or channel |
| 113 | |
| 114 | *lttng-calibrate*(1):: |
| 115 | Quantify LTTng overhead |
| 116 | |
| 117 | *lttng-create*(1):: |
| 118 | Create tracing session |
| 119 | |
| 120 | *lttng-destroy*(1):: |
| 121 | Tear down tracing session |
| 122 | |
| 123 | *lttng-enable-channel*(1):: |
| 124 | Enable tracing channel |
| 125 | |
| 126 | *lttng-enable-event*(1):: |
| 127 | Enable tracing event |
| 128 | |
| 129 | *lttng-disable-channel*(1):: |
| 130 | Disable tracing channel |
| 131 | |
| 132 | *lttng-disable-event*(1):: |
| 133 | Disable tracing event |
| 134 | |
| 135 | *lttng-list*(1):: |
| 136 | List possible tracing options |
| 137 | |
| 138 | *lttng-set-session*(1):: |
| 139 | Set current session name |
| 140 | |
| 141 | *lttng-snapshot*(1):: |
| 142 | Snapshot buffers of current session name |
| 143 | |
| 144 | *lttng-start*(1):: |
| 145 | Start tracing |
| 146 | |
| 147 | *lttng-stop*(1):: |
| 148 | Stop tracing |
| 149 | |
| 150 | *lttng-version*(1):: |
| 151 | Show version information |
| 152 | |
| 153 | *lttng-view*(1):: |
| 154 | Start trace viewer |
| 155 | |
| 156 | *lttng-save*(1):: |
| 157 | Save session configuration |
| 158 | |
| 159 | *lttng-load*(1):: |
| 160 | Load session configuration |
| 161 | |
| 162 | *lttng-track*(1):: |
| 163 | Track specific system resources |
| 164 | |
| 165 | *lttng-untrack*(1):: |
| 166 | Untrack specific system resources |
| 167 | |
| 168 | Each command also has its own -h, --help option. |
| 169 | |
| 170 | |
| 171 | EXIT STATUS |
| 172 | ----------- |
| 173 | *0*:: |
| 174 | Success |
| 175 | |
| 176 | *1*:: |
| 177 | Command error |
| 178 | |
| 179 | *2*:: |
| 180 | Undefined command |
| 181 | |
| 182 | *3*:: |
| 183 | Fatal error |
| 184 | |
| 185 | *4*:: |
| 186 | Command warning (something went wrong during the command) |
| 187 | |
| 188 | Any other value above 10, please refer to *<lttng/lttng-error.h>* for a |
| 189 | detailed list or use *lttng_strerror*() to get a human readable string |
| 190 | of the error code. |
| 191 | |
| 192 | |
| 193 | ENVIRONMENT VARIABLES |
| 194 | --------------------- |
| 195 | Note that all command line options override environment variables. |
| 196 | |
| 197 | *LTTNG_SESSIOND_PATH*:: |
| 198 | Allows one to specify the full session daemon binary path to lttng command |
| 199 | line tool. You can also use *--sessiond-path** option having the |
| 200 | same effect. |
| 201 | |
| 202 | *LTTNG_SESSION_CONFIG_XSD_PATH*:: |
| 203 | Set the path in which the *session.xsd* session configuration schema may be |
| 204 | found. |
| 205 | |
| 206 | |
| 207 | BUGS |
| 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 or |
| 211 | at *https://bugs.lttng.org* which is a bug tracker. |
| 212 | |
| 213 | |
| 214 | RESOURCES |
| 215 | --------- |
| 216 | A Web site is available at *http://lttng.org* for more information on the LTTng |
| 217 | project. |
| 218 | |
| 219 | You can also find our git tree at *http://git.lttng.org*. |
| 220 | |
| 221 | Mailing lists for support and development: *lttng-dev@lists.lttng.org*. |
| 222 | |
| 223 | You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*. |
| 224 | |
| 225 | |
| 226 | COPYRIGHTS |
| 227 | ---------- |
| 228 | lttng is distributed under the GNU General Public License version 2. See the |
| 229 | file *COPYING* for details. |
| 230 | |
| 231 | |
| 232 | THANKS |
| 233 | ------ |
| 234 | Thanks to Yannick Brosseau without whom this project would never have been so |
| 235 | lean and mean! Also thanks to the Ericsson teams working on tracing which |
| 236 | helped us greatly with detailed bug reports and unusual test cases. |
| 237 | |
| 238 | Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA |
| 239 | maintainer) and Jon Bernard for our Debian packages. |
| 240 | |
| 241 | Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de |
| 242 | Montreal for the LTTng journey. |
| 243 | |
| 244 | |
| 245 | AUTHORS |
| 246 | ------- |
| 247 | lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and |
| 248 | David Goulet. More people have since contributed to it. It is currently |
| 249 | maintained by Jérémie Galarneau *jeremie.galarneau@efficios.com*. |
| 250 | |
| 251 | |
| 252 | SEE ALSO |
| 253 | -------- |
| 254 | *babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8), |
| 255 | *lttng-crash*(1) |