1LTTNG(1)                         LTTng Manual                         LTTNG(1)
2
3
4

NAME

6       lttng - LTTng 2 tracer control command-line tool
7

SYNOPSIS

9       lttng [--group=GROUP] [--mi=TYPE] [--no-sessiond | --sessiond-path=PATH]
10             [--quiet | -v | -vv | -vvv] COMMAND [COMMAND OPTIONS]
11

DESCRIPTION

13       The Linux Trace Toolkit: next generation <http://lttng.org/> is an open
14       source software package used for correlated tracing of the Linux
15       kernel, user applications, and user libraries.
16
17       LTTng consists of Linux kernel modules (for Linux kernel tracing) and
18       dynamically loaded libraries (for user application and library
19       tracing).
20
21       An LTTng session daemon, lttng-sessiond(8), receives commands from the
22       command-line interface lttng to control the LTTng tracers. All
23       interactions with the LTTng tracers happen through the lttng tool or
24       through the liblttng-ctl library shipped with the LTTng-tools package.
25
26       A tracing domain is a tracer category. There are five available
27       domains. For some commands, the domain needs to be specified with a
28       command-line option. The domain options are:
29
30       -j, --jul
31           Apply command to the java.util.logging (JUL) domain.
32
33       -k, --kernel
34           Apply command to the Linux kernel domain.
35
36       -l, --log4j
37           Apply command to the Apache log4j 1.2
38           <https://logging.apache.org/log4j/1.2/> (Java) domain.
39
40       -p, --python
41           Apply command to the Python <https://www.python.org/> domain.
42
43       -u, --userspace
44           Apply command to the user space domain (application using
45           liblttng-ust directly; see lttng-ust(3)).
46
47       The LTTng session daemon is a tracing registry which allows the user to
48       interact with multiple tracers (kernel and user space) within the same
49       container, a tracing session. Traces can be gathered from the Linux
50       kernel and/or from instrumented applications (see lttng-ust(3)). You
51       can aggregate and read the events of LTTng traces using babeltrace(1).
52
53       To trace the Linux kernel, the session daemon needs to be running as
54       root. LTTng uses a tracing group to allow specific users to interact
55       with the root session daemon. The default tracing group name is
56       tracing. You can use the --group option to set the tracing group name
57       to use.
58
59       Session daemons can coexist. You can have a session daemon running as
60       user Alice that can be used to trace her applications alongside a root
61       session daemon or a session daemon running as user Bob.
62
63           Note
64           It is highly recommended to start the session daemon at boot time
65           for stable and long-term tracing.
66
67       User applications instrumented with LTTng automatically register to the
68       root session daemon and to user session daemons. This allows any
69       session daemon to list the available traceable applications and event
70       sources (see lttng-list(1)).
71
72       By default, the lttng-create(1) command automatically spawns a user
73       session daemon if none is currently running. The --no-sessiond general
74       option can be set to avoid this.
75

OPTIONS

77       -g GROUP, --group=GROUP
78           Use GROUP as Unix tracing group (default: tracing).
79
80       -m TYPE, --mi=TYPE
81           Print the command’s result using the machine interface type TYPE
82           instead of a human-readable output.
83
84           Supported types: xml.
85
86           The machine interface (MI) mode converts the traditional
87           pretty-printing to a machine output syntax. The MI mode provides a
88           change-resistant way to access information generated by the lttng
89           command-line program.
90
91           When using the MI mode, the data is printed to the standard output.
92           Errors and warnings are printed on the standard error with the
93           pretty-print default format.
94
95           If any error occurs during the execution of a command, the return
96           value of the command will be different than 0. In this case, lttng
97           does NOT guarantee the syntax and data validity of the generated MI
98           output.
99
100           For the xml MI type, an XML schema definition (XSD) file used for
101           validation is available: see the src/common/mi_lttng.xsd file in
102           the LTTng-tools source tree.
103
104       -n, --no-sessiond
105           Do not automatically spawn a session daemon.
106
107       -q, --quiet
108           Suppress all messages, including warnings and errors.
109
110       --sessiond-path=PATH
111           Set the session daemon binary’s absolute path to PATH.
112
113       -v, --verbose
114           Increase verbosity.
115
116           Three levels of verbosity are available, which are triggered by
117           appending additional v letters to the option (that is, -vv and
118           -vvv).
119
120   Program information
121       -h, --help
122           Show help.
123
124       --list-commands
125           List available commands.
126
127       --list-options
128           List available general options.
129
130       -V, --version
131           Show version.
132

COMMANDS

134       The following commands also have their own --help option.
135
136   Tracing sessions
137       lttng-create(1)
138           Create a tracing session.
139
140       lttng-destroy(1)
141           Tear down tracing sessions.
142
143       lttng-load(1)
144           Load tracing session configurations.
145
146       lttng-regenerate(1)
147           Manage an LTTng tracing session’s data regeneration.
148
149       lttng-save(1)
150           Save tracing session configurations.
151
152       lttng-set-session(1)
153           Set current tracing session.
154
155   Channels
156       lttng-add-context(1)
157           Add context fields to a channel.
158
159       lttng-disable-channel(1)
160           Disable tracing channels.
161
162       lttng-enable-channel(1)
163           Create or enable tracing channels.
164
165   Event rules
166       lttng-disable-event(1)
167           Disable event rules.
168
169       lttng-enable-event(1)
170           Create or enable event rules.
171
172   Status
173       lttng-list(1)
174           List tracing sessions, domains, channels, and events.
175
176       lttng-status(1)
177           Get the status of the current tracing session.
178
179   Control
180       lttng-snapshot(1)
181           Snapshot buffers of current tracing session.
182
183       lttng-start(1)
184           Start tracing.
185
186       lttng-stop(1)
187           Stop tracing.
188
189   Resource tracking
190       lttng-track(1)
191           Track specific system resources.
192
193       lttng-untrack(1)
194           Untrack specific system resources.
195
196   Miscellaneous
197       lttng-help(1)
198           Display help information about a command.
199
200       lttng-version(1)
201           Show version information.
202
203       lttng-view(1)
204           Start trace viewer.
205

ENVIRONMENT VARIABLES

207       LTTNG_ABORT_ON_ERROR
208           Set to 1 to abort the process after the first error is encountered.
209
210       LTTNG_HOME
211           Overrides the $HOME environment variable. Useful when the user
212           running the commands has a non-writable home directory.
213
214       LTTNG_MAN_BIN_PATH
215           Absolute path to the man pager to use for viewing help information
216           about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
217
218       LTTNG_SESSION_CONFIG_XSD_PATH
219           Path in which the session.xsd session configuration XML schema may
220           be found.
221
222       LTTNG_SESSIOND_PATH
223           Full session daemon binary path.
224
225           The --sessiond-path option has precedence over this environment
226           variable.
227
228       Note that the lttng-create(1) command can spawn an LTTng session daemon
229       automatically if none is running. See lttng-sessiond(8) for the
230       environment variables influencing the execution of the session daemon.
231

FILES

233       $LTTNG_HOME/.lttngrc
234           User LTTng runtime configuration.
235
236           This is where the per-user current tracing session is stored
237           between executions of lttng(1). The current tracing session can be
238           set with lttng-set-session(1). See lttng-create(1) for more
239           information about tracing sessions.
240
241       $LTTNG_HOME/lttng-traces
242           Default output directory of LTTng traces. This can be overridden
243           with the --output option of the lttng-create(1) command.
244
245       $LTTNG_HOME/.lttng
246           User LTTng runtime and configuration directory.
247
248       $LTTNG_HOME/.lttng/sessions
249           Default location of saved user tracing sessions (see lttng-save(1)
250           and lttng-load(1)).
251
252       /usr/local/etc/lttng/sessions
253           System-wide location of saved tracing sessions (see lttng-save(1)
254           and lttng-load(1)).
255
256           Note
257           $LTTNG_HOME defaults to $HOME when not explicitly set.
258

EXIT STATUS

260       0
261           Success
262
263       1
264           Command error
265
266       2
267           Undefined command
268
269       3
270           Fatal error
271
272       4
273           Command warning (something went wrong during the command)
274

BUGS

276       If you encounter any issue or usability problem, please report it on
277       the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
278

RESOURCES

280       ·   LTTng project website <http://lttng.org>
281
282       ·   LTTng documentation <http://lttng.org/docs>
283
284       ·   Git repositories <http://git.lttng.org>
285
286       ·   GitHub organization <http://github.com/lttng>
287
288       ·   Continuous integration <http://ci.lttng.org/>
289
290       ·   Mailing list <http://lists.lttng.org> for support and development:
291           lttng-dev@lists.lttng.org
292
293       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
294

COPYRIGHTS

296       This program is part of the LTTng-tools project.
297
298       LTTng-tools is distributed under the GNU General Public License version
299       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
300       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
301       for details.
302

THANKS

304       Special thanks to Michel Dagenais and the DORSAL laboratory
305       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
306       the LTTng journey.
307
308       Also thanks to the Ericsson teams working on tracing which helped us
309       greatly with detailed bug reports and unusual test cases.
310

AUTHORS

312       LTTng-tools was originally written by Mathieu Desnoyers, Julien
313       Desfossez, and David Goulet. More people have since contributed to it.
314
315       LTTng-tools is currently maintained by Jérémie Galarneau
316       <mailto:jeremie.galarneau@efficios.com>.
317

SEE ALSO

319       lttng-sessiond(8), lttng-relayd(8), lttng-crash(1), lttng-ust(3),
320       babeltrace(1)
321
322
323
324LTTng 2.10.5                      07/24/2018                          LTTNG(1)
Impressum