'\" t
.\"     Title: lttng-enable-event
.\"    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\-ENABLE\-EVENT" "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-enable-event \- Create or enable LTTng recording event rules
.SH "SYNOPSIS"
.sp
Create or enable one or more recording event rules to match Linux kernel tracepoint or system call events:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-event\fR \fB--kernel\fR [\fB--tracepoint\fR | \fB--syscall\fR]
      (\fB--all\fR | \fINAME\fR[,\fINAME\fR]\&...) [\fB--filter\fR=\fIEXPR\fR]
      [\fB--session\fR=\fISESSION\fR] [\fB--channel\fR=\fICHANNEL\fR]
.fi
.sp
Create or enable a recording event rule to match Linux kernel events created from a dynamic instrumentation point:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-event\fR \fB--kernel\fR
      (\fB--probe\fR=\fILOC\fR | \fB--function\fR=\fILOC\fR | \fB--userspace-probe\fR=\fILOC\fR) \fIRECORDNAME\fR
      [\fB--session\fR=\fISESSION\fR] [\fB--channel\fR=\fICHANNEL\fR]
.fi
.sp
Create or enable one or more recording event rules to match user space tracepoint events:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-event\fR \fB--userspace\fR [\fB--tracepoint\fR]
      (\fB--all\fR | \fINAME\fR[,\fINAME\fR]\&...) [\fB--exclude\fR=\fIXNAME\fR[,\fIXNAME\fR]\&...]
      [\fB--loglevel\fR=\fILOGLEVEL\fR | \fB--loglevel-only\fR=\fILOGLEVEL\fR] [\fB--filter\fR=\fIEXPR\fR]
      [\fB--session\fR=\fISESSION\fR] [\fB--channel\fR=\fICHANNEL\fR]
.fi
.sp
Create or enable one or more recording event rules to match Java/Python logging events:
.sp
.nf
\fBlttng\fR [\fIGENERAL OPTIONS\fR] \fBenable\-event\fR (\fB--jul\fR | \fB--log4j\fR | \fB--python\fR)
      [\fB--tracepoint\fR] (\fB--all\fR | \fINAME\fR[,\fINAME\fR]\&...)
      [\fB--loglevel\fR=\fILOGLEVEL\fR | \fB--loglevel-only\fR=\fILOGLEVEL\fR] [\fB--filter\fR=\fIEXPR\fR]
      [\fB--session\fR=\fISESSION\fR] [\fB--channel\fR=\fICHANNEL\fR]
.fi
.SH "DESCRIPTION"
.sp
The \fBlttng enable-event\fR command does one of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Create one or more recording event rules\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Enable one or more disabled recording event rules\&.
.sp
See the \(lqEnable a disabled recording event rule\(rq section below\&.
.RE
.sp
See \fBlttng-concepts\fR(7) to learn more about instrumentation points, events, recording event rules, and event records\&.
.sp
The recording event rule(s) to create or enable belong to:
.PP
With the \fB--session\fR=\fISESSION\fR option
.RS 4
The recording session named
\fISESSION\fR\&.
.RE
.PP
Without the \fB--session\fR option
.RS 4
The current recording session (see
\fBlttng-concepts\fR(7)
to learn more about the current recording session)\&.
.RE
.PP
With the \fB--channel\fR=\fICHANNEL\fR option
.RS 4
The channel named
\fICHANNEL\fR\&.
.RE
.PP
Without the \fB--channel\fR option
.RS 4
The channel named
\fBchannel0\fR\&.
.sp
If there\(cqs already a channel for the selected recording session and domain which isn\(cqt named
\fBchannel0\fR, the
\fBenable-event\fR
command fails\&. Otherwise, it automatically creates it\&.
.RE
.sp
See the \(lqEXAMPLES\(rq section below for usage examples\&.
.sp
List the recording event rules of a specific recording session and/or channel with the \fBlttng-list\fR(1) and \fBlttng-status\fR(1) commands\&.
.sp
Disable an enabled recording event rule with the \fBlttng-disable-event\fR(1) command\&.
.SS "Overview of recording event rule conditions"
.sp
For LTTng to emit and record an event\ \&\fIE\fR,\ \&\fIE\fR must satisfy \fBall\fR the conditions of a recording event rule\ \&\fIER\fR, that is:
.PP
Explicit conditions
.RS 4
You set the following conditions when you create or enable\ \&\fIER\fR
with the
\fBenable-event\fR
command:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The instrumentation point type from which LTTng creates\ \&\fIE\fR
has a specific type\&.
.sp
See the \(lqInstrumentation point type condition\(rq section below\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A pattern matches the name of\ \&\fIE\fR
while another pattern doesn\(cqt\&.
.sp
See the \(lqEvent name condition\(rq section below\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The log level of the instrumentation point from which LTTng creates\ \&\fIE\fR
is at least as severe as some value, or is exactly some value\&.
.sp
See the \(lqInstrumentation point log level condition\(rq section below\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The fields of the payload of\ \&\fIE\fR
and the current context fields satisfy a filter expression\&.
.sp
See the \(lqEvent payload and context filter condition\(rq section below\&.
.RE
.RE
.PP
Implicit conditions
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIER\fR
itself is enabled\&.
.sp
A recording event rule is enabled on creation\&.
.sp
Enable a disabled recording event rule with the
\fBenable-event\fR
command\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The channel to which\ \&\fIER\fR
is attached is enabled\&.
.sp
A channel is enabled on creation\&.
.sp
Enable a disabled channel with the
\fBlttng-enable-channel\fR(1)
command\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The recording session of\ \&\fIER\fR
is active (started)\&.
.sp
A recording session is inactive (stopped) on creation\&.
.sp
Start an inactive recording session with the
\fBlttng-start\fR(1)
command\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The process for which LTTng creates\ \&\fIE\fR
is allowed to record events\&.
.sp
All processes are allowed to record events on recording session creation\&.
.sp
Use the
\fBlttng-track\fR(1)
and
\fBlttng-untrack\fR(1)
commands to select which processes are allowed to record events based on specific process attributes\&.
.RE
.RE
.sp
The dedicated command\-line options of most conditions are optional: if you don\(cqt specify the option, the associated condition is always satisfied\&.
.SS "Instrumentation point type condition"
.sp
An event\ \&\fIE\fR satisfies the instrumentation point type condition of a recording event rule if the instrumentation point from which LTTng creates\ \&\fIE\fR is:
.PP
For the Linux kernel tracing domain (\fB--kernel\fR option)
.RS 4
.PP
With the \fB--tracepoint\fR option or without any other instrumentation point type option
.RS 4
An LTTng kernel tracepoint, that is, a statically defined point in the source code of the kernel image or of a kernel module with LTTng kernel tracer macros\&.
.sp
As of LTTng\ \&2\&.13\&.11, this is the default instrumentation point type of the Linux kernel tracing domain, but this may change in the future\&.
.sp
List the available Linux kernel tracepoints with
\fBlttng list --kernel\fR\&. See
\fBlttng-list\fR(1)
to learn more\&.
.RE
.PP
With the \fB--syscall\fR option
.RS 4
The entry and exit of a Linux kernel system call\&.
.sp
List the available Linux kernel system call instrumentation points with
\fBlttng list --kernel --syscall\fR\&. See
\fBlttng-list\fR(1)
to learn more\&.
.RE
.PP
With the \fB--probe\fR option
.RS 4
A Linux kprobe, that is, a single probe dynamically placed in the compiled kernel code\&.
.sp
The argument of the
\fB--probe\fR
option is the location of the kprobe to insert, either a symbol or a memory address, while
\fIRECORDNAME\fR
is the name of the record of\ \&\fIE\fR
(see the \(lqEvent record name\(rq section below)\&.
.sp
The payload of a Linux kprobe event is empty\&.
.RE
.PP
With the \fB--userspace-probe\fR option
.RS 4
A Linux user space probe, that is, a single probe dynamically placed at the entry of a compiled user space application/library function through the kernel\&.
.sp
The argument of the
\fB--userspace-probe\fR
option is the location of the user space probe to insert, one of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A path and symbol (ELF method)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A path, provider name, and probe name (SystemTap User\-level Statically Defined Tracing (USDT) method; a DTrace\-style marker)\&.
.sp
As of LTTng\ \&2\&.13\&.11, LTTng only supports USDT probes which are NOT reference\-counted\&.
.RE
.sp
\fIRECORDNAME\fR
is the name of the record of\ \&\fIE\fR
(see the \(lqEvent record name\(rq section below)\&.
.sp
The payload of a Linux user space probe event is empty\&.
.RE
.PP
With the \fB--function\fR option
.RS 4
A Linux kretprobe, that is, two probes dynamically placed at the entry and exit of a function in the compiled kernel code\&.
.sp
The argument of the
\fB--function\fR
option is the location of the Linux kretprobe to insert, either a symbol or a memory address, while
\fIRECORDNAME\fR
is the name of the record of\ \&\fIE\fR
(see the \(lqEvent record name\(rq section below)\&.
.sp
The payload of a Linux kretprobe event is empty\&.
.RE
.RE
.PP
For the user space tracing domain (\fB--userspace\fR option)
.RS 4
.PP
With or without the \fB--tracepoint\fR option
.RS 4
An LTTng user space tracepoint, that is, a statically defined point in the source code of a C/C++ application/library with LTTng user space tracer macros\&.
.sp
As of LTTng\ \&2\&.13\&.11, this is the default and sole instrumentation point type of the user space tracing domain, but this may change in the future\&.
.sp
List the available user space tracepoints with
\fBlttng list --userspace\fR\&. See
\fBlttng-list\fR(1)
to learn more\&.
.RE
.RE
.PP
For the \fBjava.util.logging\fR (\fB--jul\fR option), Apache log4j (\fB--log4j\fR option), and Python (\fB--python\fR option) tracing domains
.RS 4
.PP
With or without the \fB--tracepoint\fR option
.RS 4
A logging statement\&.
.sp
As of LTTng\ \&2\&.13\&.11, this is the default and sole instrumentation point type of the
\fBjava.util.logging\fR, Apache log4j, and Python tracing domains, but this may change in the future\&.
.sp
List the available Java and Python loggers with
\fBlttng list --jul\fR,
\fBlttng list --log4j\fR, and
\fBlttng list --python\fR\&. See
\fBlttng-list\fR(1)
to learn more\&.
.RE
.RE
.SS "Event name condition"
.sp
An event\ \&\fIE\fR satisfies the event name condition of a recording event rule\ \&\fIER\fR if the two 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--all\fR
option or, depending on the instrumentation type condition (see the \(lqInstrumentation point type condition\(rq section above) of\ \&\fIER\fR,
\fINAME\fR
matches:
.PP
LTTng tracepoint
.RS 4
The full name of the tracepoint from which LTTng creates\ \&\fIE\fR\&.
.sp
Note that the full name of a user space tracepoint is
\fIPROVIDER\fR\fB:\fR\fINAME\fR, where
\fIPROVIDER\fR
is the tracepoint provider name and
\fINAME\fR
is the tracepoint name\&.
.RE
.PP
Logging statement
.RS 4
The name of the Java or Python logger from which LTTng creates\ \&\fIE\fR\&.
.RE
.PP
Linux system call
.RS 4
The name of the system call, without any
\fBsys_\fR
prefix, from which LTTng creates\ \&\fIE\fR\&.
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
You don\(cqt specify the
\fB--exclude\fR=\fIXNAME\fR[\fB,\fR\fIXNAME\fR]\&... option or, depending on the instrumentation type condition of\ \&\fIER\fR, none of the
\fIXNAME\fR
arguments matches the full name of the user space tracepoint from which LTTng creates\ \&\fIE\fR\&.
.sp
The
\fB--exclude\fR
option is only available with the
\fB--userspace\fR
option\&.
.RE
.sp
This condition is only meaningful for the LTTng tracepoint, logging statement, and Linux system call instrumentation point types: it\(cqs always satisfied for the other types\&.
.sp
In all cases, \fINAME\fR and \fIXNAME\fR are globbing patterns: the \fB*\fR character means \(lqmatch anything\(rq\&. To match a literal \fB*\fR character, use \fB\e*\fR\&. To match a literal \fB,\fR character, use \fB\e,\fR\&.
.if n \{\
.sp
.\}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.RS 4
.sp
Make sure to \fBsingle\-quote\fR \fINAME\fR and \fIXNAME\fR when they contain the \fB*\fR character and when you run the \fBenable-event\fR command from a shell\&.
.sp .5v
.RE
.sp
With the LTTng tracepoint, logging statement, and Linux system call instrumentation point types, the \fBenable-event\fR command creates or enables one independent recording event rule per \fINAME\fR argument (non\-option, comma\-separated)\&. With the \fB--all\fR option, the \fBenable-event\fR command creates or enables a single recording event rule\&.
.SS "Instrumentation point log level condition"
.sp
An event\ \&\fIE\fR satisfies the instrumentation point log level condition of a recording event rule if either:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fB--loglevel\fR
and
\fB--loglevel-only\fR
options are missing\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The log level of the LTTng user space tracepoint or logging statement which creates\ \&\fIE\fR
is:
.PP
With the \fB--loglevel\fR=\fILOGLEVEL\fR option
.RS 4
At least as severe as
\fILOGLEVEL\fR\&.
.RE
.PP
With the \fB--loglevel-only\fR=\fILOGLEVEL\fR option
.RS 4
Exactly
\fILOGLEVEL\fR\&.
.RE
.RE
.sp
This condition is only meaningful for the LTTng user space tracepoint and logging statement instrumentation point types: it\(cqs always satisfied for other types\&.
.sp
The available values of \fILOGLEVEL\fR are, depending on the tracing domain, from the most to the least severe:
.PP
User space (\fB--userspace\fR option)
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBEMERG\fR
(0)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBALERT\fR
(1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBCRIT\fR
(2)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBERR\fR
(3)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBWARNING\fR
(4)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBNOTICE\fR
(5)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBINFO\fR
(6)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_SYSTEM\fR
(7)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_PROGRAM\fR
(8)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_PROCESS\fR
(9)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_MODULE\fR
(10)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_UNIT\fR
(11)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_FUNCTION\fR
(12)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG_LINE\fR
(13)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG\fR
(14)
.RE
.RE
.PP
\fBjava.util.logging\fR (\fB--jul\fR option)
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBOFF\fR
(\fBINT32_MAX\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBSEVERE\fR
(1000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBWARNING\fR
(900)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBINFO\fR
(800)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBCONFIG\fR
(700)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBFINE\fR
(500)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBFINER\fR
(400)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBFINEST\fR
(300)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBALL\fR
(\fBINT32_MIN\fR)
.RE
.RE
.PP
Apache log4j (\fB--log4j\fR option)
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBOFF\fR
(\fBINT32_MAX\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBFATAL\fR
(50000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBERROR\fR
(40000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBWARN\fR
(30000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBINFO\fR
(20000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG\fR
(10000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBTRACE\fR
(5000)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBALL\fR
(\fBINT32_MIN\fR)
.RE
.RE
.PP
Python (\fB--python\fR option)
.RS 4
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBCRITICAL\fR
(50)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBERROR\fR
(40)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBWARNING\fR
(30)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBINFO\fR
(20)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDEBUG\fR
(10)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBNOTSET\fR
(0)
.RE
.RE
.SS "Event payload and context filter condition"
.sp
An event\ \&\fIE\fR satisfies the event payload and context filter condition of a recording event rule if the \fB--filter\fR=\fIEXPR\fR option is missing or if \fIEXPR\fR is \fItrue\fR\&.
.sp
This condition is only meaningful for the LTTng tracepoint and Linux system call instrumentation point types: it\(cqs always satisfied for other types\&.
.sp
\fIEXPR\fR can contain references to the payload fields of\ \&\fIE\fR and to the current context fields\&.
.if n \{\
.sp
.\}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.RS 4
.sp
Make sure to \fBsingle\-quote\fR \fIEXPR\fR when you run the \fBenable-event\fR command from a shell, as filter expressions typically include characters having a special meaning for most shells\&.
.sp .5v
.RE
.sp
The expected syntax of \fIEXPR\fR is similar to the syntax of a C\ \&language conditional expression (an expression which an \fBif\fR statement can evaluate), but there are a few differences:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A
\fINAME\fR
expression identifies an event payload field named
\fINAME\fR
(a C\ \&identifier)\&.
.sp
Use the C\ \&language dot and square bracket notations to access nested structure and array/sequence fields\&. You can only use a constant, positive integer number within square brackets\&. If the index is out of bounds,
\fIEXPR\fR
is
\fIfalse\fR\&.
.sp
The value of an enumeration field is an integer\&.
.sp
When a field expression doesn\(cqt exist,
\fIEXPR\fR
is
\fIfalse\fR\&.
.sp
Examples:
\fBmy_field\fR,
\fBtarget_cpu\fR,
\fBseq[7]\fR,
\fBmsg.user[1].data[2][17]\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A
\fB$ctx.\fR\fITYPE\fR
expression identifies the statically\-known context field having the type
\fITYPE\fR
(a C\ \&identifier)\&.
.sp
List the available statically\-known context field names with the
\fBlttng-add-context\fR(1)
command\&.
.sp
When a field expression doesn\(cqt exist,
\fIEXPR\fR
is
\fIfalse\fR\&.
.sp
Examples:
\fB$ctx.prio\fR,
\fB$ctx.preemptible\fR,
\fB$ctx.perf:cpu:stalled-cycles-frontend\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A
\fB$app.\fR\fIPROVIDER\fR\fB:\fR\fITYPE\fR
expression identifies the application\-specific context field having the type
\fITYPE\fR
(a C\ \&identifier) from the provider
\fIPROVIDER\fR
(a C\ \&identifier)\&.
.sp
When a field expression doesn\(cqt exist,
\fIEXPR\fR
is
\fIfalse\fR\&.
.sp
Example:
\fB$app.server:cur_user\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Compare strings, either string fields or string literals (double\-quoted), with the
\fB==\fR
and
\fB!=\fR
operators\&.
.sp
When comparing to a string literal, the
\fB*\fR
character means \(lqmatch anything\(rq\&. To match a literal
\fB*\fR
character, use
\fB\e*\fR\&.
.sp
Examples:
\fBmy_field == "user34"\fR,
\fBmy_field == my_other_field\fR,
\fBmy_field == "192.168.*"\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The precedence table of the operators which are supported in
\fIEXPR\fR
is as follows\&. In this table, the highest precedence is\ \&1:
.TS
allbox tab(:);
ltB ltB ltB ltB.
T{
Precedence
T}:T{
Operator
T}:T{
Description
T}:T{
Associativity
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 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
lt lt lt lt
lt lt lt lt
lt lt lt lt
lt lt lt lt.
T{
1
T}:T{
\fB-\fR
T}:T{
Unary minus
T}:T{
Right\-to\-left
T}
T{
1
T}:T{
\fB+\fR
T}:T{
Unary plus
T}:T{
Right\-to\-left
T}
T{
1
T}:T{
\fB!\fR
T}:T{
Logical NOT
T}:T{
Right\-to\-left
T}
T{
1
T}:T{
\fB~\fR
T}:T{
Bitwise NOT
T}:T{
Right\-to\-left
T}
T{
2
T}:T{
\fB<<\fR
T}:T{
Bitwise left shift
T}:T{
Left\-to\-right
T}
T{
2
T}:T{
\fB>>\fR
T}:T{
Bitwise right shift
T}:T{
Left\-to\-right
T}
T{
3
T}:T{
\fB&\fR
T}:T{
Bitwise AND
T}:T{
Left\-to\-right
T}
T{
4
T}:T{
\fB^\fR
T}:T{
Bitwise XOR
T}:T{
Left\-to\-right
T}
T{
5
T}:T{
\fB|\fR
T}:T{
Bitwise OR
T}:T{
Left\-to\-right
T}
T{
6
T}:T{
\fB<\fR
T}:T{
Less than
T}:T{
Left\-to\-right
T}
T{
6
T}:T{
\fB<=\fR
T}:T{
Less than or equal to
T}:T{
Left\-to\-right
T}
T{
6
T}:T{
\fB>\fR
T}:T{
Greater than
T}:T{
Left\-to\-right
T}
T{
6
T}:T{
\fB>=\fR
T}:T{
Greater than or equal to
T}:T{
Left\-to\-right
T}
T{
7
T}:T{
\fB==\fR
T}:T{
Equal to
T}:T{
Left\-to\-right
T}
T{
7
T}:T{
\fB!=\fR
T}:T{
Not equal to
T}:T{
Left\-to\-right
T}
T{
8
T}:T{
\fB&&\fR
T}:T{
Logical AND
T}:T{
Left\-to\-right
T}
T{
9
T}:T{
\fB||\fR
T}:T{
Logical OR
T}:T{
Left\-to\-right
T}
.TE
.sp 1
Parentheses are supported to bypass the default order\&.
.if n \{\
.sp
.\}
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.RS 4
Unlike the C\ \&language, the bitwise AND and OR operators (\fB&\fR
and
\fB|\fR) in
\fIEXPR\fR
take precedence over relational operators (\fB<\fR,
\fB<=\fR,
\fB>\fR,
\fB>=\fR,
\fB==\fR, and
\fB!=\fR)\&. This means the expression
\fB2 & 2 == 2\fR
is
\fItrue\fR
while the equivalent C\ \&expression is
\fIfalse\fR\&.
.sp .5v
.RE
The arithmetic operators are NOT supported\&.
.sp
LTTng first casts all integer constants and fields to signed 64\-bit integers\&. The representation of negative integers is two\(cqs complement\&. This means that, for example, the signed 8\-bit integer field 0xff (\-1) becomes 0xffffffffffffffff (still \-1) once casted\&.
.sp
Before a bitwise operator is applied, LTTng casts all its operands to unsigned 64\-bit integers, and then casts the result back to a signed 64\-bit integer\&. For the bitwise NOT operator, it\(cqs the equivalent of this C\ \&expression:
.sp
.if n \{\
.RS 4
.\}
.nf
(int64_t) ~((uint64_t) val)
.fi
.if n \{\
.RE
.\}
.sp
For the binary bitwise operators, it\(cqs the equivalent of those C\ \&expressions:
.sp
.if n \{\
.RS 4
.\}
.nf
(int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
(int64_t) ((uint64_t) lhs << (uint64_t) rhs)
(int64_t) ((uint64_t) lhs & (uint64_t) rhs)
(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
(int64_t) ((uint64_t) lhs | (uint64_t) rhs)
.fi
.if n \{\
.RE
.\}
.sp
If the right\-hand side of a bitwise shift operator (\fB<<\fR
and
\fB>>\fR) is not in the [0,\ \&63] range, then
\fIEXPR\fR
is
\fIfalse\fR\&.
.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
Use the \fBlttng-track\fR(1) and \fBlttng-untrack\fR(1) commands to allow or disallow processes to record LTTng events based on their attributes instead of using equivalent statically\-known context fields in \fIEXPR\fR like \fB$ctx.pid\fR\&.
.sp
The former method is much more efficient\&.
.sp .5v
.RE
.sp
\fIEXPR\fR examples:
.sp
.if n \{\
.RS 4
.\}
.nf
msg_id == 23 && size >= 2048
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ctx\&.procname == "lttng*" && (!flag || poel < 34)
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$app\&.my_provider:my_context == 17\&.34e9 || some_enum >= 14
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
$ctx\&.cpu_id == 2 && filename != "*\&.log"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
.fi
.if n \{\
.RE
.\}
.SS "Event record name"
.sp
When LTTng records an event\ \&\fIE\fR, the resulting event record has a name which depends on the instrumentation point type condition (see the \(lqInstrumentation point type condition\(rq section above) of the recording event rule which matched\ \&\fIE\fR:
.PP
LTTng tracepoint (\fB--kernel\fR/\fB--userspace\fR and \fB--tracepoint\fR options)
.RS 4
Full name of the tracepoint from which LTTng creates\ \&\fIE\fR\&.
.sp
Note that the full name of a user space tracepoint is
\fIPROVIDER\fR\fB:\fR\fINAME\fR, where
\fIPROVIDER\fR
is the tracepoint provider name and
\fINAME\fR
is the tracepoint name\&.
.RE
.PP
\fBjava.util.logging\fR logging statement (\fB--jul\fR and \fB--tracepoint\fR options)
.RS 4
\fBlttng_jul:event\fR
.sp
Such an event record has a string field
\fBlogger_name\fR
which contains the name of the
\fBjava.util.logging\fR
logger from which LTTng creates\ \&\fIE\fR\&.
.RE
.PP
Apache log4j logging statement (\fB--log4j\fR and \fB--tracepoint\fR options)
.RS 4
\fBlttng_log4j:event\fR
.sp
Such an event record has a string field
\fBlogger_name\fR
which contains the name of the Apache log4j logger from which LTTng creates\ \&\fIE\fR\&.
.RE
.PP
Python logging statement (\fB--python\fR and \fB--tracepoint\fR options)
.RS 4
\fBlttng_python:event\fR
.sp
Such an event record has a string field
\fBlogger_name\fR
which contains the name of the Python logger from which LTTng creates\ \&\fIE\fR\&.
.RE
.PP
Linux system call (\fB--kernel\fR and \fB--syscall\fR options)
.RS 4
.PP
Entry
.RS 4
\fBsyscall_entry_\fR\fINAME\fR, where
\fINAME\fR
is the name of the system call from which LTTng creates\ \&\fIE\fR, without any
\fBsys_\fR
prefix\&.
.RE
.PP
Exit
.RS 4
\fBsyscall_exit_\fR\fINAME\fR, where
\fINAME\fR
is the name of the system call from which LTTng creates\ \&\fIE\fR, without any
\fBsys_\fR
prefix\&.
.RE
.RE
.PP
Linux kprobe (\fB--kernel\fR and \fB--probe\fR options), Linux user space probe (\fB--kernel\fR and \fB--userspace-probe\fR options)
.RS 4
\fIRECORDNAME\fR
(first non\-option argument)\&.
.RE
.PP
Linux kretprobe (\fB--kernel\fR and \fB--function\fR options)
.RS 4
.PP
Entry
.RS 4
\fIRECORDNAME\fR\fB_entry\fR
.RE
.PP
Exit
.RS 4
\fIRECORDNAME\fR\fB_exit\fR
.RE
.RE
.SS "Enable a disabled recording event rule"
.sp
The \fBenable-event\fR command can enable a disabled recording event rule, as listed in the output of the \fBlttng-list\fR(1) command\&.
.sp
You may enable a disabled recording event rule regardless of the activity (started or stopped) of its recording session (see \fBlttng-start\fR(1) and \fBlttng-stop\fR(1))\&.
.sp
To enable a disabled recording event rule, run the \fBenable-event\fR command with the exact same options and arguments that you used to create it\&. In particular, with the \fB--filter\fR=\fIEXPR\fR option, \fIEXPR\fR must be the exact same string as the one you used on creation\&.
.SH "OPTIONS"
.sp
See \fBlttng\fR(1) for \fIGENERAL OPTIONS\fR\&.
.SS "Tracing domain"
.sp
One of:
.PP
\fB-j\fR, \fB--jul\fR
.RS 4
Create or enable recording event rules in the
\fBjava.util.logging\fR
(JUL) tracing domain\&.
.RE
.PP
\fB-k\fR, \fB--kernel\fR
.RS 4
Create or enable recording event rules in the Linux kernel tracing domain\&.
.RE
.PP
\fB-l\fR, \fB--log4j\fR
.RS 4
Create or enable recording event rules in the Apache log4j tracing domain\&.
.RE
.PP
\fB-p\fR, \fB--python\fR
.RS 4
Create or enable recording event rules in the Python tracing domain\&.
.RE
.PP
\fB-u\fR, \fB--userspace\fR
.RS 4
Create or enable recording event rules in the user space tracing domain\&.
.RE
.SS "Recording target"
.PP
\fB-c\fR \fICHANNEL\fR, \fB--channel\fR=\fICHANNEL\fR
.RS 4
Create or enable recording event rules attached to the channel named
\fICHANNEL\fR
instead of
\fBchannel0\fR\&.
.RE
.PP
\fB-s\fR \fISESSION\fR, \fB--session\fR=\fISESSION\fR
.RS 4
Create or enable recording event rules in the recording session named
\fISESSION\fR
instead of the current recording session\&.
.RE
.SS "Instrumentation point type condition"
.sp
See the \(lqInstrumentation point type condition\(rq section above\&.
.sp
At most one of:
.PP
\fB--function\fR=\fILOC\fR
.RS 4
Only match Linux kretprobe events\&.
.sp
Only available with the
\fB--kernel\fR
option\&.
.sp
\fILOC\fR
is one of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A function address (\fB0x\fR
hexadecimal prefix supported)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A function symbol name\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A function symbol name and an offset (\fISYMBOL\fR\fB+\fR\fIOFFSET\fR
format)\&.
.RE
.sp
You must specify the event record name with
\fIRECORDNAME\fR\&. See the \(lqEvent record name\(rq section above to learn more\&.
.RE
.PP
\fB--probe\fR=\fILOC\fR
.RS 4
Only match Linux kprobe events\&.
.sp
Only available with the
\fB--kernel\fR
option\&.
.sp
\fILOC\fR
is one of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
An address (\fB0x\fR
hexadecimal prefix supported)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A symbol name\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A symbol name and an offset (\fISYMBOL\fR\fB+\fR\fIOFFSET\fR
format)\&.
.RE
.sp
You must specify the event record name with
\fIRECORDNAME\fR\&. See the \(lqEvent record name\(rq section above to learn more\&.
.RE
.PP
\fB--userspace-probe\fR=\fILOC\fR
.RS 4
Only match Linux user space probe events\&.
.sp
Only available with the
\fB--kernel\fR
option\&.
.sp
\fILOC\fR
is one of:
.PP
[\fBelf:\fR]\fIPATH\fR\fB:\fR\fISYMBOL\fR
.RS 4
Probe an available symbol within a user space application or library\&.
.PP
\fIPATH\fR
.RS 4
Application or library path\&.
.sp
One of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
An absolute path\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A relative path\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The name of an application as found in the directories listed in the
\fBPATH\fR
environment variable\&.
.RE
.RE
.PP
\fISYMBOL\fR
.RS 4
Symbol name of the function of which to instrument the entry\&.
.sp
\fISYMBOL\fR
can be any defined code symbol in the output of the
\fBnm\fR(1)
command, including with its
\fB--dynamic\fR
option, which lists dynamic symbols\&.
.RE
.sp
As of LTTng\ \&2\&.13\&.11, not specifying
\fBelf:\fR
is equivalent to specifying it, but this default may change in the future\&.
.sp
Examples:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB--userspace-probe=/usr/lib/libc.so.6:malloc\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB--userspace-probe=./myapp:createUser\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB--userspace-probe=elf:httpd:ap_run_open_htaccess\fR
.RE
.RE
.PP
\fBsdt:\fR\fIPATH\fR\fB:\fR\fIPROVIDER\fR\fB:\fR\fINAME\fR
.RS 4
Use a SystemTap User\-level Statically Defined Tracing (USDT) probe within a user space application or library\&.
.PP
\fIPATH\fR
.RS 4
Application or library path\&.
.sp
This can be:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
An absolute path\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A relative path\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The name of an application as found in the directories listed in the
\fBPATH\fR
environment variable\&.
.RE
.RE
.PP
\fIPROVIDER\fR, \fINAME\fR
.RS 4
USDT provider and probe names\&.
.sp
For example, with the following USDT probe:
.sp
.if n \{\
.RS 4
.\}
.nf
DTRACE_PROBE2("server", "accept_request",
              request_id, ip_addr);
.fi
.if n \{\
.RE
.\}
.sp
The provider/probe name pair is
\fBserver:accept_request\fR\&.
.RE
.sp
Example:
\fB--userspace-probe=sdt:./build/server:server:accept_request\fR
.RE
.sp
You must specify the event record name with
\fIRECORDNAME\fR\&. See the \(lqEvent record name\(rq section above to learn more\&.
.RE
.PP
\fB--syscall\fR
.RS 4
Only match Linux system call events\&.
.sp
Only available with the
\fB--kernel\fR
option\&.
.RE
.PP
\fB--tracepoint\fR
.RS 4
Only match:
.PP
With the \fB--kernel\fR or \fB--userspace\fR option
.RS 4
LTTng tracepoint events\&.
.RE
.PP
With the \fB--jul\fR, \fB--log4j\fR, or \fB--python\fR option
.RS 4
Logging events\&.
.RE
.RE
.sp
With the \fB--kernel\fR, not specifying any of the instrumentation point type options is equivalent to specifying the \fB--tracepoint\fR option, but this default may change in the future\&.
.sp
With the \fB--userspace\fR, \fB--jul\fR, \fB--log4j\fR, and \fB--python\fR options, not specifying the \fB--tracepoint\fR option is equivalent to specifying it, but this default may change in the future\&.
.SS "Event name condition"
.sp
See the \(lqEvent name condition\(rq section above\&.
.PP
\fB-a\fR, \fB--all\fR
.RS 4
Equivalent to a single
\fINAME\fR
argument (LTTng tracepoint or logger name) set to
\fB*\fR
(match anything)\&.
.sp
You may NOT use this option with a
\fINAME\fR
argument\&.
.RE
.PP
\fB-x\fR \fIXNAME\fR[,\fIXNAME\fR]\&..., \fB--exclude\fR=\fIXNAME\fR[,\fIXNAME\fR]\&...
.RS 4
Only match events of which none of the
\fIXNAME\fR
arguments matches the full name of the LTTng user space tracepoint\&.
.sp
Only available with the
\fB--userspace\fR
option\&.
.sp
\fIXNAME\fR
is a globbing pattern: the
\fB*\fR
character means \(lqmatch anything\(rq\&. To match a literal
\fB*\fR
character, use
\fB\e*\fR\&. To match a literal
\fB,\fR
character, use
\fB\e,\fR\&.
.RE
.SS "Instrumentation point log level condition"
.sp
See the \(lqInstrumentation point log level condition\(rq section above\&.
.sp
At most one of:
.PP
\fB--loglevel\fR=\fILOGLEVEL\fR
.RS 4
Only match events of which the log level of the LTTng tracepoint or logging statement is at least as severe as
\fILOGLEVEL\fR\&.
.RE
.PP
\fB--loglevel-only\fR=\fILOGLEVEL\fR
.RS 4
Only match events of which the log level of the LTTng tracepoint or logging statement is exactly
\fILOGLEVEL\fR\&.
.RE
.sp
The instrumentation point log level options above are NOT available with the \fB--kernel\fR option\&.
.SS "Event payload and context filter condition"
.sp
See the \(lqEvent payload and context filter condition\(rq section above\&.
.PP
\fB-f\fR \fIEXPR\fR, \fB--filter\fR=\fIEXPR\fR
.RS 4
Only match events of which
\fIEXPR\fR, which can contain references to event payload and current context fields, is
\fItrue\fR\&.
.sp
This option is only available with the
\fB--tracepoint\fR
or
\fB--syscall\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
.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 "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Create a recording event rule which matches all Linux system call events (current recording session, default channel)\&.\fR
.RS 4
.sp
See the \fB--all\fR and \fB--syscall\fR options\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-kernel \-\-all \-\-syscall
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&2.\ \&Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel)\&.\fR
.RS 4
.sp
The recording event rule below matches all user space tracepoint events of which the name starts with \fBmy_provider:msg\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-userspace \*(Aqmy_provider:msg*\*(Aq
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&3.\ \&Create three recording event rules which match Python logging events named specifically (current recording session, default channel)\&.\fR
.RS 4
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-python server3,ui\&.window,user\-mgmt
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&4.\ \&Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel)\&.\fR
.RS 4
.sp
See the \fB--channel\fR, \fB--all\fR, and \fB--loglevel\fR options\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-log4j \-\-channel=my\-loggers \e
                     \-\-all \-\-loglevel=INFO
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&5.\ \&Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel)\&.\fR
.RS 4
.sp
The recording event rule below matches the entry of \fBusb_disconnect()\fR Linux kernel function calls\&. The records of such events are named \fBusbd\fR (see the \(lqEvent record name\(rq section above)\&.
.sp
See the \fB--probe\fR option\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-kernel \-\-probe=usb_disconnect usbd
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&6.\ \&Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel)\&.\fR
.RS 4
.sp
See the \fB--session\fR and \fB--filter\fR options\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-kernel \-\-session=my\-session \*(Aqsched_*\*(Aq \e
        \-\-filter=\*(Aq$ctx\&.preemptible && comm != "systemd*"\*(Aq
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fBExample\ \&7.\ \&Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel)\&.\fR
.RS 4
.sp
See the \fB--channel\fR option\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ lttng enable\-event \-\-kernel \-\-channel=tva ja,wendy
.fi
.if n \{\
.RE
.\}
.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\fR(1), \fBlttng-disable-event\fR(1), \fBlttng-enable-channel\fR(1), \fBlttng-list\fR(1), \fBlttng-start\fR(1), \fBlttng-track\fR(1), \fBlttng-concepts\fR(7)