8 lttng - LTTng 2.x tracer control command line tool
13 *lttng* ['general-options'] 'command' ['command-options']
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.
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
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.
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
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.
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).
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.
61 Show summary of possible options and commands.
69 Three levels of verbosity are available which are triggered by putting
70 additional *v* to the option (*-vv* or *-vvv*).
73 Suppress all messages (even errors).
75 *-g, --group='GROUP'*::
76 Set unix tracing group name. (default: *tracing*)
79 Don't automatically spawn a session daemon.
81 *--sessiond-path='PATH'*::
82 Set session daemon full binary path.
85 Simple listing of lttng commands.
90 'TYPE' supported: *xml*
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.
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
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.
104 For XML output type, a schema definition (XSD) file used for validation can be
105 found under *src/common/mi_lttng.xsd*.
111 *lttng-add-context*(1)::
112 Add context to event and/or channel
114 *lttng-calibrate*(1)::
115 Quantify LTTng overhead
118 Create tracing session
121 Tear down tracing session
123 *lttng-enable-channel*(1)::
124 Enable tracing channel
126 *lttng-enable-event*(1)::
129 *lttng-disable-channel*(1)::
130 Disable tracing channel
132 *lttng-disable-event*(1)::
133 Disable tracing event
136 List possible tracing options
138 *lttng-set-session*(1)::
139 Set current session name
141 *lttng-snapshot*(1)::
142 Snapshot buffers of current session name
151 Show version information
157 Save session configuration
160 Load session configuration
163 Track specific system resources
166 Untrack specific system resources
168 Each command also has its own -h, --help option.
186 Command warning (something went wrong during the command)
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
193 ENVIRONMENT VARIABLES
194 ---------------------
195 Note that all command line options override environment variables.
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
202 *LTTNG_SESSION_CONFIG_XSD_PATH*::
203 Set the path in which the *session.xsd* session configuration schema may be
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.
216 A Web site is available at *http://lttng.org* for more information on the LTTng
219 You can also find our git tree at *http://git.lttng.org*.
221 Mailing lists for support and development: *lttng-dev@lists.lttng.org*.
223 You can find us on IRC server *irc.oftc.net* (OFTC) in *#lttng*.
228 lttng is distributed under the GNU General Public License version 2. See the
229 file *COPYING* for details.
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.
238 Thanks to our beloved packager Alexandre Montplaisir-Goncalves (Ubuntu and PPA
239 maintainer) and Jon Bernard for our Debian packages.
241 Special thanks to Michel Dagenais and the DORSAL laboratory at Polytechnique de
242 Montreal for the LTTng journey.
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*.
254 *babeltrace*(1), *lttng-ust*(3), *lttng-sessiond*(8), *lttng-relayd*(8),