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 <https://lttng.org/> is an
14       open 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 babeltrace2(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   Tracing session rotation
190       lttng-disable-rotation(1)
191           Unset a rotation schedule.
192
193       lttng-enable-rotation(1)
194           Set a rotation schedule.
195
196       lttng-rotate(1)
197           Archive a tracing session’s current trace chunk.
198
199   Resource tracking
200       lttng-track(1)
201           Track specific system resources.
202
203       lttng-untrack(1)
204           Untrack specific system resources.
205
206   Miscellaneous
207       lttng-help(1)
208           Display help information about a command.
209
210       lttng-version(1)
211           Show version information.
212
213       lttng-view(1)
214           Start trace viewer.
215

ENVIRONMENT VARIABLES

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

FILES

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

EXIT STATUS

270       0
271           Success
272
273       1
274           Command error
275
276       2
277           Undefined command
278
279       3
280           Fatal error
281
282       4
283           Command warning (something went wrong during the command)
284

BUGS

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

RESOURCES

290       ·   LTTng project website <https://lttng.org>
291
292       ·   LTTng documentation <https://lttng.org/docs>
293
294       ·   Git repositories <http://git.lttng.org>
295
296       ·   GitHub organization <http://github.com/lttng>
297
298       ·   Continuous integration <http://ci.lttng.org/>
299
300       ·   Mailing list <http://lists.lttng.org> for support and development:
301           lttng-dev@lists.lttng.org
302
303       ·   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
304

COPYRIGHTS

306       This program is part of the LTTng-tools project.
307
308       LTTng-tools is distributed under the GNU General Public License version
309       2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
310       LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
311       for details.
312

THANKS

314       Special thanks to Michel Dagenais and the DORSAL laboratory
315       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
316       the LTTng journey.
317
318       Also thanks to the Ericsson teams working on tracing which helped us
319       greatly with detailed bug reports and unusual test cases.
320

SEE ALSO

322       lttng-sessiond(8), lttng-relayd(8), lttng-crash(1), lttng-ust(3),
323       babeltrace2(1)
324
325
326
327LTTng 2.12.2                    16 October 2019                       LTTNG(1)
Impressum