Commit | Line | Data |
---|---|---|
307a8468 PP |
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) |