'\" t
.\"     Title: lttng
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 14 June 2021
.\"    Manual: LTTng Manual
.\"    Source: LTTng 2.13.11
.\"  Language: English
.\"
.TH "LTTNG" "1" "14 June 2021" "LTTng 2\&.13\&.11" "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 \- Control LTTng tracing
.SH "SYNOPSIS"
.sp
.nf
\fBlttng\fR [\fB--group\fR=\fIGROUP\fR] [\fB--mi\fR=\fBxml\fR] [\fB--no-sessiond\fR | \fB--sessiond-path\fR=\fIPATH\fR]
      [\fB--relayd-path\fR=\fIPATH\fR] [\fB--quiet\fR | \fB-verbose\fR\&...]
      \fICOMMAND\fR [\fICOMMAND OPTIONS\fR]
.fi
.SH "DESCRIPTION"
.sp
The \fILinux Trace Toolkit: next generation\fR <https://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
The \fBlttng\fR command\-line tool, as well as any user application linked with the LTTng control library (\fBliblttng-ctl\fR), sends commands to a listening LTTng session daemon (\fBlttng-sessiond\fR(8))\&. A session daemon:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Manages recording sessions (see
\fBlttng-concepts\fR(7)
to learn more about recording sessions)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Controls the various components (like tracers and consumer daemons) of LTTng\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Sends asynchronous notifications to user applications\&.
.RE
.sp
By default, the \fBlttng-create\fR(1) command automatically spawns:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A session daemon for your Unix user if none is currently running\&.
.sp
Override the path of the session daemon binary to spawn with the
\fB--sessiond-path\fR
option\&.
.sp
Avoid automatically spawning a session daemon with the
\fB--no-sessiond\fR
option\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A relay daemon (see
\fBlttng-relayd\fR(8)) if all the following statements are true:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
You specify the
\fB--live\fR
option\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
You don\(cqt specify any of the
\fB--set-url\fR,
\fB--ctrl-url\fR, or
\fB--data-url\fR
options\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
No relay daemon is currently listening for TCP connections on
\fB127.0.0.1:5344\fR
(default LTTng live reader connection address and port)\&.
.RE
.sp
Override the path of the relay daemon binary to spawn with the
\fB--relayd-path\fR
option\&.
.RE
.if n \{\
.sp
.\}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.RS 4
.sp
The LTTng project recommends that you start the session daemon at boot time for stable and long\-term tracing\&.
.sp .5v
.RE
.sp
See \fBlttng-concepts\fR(7) to learn more about the foundational concepts of LTTng\&.
.sp
The \fBlttng\fR tool offers a subcommand\-based command\-line interface\&. The \(lqCOMMANDS\(rq section below lists the available commands\&.
.SS "Session daemon connection"
.sp
For most of its commands, the \fBlttng\fR tool needs to connect to a listening LTTng session daemon (\fBlttng-sessiond\fR(8)) to control LTTng tracing\&.
.sp
Each Unix user may have its own independent running session daemon\&. However, the \fBlttng\fR tool must connect to the session daemon of the \fBroot\fR user (the root session daemon) to control Linux kernel tracing\&.
.sp
How the \fBlttng\fR tool chooses which session daemon to connect to is as follows:
.PP
If your Unix user is \fBroot\fR
.RS 4
Connect to the root session daemon\&.
.RE
.PP
If your Unix user is not \fBroot\fR
.RS 4
.PP
If your Unix user is part of the Unix tracing group
.RS 4
Try to connect to the root session daemon\&.
.sp
If the root session daemon isn\(cqt running, connect to the session daemon of your Unix user\&.
.RE
.PP
If your Unix user is not part of the tracing group
.RS 4
Connect to the session daemon of your Unix user\&.
.RE
.RE
.sp
The name of the Unix tracing group is one of:
.PP
With the \fB--group\fR=\fIGROUP\fR option of the root session daemon (\fBlttng-sessiond\fR(8))
.RS 4
\fIGROUP\fR
.sp
In that case, you must use the
\fB--group\fR=\fIGROUP\fR
option, with the same
\fIGROUP\fR
argument, of the
\fBlttng\fR
tool\&.
.RE
.PP
Without the \fB--group\fR option of the root session daemon
.RS 4
\fBtracing\fR
.RE
.sp
LTTng\-instrumented user applications automatically register to both the root and user session daemons\&. This makes it possible for both session daemons to list the available instrumented applications and their instrumentation points (see \fBlttng-list\fR(1))\&.
.SH "OPTIONS"
.PP
\fB-g\fR \fIGROUP\fR, \fB--group\fR=\fIGROUP\fR
.RS 4
Set the name of the Unix tracing group to
\fIGROUP\fR
instead of
\fBtracing\fR\&.
.sp
You must use this option to be able to connect to a root session daemon (\fBlttng-sessiond\fR(8)) which was started with its own
\fB--group\fR=\fIGROUP\fR
option\&.
.RE
.PP
\fB-m\fR \fBxml\fR, \fB--mi\fR=\fBxml\fR
.RS 4
Print the command\(cqs result using a stable XML machine interface (MI) output instead of the default, unstable human\-readable output\&.
.sp
With this mode,
\fBlttng\fR
prints the resulting XML document to the standard output, while it prints any error/warning to the standard error with an unstable, human\-readable format\&.
.sp
If any error occurs during the execution of
\fBlttng\fR, the command exits with a status different than\ \&0, and
\fBlttng\fR
does NOT guarantee the syntax and data validity of its MI output\&.
.sp
An XML schema definition (XSD) file used for validation of the MI output 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 for your Unix user when running the
\fBlttng-create\fR(1)
command\&.
.sp
You may NOT use this option with the
\fB--sessiond-path\fR
option\&.
.RE
.PP
\fB-q\fR, \fB--quiet\fR
.RS 4
Suppress all messages, including warnings and errors\&.
.sp
You may NOT use this option with the
\fB--verbose\fR
option\&.
.RE
.PP
\fB--sessiond-path\fR=\fIPATH\fR
.RS 4
Set the absolute path of the session daemon binary to spawn from the
\fBlttng-create\fR(1)
command to
\fIPATH\fR\&.
.sp
You may NOT use this option with the
\fB--no-sessiond\fR
option\&.
.RE
.PP
\fB--relayd-path\fR=\fIPATH\fR
.RS 4
Set the absolute path of the relay daemon binary to spawn from the
\fBlttng-create\fR(1)
command to
\fIPATH\fR\&.
.RE
.PP
\fB-v\fR, \fB--verbose\fR
.RS 4
Increase verbosity\&.
.sp
Specify this option up to three times to get more levels of verbosity\&.
.sp
You may NOT use this option with the
\fB--quiet\fR
option\&.
.RE
.SS "Program information"
.PP
\fB-h\fR, \fB--help\fR
.RS 4
Show help\&.
.sp
This option attempts to launch
\fB/usr/bin/man\fR
to view this manual page\&. Override the manual pager path with the
\fBLTTNG_MAN_BIN_PATH\fR
environment variable\&.
.RE
.PP
\fB--list-options\fR
.RS 4
List available command options and quit\&.
.RE
.PP
\fB--list-commands\fR
.RS 4
List available commands and quit\&.
.RE
.PP
\fB-V\fR, \fB--version\fR
.RS 4
Show version and quit\&.
.RE
.SH "COMMANDS"
.sp
The following commands also have their own \fB--help\fR option\&.
.SS "Recording session"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt
lt lt.
T{
.sp
\fBlttng-create\fR(1)
T}:T{
.sp
Create a recording session\&.
T}
T{
.sp
\fBlttng-destroy\fR(1)
T}:T{
.sp
Destroy recording sessions\&.
T}
T{
.sp
\fBlttng-disable-rotation\fR(1)
T}:T{
.sp
Unset a recording session rotation schedule\&.
T}
T{
.sp
\fBlttng-enable-rotation\fR(1)
T}:T{
.sp
Set a recording session rotation schedule\&.
T}
T{
.sp
\fBlttng-load\fR(1)
T}:T{
.sp
Load recording session configurations\&.
T}
T{
.sp
\fBlttng-regenerate\fR(1)
T}:T{
.sp
Regenerate specific recording session data\&.
T}
T{
.sp
\fBlttng-rotate\fR(1)
T}:T{
.sp
Archive the current trace chunk of a recording session\&.
T}
T{
.sp
\fBlttng-save\fR(1)
T}:T{
.sp
Save recording session configurations\&.
T}
T{
.sp
\fBlttng-set-session\fR(1)
T}:T{
.sp
Set the current recording session\&.
T}
T{
.sp
\fBlttng-snapshot\fR(1)
T}:T{
.sp
Take a recording session snapshot\&.
T}
T{
.sp
\fBlttng-start\fR(1)
T}:T{
.sp
Start a recording session\&.
T}
T{
.sp
\fBlttng-status\fR(1)
T}:T{
.sp
Show the status of the current recording session\&.
T}
T{
.sp
\fBlttng-stop\fR(1)
T}:T{
.sp
Stop a recording session\&.
T}
.TE
.sp 1
.SS "Channel"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt.
T{
.sp
\fBlttng-add-context\fR(1)
T}:T{
.sp
Add context fields to be recorded\&.
T}
T{
.sp
\fBlttng-disable-channel\fR(1)
T}:T{
.sp
Disable channels\&.
T}
T{
.sp
\fBlttng-enable-channel\fR(1)
T}:T{
.sp
Create or enable a channel\&.
T}
.TE
.sp 1
.SS "Recording event rule"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt
lt lt.
T{
.sp
\fBlttng-disable-event\fR(1)
T}:T{
.sp
Disable recording event rules\&.
T}
T{
.sp
\fBlttng-enable-event\fR(1)
T}:T{
.sp
Create or enable recording event rules\&.
T}
.TE
.sp 1
.SS "Information"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt.
T{
.sp
\fBlttng-list\fR(1)
T}:T{
.sp
List recording sessions and instrumentation points\&.
T}
.TE
.sp 1
.SS "Resource tracking"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt
lt lt.
T{
.sp
\fBlttng-track\fR(1)
T}:T{
.sp
Allow specific processes to record events\&.
T}
T{
.sp
\fBlttng-untrack\fR(1)
T}:T{
.sp
Disallow specific processes to record events\&.
T}
.TE
.sp 1
.SS "Trigger"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt.
T{
.sp
\fBlttng-add-trigger\fR(1)
T}:T{
.sp
Add a trigger\&.
T}
T{
.sp
\fBlttng-list-triggers\fR(1)
T}:T{
.sp
List triggers\&.
T}
T{
.sp
\fBlttng-remove-trigger\fR(1)
T}:T{
.sp
Remove a trigger\&.
T}
.TE
.sp 1
.SS "Miscellaneous"
.TS
allbox tab(:);
ltB ltB.
T{
Command
T}:T{
Description
T}
.T&
lt lt
lt lt
lt lt.
T{
.sp
\fBlttng-help\fR(1)
T}:T{
.sp
Show the help of a command\&.
T}
T{
.sp
\fBlttng-version\fR(1)
T}:T{
.sp
Show LTTng\-tools version information\&.
T}
T{
.sp
\fBlttng-view\fR(1)
T}:T{
.sp
Launch a trace reader\&.
T}
.TE
.sp 1
.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 "ENVIRONMENT"
.PP
\fBLTTNG_ABORT_ON_ERROR\fR
.RS 4
Set to
\fB1\fR
to abort the process after the first error is encountered\&.
.RE
.PP
\fBLTTNG_HOME\fR
.RS 4
Path to the LTTng home directory\&.
.sp
Defaults to
\fB$HOME\fR\&.
.sp
Useful when the Unix user running the commands has a non\-writable home directory\&.
.RE
.PP
\fBLTTNG_MAN_BIN_PATH\fR
.RS 4
Absolute path to the manual pager to use to read the LTTng command\-line help (with
\fBlttng-help\fR(1)
or with the
\fB--help\fR
option) instead of
\fB/usr/bin/man\fR\&.
.RE
.PP
\fBLTTNG_SESSION_CONFIG_XSD_PATH\fR
.RS 4
Path to the directory containing the
\fBsession.xsd\fR
recording session configuration XML schema\&.
.RE
.PP
\fBLTTNG_SESSIOND_PATH\fR
.RS 4
Absolute path to the LTTng session daemon binary (see
\fBlttng-sessiond\fR(8)) to spawn from the
\fBlttng-create\fR(1)
command\&.
.sp
The
\fB--sessiond-path\fR
general option overrides this environment variable\&.
.RE
.SH "FILES"
.PP
\fB$LTTNG_HOME/.lttngrc\fR
.RS 4
Unix user\(cqs LTTng runtime configuration\&.
.sp
This is where LTTng stores the name of the Unix user\(cqs current recording session between executions of
\fBlttng\fR(1)\&.
\fBlttng-create\fR(1)
and
\fBlttng-set-session\fR(1)
set the current recording session\&.
.RE
.PP
\fB$LTTNG_HOME/lttng-traces\fR
.RS 4
Default output directory of LTTng traces in local and snapshot modes\&.
.sp
Override this path with the
\fB--output\fR
option of the
\fBlttng-create\fR(1)
command\&.
.RE
.PP
\fB$LTTNG_HOME/.lttng\fR
.RS 4
Unix user\(cqs LTTng runtime and configuration directory\&.
.RE
.PP
\fB$LTTNG_HOME/.lttng/sessions\fR
.RS 4
Default directory containing the Unix user\(cqs saved recording session configurations (see
\fBlttng-save\fR(1)
and
\fBlttng-load\fR(1))\&.
.RE
.PP
\fB/etc/lttng/sessions\fR
.RS 4
Directory containing the system\-wide saved recording session configurations (see
\fBlttng-save\fR(1)
and
\fBlttng-load\fR(1))\&.
.RE
.if n \{\
.sp
.\}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.RS 4
.sp
\fB$LTTNG_HOME\fR defaults to the value of the \fBHOME\fR environment variable\&.
.sp .5v
.RE
.SH "RESOURCES"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng project website <https://lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng documentation <https://lttng.org/docs>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LTTng bug tracker <https://bugs.lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Git repositories <https://git.lttng.org>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GitHub organization <https://github.com/lttng>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Continuous integration <https://ci.lttng.org/>
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Mailing list <https://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 "COPYRIGHT"
.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 "SEE ALSO"
.sp
\fBlttng-concepts\fR(7) \fBlttng-relayd\fR(8), \fBlttng-sessiond\fR(8)