doc/man: convert lttng(1) to AsciiDoc
[lttng-tools.git] / doc / man / lttng.1.txt
CommitLineData
307a8468
PP
1lttng(1)
2========
3:doctype: manpage
4
5
6NAME
7----
8lttng - LTTng 2.x tracer control command line tool
9
10
11SYNOPSIS
12--------
13*lttng* ['general-options'] 'command' ['command-options']
14
15
16DESCRIPTION
17-----------
18The LTTng project aims at providing highly efficient tracing tools for Linux.
19Its tracers help track down performance issues and debug problems
20involving multiple concurrent processes and threads. Tracing across multiple
21systems is also possible.
22
23The *lttng* command line tool from the lttng-tools package is used to control
24both kernel and user-space tracing. Every interaction with the tracer should
25be done by this tool or by the liblttng-ctl library provided by the lttng-tools
26package.
27
28LTTng uses a session daemon (*lttng-sessiond*(8)), acting as a tracing registry,
29which allows you to interact with multiple tracers (kernel and user-space)
30inside the same container, a tracing session. Traces can be gathered from the
31kernel and/or instrumented applications (*lttng-ust*(3)). Aggregating and
32reading those traces is done using the *babeltrace*(1) text viewer.
33
34We introduce the notion of _tracing domains_ which is essentially a type of
35tracer (kernel, user space, JUL, LOG4J or Python for now). In the future, we
36could see more tracer like for instance an hypervisor. For some commands,
37you'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
39kernel event.
40
41In order to trace the kernel, the session daemon needs to be running as root.
42LTTng provides the use of a _tracing group_ (default: *tracing*). Whomever is
43in that group can interact with the root session daemon and thus trace the
44kernel. Session daemons can co-exist, meaning that you can have a session daemon
45running as Alice that can be used to trace her applications along side with a
46root daemon or even a Bob daemon. We highly recommend starting the session
47daemon at boot time for stable and long term tracing.
48
49Each user-space application instrumented with *lttng-ust*(3) will automatically
50register with the root session daemon and its user session daemon. This allows
51each daemon to list the available traceable applications and tracepoints at any
52given moment (See the *list* command).
53
54
55OPTIONS
56-------
57This program follows the usual GNU command line syntax with long options
58starting 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+
69Three levels of verbosity are available which are triggered by putting
70additional *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+
92Machine interface (MI) mode converts the traditional pretty printing to a
93machine output syntax. MI mode provides a format change-resistant way to
94access information generated via the lttng command line.
95+
96When using MI mode, the data is printed on the standard output. Error and
97warning are printed on the standard error with the pretty print default
98format.
99+
100If any errors occur during the execution of a command, the return value of the
101command will be different than zero. In this case, lttng does NOT guarantee the
102syntax and data validity of the generated MI output.
103+
104For XML output type, a schema definition (XSD) file used for validation can be
105found under *src/common/mi_lttng.xsd*.
106
107
108COMMANDS
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
168Each command also has its own -h, --help option.
169
170
171EXIT 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
188Any other value above 10, please refer to *<lttng/lttng-error.h>* for a
189detailed list or use *lttng_strerror*() to get a human readable string
190of the error code.
191
192
193ENVIRONMENT VARIABLES
194---------------------
195Note 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
207BUGS
208----
209If you encounter any issues or usability problem, please report it on our
210mailing list *lttng-dev@lists.lttng.org* to help improve this project or
211at *https://bugs.lttng.org* which is a bug tracker.
212
213
214RESOURCES
215---------
216A Web site is available at *http://lttng.org* for more information on the LTTng
217project.
218
219You can also find our git tree at *http://git.lttng.org*.
220
221Mailing lists for support and development: *lttng-dev@lists.lttng.org*.
222
223You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*.
224
225
226COPYRIGHTS
227----------
228lttng is distributed under the GNU General Public License version 2. See the
229file *COPYING* for details.
230
231
232THANKS
233------
234Thanks to Yannick Brosseau without whom this project would never have been so
235lean and mean! Also thanks to the Ericsson teams working on tracing which
236helped us greatly with detailed bug reports and unusual test cases.
237
238Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
239maintainer) and Jon Bernard for our Debian packages.
240
241Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
242Montreal for the LTTng journey.
243
244
245AUTHORS
246-------
247lttng-tools was originally written by Mathieu Desnoyers, Julien Desfossez and
248David Goulet. More people have since contributed to it. It is currently
249maintained by Jérémie Galarneau *jeremie.galarneau@efficios.com*.
250
251
252SEE ALSO
253--------
254*babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8),
255*lttng-crash*(1)
This page took 0.032147 seconds and 5 git commands to generate.