'\" t
.\"     Title: lttng
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/09/2017
.\"    Manual: LTTng Manual
.\"    Source: LTTng 2.9.3
.\"  Language: English
.\"
.TH "LTTNG" "1" "01/09/2017" "LTTng 2\&.9\&.3" "LTTng Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
lttng \- LTTng 2 tracer control command\-line tool
.SH "SYNOPSIS"
.sp
.nf
\fBlttng\fR [\fB--group\fR=\fIGROUP\fR] [\fB--mi\fR=\fITYPE\fR] [\fB--no-sessiond\fR | \fB--sessiond-path\fR=\fIPATH\fR]
      [\fB--quiet\fR | \fB-v\fR | \fB-vv\fR | \fB-vvv\fR] \fI\fICOMMAND\fR\fR [\fICOMMAND OPTIONS\fR]
.fi
.SH "DESCRIPTION"
.sp
The \fILinux Trace Toolkit: next generation\fR <http://lttng.org/> is an open source software package used for correlated tracing of the Linux kernel, user applications, and user libraries\&.
.sp
LTTng consists of Linux kernel modules (for Linux kernel tracing) and dynamically loaded libraries (for user application and library tracing)\&.
.sp
An LTTng \fIsession daemon\fR, \fBlttng-sessiond\fR(8), receives commands from the command\-line interface \fBlttng\fR to control the LTTng tracers\&. All interactions with the LTTng tracers happen through the \fBlttng\fR tool or through the liblttng\-ctl library shipped with the LTTng\-tools package\&.
.sp
A \fItracing domain\fR is a tracer category\&. There are five available domains\&. For some commands, the domain needs to be specified with a command\-line option\&. The domain options are:
.PP
\fB-j\fR, \fB--jul\fR
.RS 4
Apply command to the
\fBjava.util.logging\fR
(JUL) domain\&.
.RE
.PP
\fB-k\fR, \fB--kernel\fR
.RS 4
Apply command to the Linux kernel domain\&.
.RE
.PP
\fB-l\fR, \fB--log4j\fR
.RS 4
Apply command to the
Apache log4j 1\&.2 <https://logging.apache.org/log4j/1.2/>
(Java) domain\&.
.RE
.PP
\fB-p\fR, \fB--python\fR
.RS 4
Apply command to the
Python <https://www.python.org/>
domain\&.
.RE
.PP
\fB-u\fR, \fB--userspace\fR
.RS 4
Apply command to the user space domain (application using liblttng\-ust directly; see
\fBlttng-ust\fR(3))\&.
.RE
.sp
The LTTng session daemon is a tracing registry which allows the user to interact with multiple tracers (kernel and user space) within the same container, a \fItracing session\fR\&. Traces can be gathered from the Linux kernel and/or from instrumented applications (see \fBlttng-ust\fR(3))\&. You can aggregate and read the events of LTTng traces using \fBbabeltrace\fR(1)\&.
.sp
To trace the Linux kernel, the session daemon needs to be running as \fBroot\fR\&. LTTng uses a \fItracing group\fR to allow specific users to interact with the root session daemon\&. The default tracing group name is \fBtracing\fR\&. You can use the \fB--group\fR option to set the tracing group name to use\&.
.sp
Session daemons can coexist\&. You can have a session daemon running as user Alice that can be used to trace her applications alongside a root session daemon or a session daemon running as user Bob\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
It is highly recommended to start the session daemon at boot time for stable and long\-term tracing\&.
.sp .5v
.RE
.sp
User applications instrumented with LTTng automatically register to the root session daemon and to user session daemons\&. This allows any session daemon to list the available traceable applications and event sources (see \fBlttng-list\fR(1))\&.
.sp
By default, the \fBlttng-create\fR(1) command automatically spawns a user session daemon if none is currently running\&. The \fB--no-sessiond\fR general option can be set to avoid this\&.
.SH "OPTIONS"
.PP
\fB-g\fR \fIGROUP\fR, \fB--group\fR=\fIGROUP\fR
.RS 4
Use
\fIGROUP\fR
as Unix tracing group (default:
\fBtracing\fR)\&.
.RE
.PP
\fB-m\fR \fITYPE\fR, \fB--mi\fR=\fITYPE\fR
.RS 4
Print the command\(cqs result using the machine interface type
\fITYPE\fR
instead of a human\-readable output\&.
.sp
Supported types:
\fBxml\fR\&.
.sp
The machine interface (MI) mode converts the traditional pretty\-printing to a machine output syntax\&. The MI mode provides a change\-resistant way to access information generated by the
\fBlttng\fR
command\-line program\&.
.sp
When using the MI mode, the data is printed to the standard output\&. Errors and warnings are printed on the standard error with the pretty\-print default format\&.
.sp
If any error occurs during the execution of a command, the return value of the command will be different than 0\&. In this case,
\fBlttng\fR
does NOT guarantee the syntax and data validity of the generated MI output\&.
.sp
For the
\fBxml\fR
MI type, an XML schema definition (XSD) file used for validation is available: see the
\fBsrc/common/mi_lttng.xsd\fR
file in the LTTng\-tools source tree\&.
.RE
.PP
\fB-n\fR, \fB--no-sessiond\fR
.RS 4
Do not automatically spawn a session daemon\&.
.RE
.PP
\fB-q\fR, \fB--quiet\fR
.RS 4
Suppress all messages, including warnings and errors\&.
.RE
.PP
\fB--sessiond-path\fR=\fIPATH\fR
.RS 4
Set the session daemon binary\(cqs absolute path to
\fIPATH\fR\&.
.RE
.PP
\fB-v\fR, \fB--verbose\fR
.RS 4
Increase verbosity\&.
.sp
Three levels of verbosity are available, which are triggered by appending additional
\fBv\fR
letters to the option (that is,
\fB-vv\fR
and
\fB-vvv\fR)\&.
.RE
.SS "Program information"
.PP
\fB-h\fR, \fB--help\fR
.RS 4
Show help\&.
.RE
.PP
\fB--list-commands\fR
.RS 4
List available commands\&.
.RE
.PP
\fB--list-options\fR
.RS 4
List available general options\&.
.RE
.PP
\fB-V\fR, \fB--version\fR
.RS 4
Show version\&.
.RE
.SH "COMMANDS"
.sp
The following commands also have their own \fB--help\fR option\&.
.SS "Tracing sessions"
.PP
\fBlttng-create\fR(1)
.RS 4
Create a tracing session\&.
.RE
.PP
\fBlttng-destroy\fR(1)
.RS 4
Tear down tracing sessions\&.
.RE
.PP
\fBlttng-load\fR(1)
.RS 4
Load tracing session configurations\&.
.RE
.PP
\fBlttng-regenerate\fR(1)
.RS 4
Manage an LTTng tracing session\(cqs data regeneration\&.
.RE
.PP
\fBlttng-save\fR(1)
.RS 4
Save tracing session configurations\&.
.RE
.PP
\fBlttng-set-session\fR(1)
.RS 4
Set current tracing session\&.
.RE
.SS "Channels"
.PP
\fBlttng-add-context\fR(1)
.RS 4
Add context fields to a channel\&.
.RE
.PP
\fBlttng-disable-channel\fR(1)
.RS 4
Disable tracing channels\&.
.RE
.PP
\fBlttng-enable-channel\fR(1)
.RS 4
Create or enable tracing channels\&.
.RE
.SS "Event rules"
.PP
\fBlttng-disable-event\fR(1)
.RS 4
Disable event rules\&.
.RE
.PP
\fBlttng-enable-event\fR(1)
.RS 4
Create or enable event rules\&.
.RE
.SS "Status"
.PP
\fBlttng-list\fR(1)
.RS 4
List tracing sessions, domains, channels, and events\&.
.RE
.PP
\fBlttng-status\fR(1)
.RS 4
Get the status of the current tracing session\&.
.RE
.SS "Control"
.PP
\fBlttng-snapshot\fR(1)
.RS 4
Snapshot buffers of current tracing session\&.
.RE
.PP
\fBlttng-start\fR(1)
.RS 4
Start tracing\&.
.RE
.PP
\fBlttng-stop\fR(1)
.RS 4
Stop tracing\&.
.RE
.SS "Resource tracking"
.PP
\fBlttng-track\fR(1)
.RS 4
Track specific system resources\&.
.RE
.PP
\fBlttng-untrack\fR(1)
.RS 4
Untrack specific system resources\&.
.RE
.SS "Miscellaneous"
.PP
\fBlttng-help\fR(1)
.RS 4
Display help information about a command\&.
.RE
.PP
\fBlttng-version\fR(1)
.RS 4
Show version information\&.
.RE
.PP
\fBlttng-view\fR(1)
.RS 4
Start trace viewer\&.
.RE
.SH "ENVIRONMENT VARIABLES"
.PP
\fBLTTNG_ABORT_ON_ERROR\fR
.RS 4
Set to 1 to abort the process after the first error is encountered\&.
.RE
.PP
\fBLTTNG_HOME\fR
.RS 4
Overrides the
\fB$HOME\fR
environment variable\&. Useful when the user running the commands has a non\-writable home directory\&.
.RE
.PP
\fBLTTNG_MAN_BIN_PATH\fR
.RS 4
Absolute path to the man pager to use for viewing help information about LTTng commands (using
\fBlttng-help\fR(1)
or
\fBlttng COMMAND --help\fR)\&.
.RE
.PP
\fBLTTNG_SESSION_CONFIG_XSD_PATH\fR
.RS 4
Path in which the
\fBsession.xsd\fR
session configuration XML schema may be found\&.
.RE
.PP
\fBLTTNG_SESSIOND_PATH\fR
.RS 4
Full session daemon binary path\&.
.sp
The
\fB--sessiond-path\fR
option has precedence over this environment variable\&.
.RE
.sp
Note that the \fBlttng-create\fR(1) command can spawn an LTTng session daemon automatically if none is running\&. See \fBlttng-sessiond\fR(8) for the environment variables influencing the execution of the session daemon\&.
.SH "FILES"
.PP
\fB$LTTNG_HOME/.lttngrc\fR
.RS 4
User LTTng runtime configuration\&.
.sp
This is where the per\-user current tracing session is stored between executions of
\fBlttng\fR(1)\&. The current tracing session can be set with
\fBlttng-set-session\fR(1)\&. See
\fBlttng-create\fR(1)
for more information about tracing sessions\&.
.RE
.PP
\fB$LTTNG_HOME/lttng-traces\fR
.RS 4
Default output directory of LTTng traces\&. This can be overridden with the
\fB--output\fR
option of the
\fBlttng-create\fR(1)
command\&.
.RE
.PP
\fB$LTTNG_HOME/.lttng\fR
.RS 4
User LTTng runtime and configuration directory\&.
.RE
.PP
\fB$LTTNG_HOME/.lttng/sessions\fR
.RS 4
Default location of saved user tracing sessions (see
\fBlttng-save\fR(1)
and
\fBlttng-load\fR(1))\&.
.RE
.PP
\fB/usr/local/etc/lttng/sessions\fR
.RS 4
System\-wide location of saved tracing sessions (see
\fBlttng-save\fR(1)
and
\fBlttng-load\fR(1))\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
\fB$LTTNG_HOME\fR defaults to \fB$HOME\fR when not explicitly set\&.
.sp .5v
.RE
.SH "EXIT STATUS"
.PP
\fB0\fR
.RS 4
Success
.RE
.PP
\fB1\fR
.RS 4
Command error
.RE
.PP
\fB2\fR
.RS 4
Undefined command
.RE
.PP
\fB3\fR
.RS 4
Fatal error
.RE
.PP
\fB4\fR
.RS 4
Command warning (something went wrong during the command)
.RE
.SH "BUGS"
.sp
If you encounter any issue or usability problem, please report it on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>\&.
.SH "RESOURCES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng project website <http://lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng documentation <http://lttng.org/docs>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Git repositories <http://git.lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GitHub organization <http://github.com/lttng>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Continuous integration <http://ci.lttng.org/>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Mailing list <http://lists.lttng.org>
for support and development:
\fBlttng-dev@lists.lttng.org\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
IRC channel <irc://irc.oftc.net/lttng>:
\fB#lttng\fR
on
\fBirc.oftc.net\fR
.RE
.SH "COPYRIGHTS"
.sp
This program is part of the LTTng\-tools project\&.
.sp
LTTng\-tools is distributed under the GNU General Public License version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>\&. See the \fBLICENSE\fR <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details\&.
.SH "THANKS"
.sp
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at \('Ecole Polytechnique de Montr\('eal for the LTTng journey\&.
.sp
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases\&.
.SH "AUTHORS"
.sp
LTTng\-tools was originally written by Mathieu Desnoyers, Julien Desfossez, and David Goulet\&. More people have since contributed to it\&.
.sp
LTTng\-tools is currently maintained by J\('er\('emie Galarneau <mailto:jeremie.galarneau@efficios.com>\&.
.SH "SEE ALSO"
.sp
\fBlttng-sessiond\fR(8), \fBlttng-relayd\fR(8), \fBlttng-crash\fR(1), \fBlttng-ust\fR(3), \fBbabeltrace\fR(1)