'\" t
.\"     Title: lttng-create
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 18 January 2018
.\"    Manual: LTTng Manual
.\"    Source: LTTng 2.12.3
.\"  Language: English
.\"
.TH "LTTNG\-CREATE" "1" "18 January 2018" "LTTng 2\&.12\&.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-create \- Create an LTTng tracing session
.SH "SYNOPSIS"
.sp
Local mode:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBcreate\fR [\fISESSION\fR] [\fB--shm-path\fR=\fIPATH\fR]
      [\fB--no-output\fR | \fB--output\fR=\fIPATH\fR | \fB--set-url\fR=file://\fIPATH\fR]
.fi
.sp
Network streaming mode:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBcreate\fR [\fISESSION\fR] [\fB--shm-path\fR=\fIPATH\fR]
      (\fB--set-url\fR=\fIURL\fR | \fB--ctrl-url\fR=\fIURL\fR \fB--data-url\fR=\fIURL\fR)
.fi
.sp
Snapshot mode:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBcreate\fR [\fISESSION\fR] \fB--snapshot\fR
      [\fB--shm-path\fR=\fIPATH\fR] [\fB--set-url\fR=\fIURL\fR | \fB--ctrl-url\fR=\fIURL\fR \fB--data-url\fR=\fIURL\fR]
.fi
.sp
Live mode:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBcreate\fR [\fISESSION\fR] \fB--live\fR[=\fIDELAYUS\fR]
      [\fB--shm-path\fR=\fIPATH\fR] [\fB--set-url\fR=\fIURL\fR | \fB--ctrl-url\fR=\fIURL\fR \fB--data-url\fR=\fIURL\fR]
.fi
.SH "DESCRIPTION"
.sp
The \fBlttng create\fR command creates a new tracing session\&.
.sp
A tracing session is a named container of channels, which in turn contain event rules\&. It is domain\-agnostic, in that channels and event rules can be enabled for the user space tracer and/or the Linux kernel tracer\&.
.sp
On execution, an \fB.lttngrc\fR file is created, if it does not exist, in the user\(cqs home directory\&. This file contains the name of the current tracing session\&. When creating a new tracing session with \fBlttng create\fR, the current tracing session is set to this new tracing session\&. The \fBlttng-set-session\fR(1) command can be used to set the current tracing session without manually editing the \fB.lttngrc\fR file\&.
.sp
If \fISESSION\fR is omitted, a session name is automatically created having this form: \fBauto-YYYYmmdd-HHMMSS\fR\&. \fISESSION\fR \fBmust not\fR contain the character \fB/\fR\&.
.sp
The \fB--shm-path\fR option can be used to specify the path to the shared memory holding the ring buffers\&. Specifying a location on an NVRAM file system makes it possible to retrieve the latest recorded trace data when the system reboots after a crash\&. To view the events of ring buffer files after a system crash, use the \fBlttng-crash\fR(1) utility\&.
.sp
Tracing sessions are destroyed using the \fBlttng-destroy\fR(1) command\&.
.SS "Creation modes"
.sp
There are four tracing session modes:
.PP
Local mode
.RS 4
Traces the local system and writes the trace to the local file system\&. The
\fB--output\fR
option specifies the trace path\&. Using
\fB--set-url\fR=file://\fIPATH\fR
is the equivalent of using
\fB--output\fR=\fIPATH\fR\&. The file system output can be disabled using the
\fB--no-output\fR
option\&.
.sp
If none of the options mentioned above are used, then the trace is written locally in the
\fB$LTTNG_HOME/lttng-traces\fR
directory (\fB$LTTNG_HOME\fR
defaults to
\fB$HOME\fR)\&.
.RE
.PP
Network streaming mode
.RS 4
Traces the local system and sends the trace over the network to a listening relay daemon (see
\fBlttng-relayd\fR(8))\&. The
\fB--set-url\fR, or
\fB--ctrl-url\fR
and
\fB--data-url\fR
options set the trace output destination (see the
\fIURL format\fR
section below)\&.
.RE
.PP
Snapshot mode
.RS 4
Traces the local system without writing the trace to the local file system (implicit
\fB--no-output\fR
option)\&. Channels are automatically configured to be snapshot\-ready on creation (see
\fBlttng-enable-channel\fR(1))\&. The
\fBlttng-snapshot\fR(1)
command is used to take snapshots of the current ring buffers\&. The
\fB--set-url\fR, or
\fB--ctrl-url\fR
and
\fB--data-url\fR
options set the default snapshot output destination\&.
.RE
.PP
Live mode
.RS 4
Traces the local system, sending trace data to an LTTng relay daemon over the network (see
\fBlttng-relayd\fR(8))\&. The
\fB--set-url\fR, or
\fB--ctrl-url\fR
and
\fB--data-url\fR
options set the trace output destination\&. The live output URLs cannot use the
\fBfile://\fR
protocol (see the
\fIURL format\fR
section below)\&.
.RE
.SS "URL format"
.sp
The \fB--set-url\fR, \fB--ctrl-url\fR, and \fB--data-url\fR options\*(Aq arguments are URLs\&.
.sp
The format of those URLs is one of:
.sp
.if n \{\
.RS 4
.\}
.nf
file://\fITRACEPATH\fR
\fINETPROTO\fR://(\fIHOST\fR | \fIIPADDR\fR)[:\fICTRLPORT\fR[:\fIDATAPORT\fR]][/\fITRACEPATH\fR]
.fi
.if n \{\
.RE
.\}
.sp
The \fBfile://\fR protocol targets the \fBlocal file system\fR and can only be used as the \fB--set-url\fR option\(cqs argument when the session is created in \fIlocal\fR or \fIsnapshot\fR mode\&.
.PP
\fITRACEPATH\fR
.RS 4
Absolute path to trace files on the local file system\&.
.RE
.sp
The other version is available when the session is created in \fInetwork streaming\fR, \fIsnapshot\fR, or \fIlive\fR mode\&.
.PP
\fINETPROTO\fR
.RS 4
Network protocol, amongst:
.PP
\fBnet\fR
.RS 4
TCP over IPv4; the default values of
\fICTRLPORT\fR
and
\fIDATAPORT\fR
are respectively 5342 and 5343\&.
.RE
.PP
\fBnet6\fR
.RS 4
TCP over IPv6: same default ports as the
\fBnet\fR
protocol\&.
.RE
.PP
\fBtcp\fR
.RS 4
Same as the
\fBnet\fR
protocol; can only be used with the
\fB--ctrl-url\fR
and
\fB--data-url\fR
options together\&.
.RE
.PP
\fBtcp6\fR
.RS 4
Same as the
\fBnet6\fR
protocol; can only be used with the
\fB--ctrl-url\fR
and
\fB--data-url\fR
options together\&.
.RE
.RE
.PP
(\fIHOST\fR | \fIIPADDR\fR)
.RS 4
Hostname or IP address (IPv6 address
\fBmust\fR
be enclosed in brackets (\fB[\fR
and
\fB]\fR); see
RFC 2732 <https://www.ietf.org/rfc/rfc2732.txt>)\&.
.RE
.PP
\fICTRLPORT\fR
.RS 4
Control port\&.
.RE
.PP
\fIDATAPORT\fR
.RS 4
Data port\&.
.RE
.PP
\fITRACEPATH\fR
.RS 4
Path of trace files on the remote file system\&. This path is relative to the base output directory set on the relay daemon side; see
\fBlttng-relayd\fR(8)\&.
.RE
.SH "OPTIONS"
.sp
General options are described in \fBlttng\fR(1)\&.
.SS "Mode selection"
.PP
\fB--live\fR[=\fIDELAYUS\fR]
.RS 4
Create the session in
\fIlive mode\fR\&.
.sp
The optional
\fIDELAYUS\fR
parameter, given in microseconds, is the maximum time the user can wait for the data to be flushed\&. This mode can be set with a network URL (options
\fB--set-url\fR, or
\fB--ctrl-url\fR
and
\fB--data-url\fR) and must have a relay daemon listening (see
\fBlttng-relayd\fR(8))\&.
.sp
By default,
\fIDELAYUS\fR
is 1000000 and the network URL is set to
\fBnet://127.0.0.1\fR\&.
.RE
.PP
\fB--snapshot\fR
.RS 4
Create the session in
\fIsnapshot mode\fR\&. This is the equivalent of using the
\fB--no-output\fR
option and creating all the channels of this new tracing session in overwrite mode with an
\fBmmap\fR
output type\&.
.RE
.SS "Output"
.PP
\fB--no-output\fR
.RS 4
In
\fIlocal mode\fR, do not output any trace data\&.
.RE
.PP
\fB-o\fR \fIPATH\fR, \fB--output\fR=\fIPATH\fR
.RS 4
In
\fIlocal mode\fR, set trace output path to
\fIPATH\fR\&.
.RE
.PP
\fB--shm-path\fR=\fIPATH\fR
.RS 4
Create shared memory holding buffers at
\fIPATH\fR\&.
.RE
.SS "URL"
.sp
See the \fIURL format\fR section above for more information about the syntax of the following options\*(Aq \fIURL\fR argument\&.
.PP
\fB-C\fR \fIURL\fR, \fB--ctrl-url\fR=\fIURL\fR
.RS 4
Set control path URL to
\fIURL\fR
(must use
\fB--data-url\fR
option also)\&.
.RE
.PP
\fB-D\fR \fIURL\fR, \fB--data-url\fR=\fIURL\fR
.RS 4
Set data path URL to
\fIURL\fR
(must use
\fB--ctrl-url\fR
option also)\&.
.RE
.PP
\fB-U\fR \fIURL\fR, \fB--set-url\fR=\fIURL\fR
.RS 4
Set URL destination of the trace data to
\fIURL\fR\&. It is persistent for the session lifetime\&. This option sets both data (\fB--data-url\fR
option) and control (\fB--ctrl-url\fR
option) URLs at the same time\&.
.sp
In
\fIlocal\fR
mode,
\fIURL\fR
must start with
\fBfile://\fR
followed by the destination path on the local file system\&.
.RE
.SS "Program information"
.PP
\fB-h\fR, \fB--help\fR
.RS 4
Show command help\&.
.sp
This option, like
\fBlttng-help\fR(1), attempts to launch
\fB/usr/bin/man\fR
to view the command\(cqs man page\&. The path to the man pager can be overridden by the
\fBLTTNG_MAN_BIN_PATH\fR
environment variable\&.
.RE
.PP
\fB--list-options\fR
.RS 4
List available command options\&.
.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/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 <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
.\}
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 "SEE ALSO"
.sp
\fBlttng-destroy\fR(1), \fBlttng-set-session\fR(1), \fBlttng\fR(1)