table of contents
LTTNG-ENABLE-EVENT(1) | LTTng Manual | LTTNG-ENABLE-EVENT(1) |
NAME¶
lttng-enable-event - Create or enable LTTng recording event rules
SYNOPSIS¶
Create or enable one or more recording event rules to match Linux kernel tracepoint or system call events:
lttng [GENERAL OPTIONS] enable-event --kernel [--tracepoint | --syscall]
(--all | NAME[,NAME]...) [--filter=EXPR]
[--session=SESSION] [--channel=CHANNEL]
Create or enable a recording event rule to match Linux kernel events created from a dynamic instrumentation point:
lttng [GENERAL OPTIONS] enable-event --kernel
(--probe=LOC | --function=LOC | --userspace-probe=LOC) RECORDNAME
[--session=SESSION] [--channel=CHANNEL]
Create or enable one or more recording event rules to match user space tracepoint events:
lttng [GENERAL OPTIONS] enable-event --userspace [--tracepoint]
(--all | NAME[,NAME]...) [--exclude=XNAME[,XNAME]...]
[--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
[--session=SESSION] [--channel=CHANNEL]
Create or enable one or more recording event rules to match Java/Python logging events:
lttng [GENERAL OPTIONS] enable-event (--jul | --log4j | --python)
[--tracepoint] (--all | NAME[,NAME]...)
[--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
[--session=SESSION] [--channel=CHANNEL]
DESCRIPTION¶
The lttng enable-event command does one of:
See the “Enable a disabled recording event rule” section below.
See lttng-concepts(7) to learn more about instrumentation points, events, recording event rules, and event records.
The recording event rule(s) to create or enable belong to:
With the --session=SESSION option
Without the --session option
With the --channel=CHANNEL option
Without the --channel option
If there’s already a channel for the selected recording session and domain which isn’t named channel0, the enable-event command fails. Otherwise, it automatically creates it.
See the “EXAMPLES” section below for usage examples.
List the recording event rules of a specific recording session and/or channel with the lttng-list(1) and lttng-status(1) commands.
Disable an enabled recording event rule with the lttng-disable-event(1) command.
Overview of recording event rule conditions¶
For LTTng to emit and record an event E, E must satisfy all the conditions of a recording event rule ER, that is:
Explicit conditions
See the “Instrumentation point type condition” section below.
See the “Event name condition” section below.
See the “Instrumentation point log level condition” section below.
See the “Event payload and context filter condition” section below.
Implicit conditions
A recording event rule is enabled on creation.
Enable a disabled recording event rule with the enable-event command.
A channel is enabled on creation.
Enable a disabled channel with the lttng-enable-channel(1) command.
A recording session is inactive (stopped) on creation.
Start an inactive recording session with the lttng-start(1) command.
All processes are allowed to record events on recording session creation.
Use the lttng-track(1) and lttng-untrack(1) commands to select which processes are allowed to record events based on specific process attributes.
The dedicated command-line options of most conditions are optional: if you don’t specify the option, the associated condition is always satisfied.
Instrumentation point type condition¶
An event E satisfies the instrumentation point type condition of a recording event rule if the instrumentation point from which LTTng creates E is:
For the Linux kernel tracing domain (--kernel option)
With the --tracepoint option or without any other instrumentation point type option
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.
List the available Linux kernel tracepoints with lttng list --kernel. See lttng-list(1) to learn more.
With the --syscall option
List the available Linux kernel system call instrumentation points with lttng list --kernel --syscall. See lttng-list(1) to learn more.
With the --probe option
The argument of the --probe option is the location of the kprobe to insert, either a symbol or a memory address, while RECORDNAME is the name of the record of E (see the “Event record name” section below).
The payload of a Linux kprobe event is empty.
With the --userspace-probe option
The argument of the --userspace-probe option is the location of the user space probe to insert, one of:
As of LTTng 2.13.11, LTTng only supports USDT probes which are NOT reference-counted.
RECORDNAME is the name of the record of E (see the “Event record name” section below).
The payload of a Linux user space probe event is empty.
With the --function option
The argument of the --function option is the location of the Linux kretprobe to insert, either a symbol or a memory address, while RECORDNAME is the name of the record of E (see the “Event record name” section below).
The payload of a Linux kretprobe event is empty.
For the user space tracing domain (--userspace option)
With or without the --tracepoint option
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.
List the available user space tracepoints with lttng list --userspace. See lttng-list(1) to learn more.
For the java.util.logging (--jul option), Apache log4j (--log4j option), and Python (--python option) tracing domains
With or without the --tracepoint option
As of LTTng 2.13.11, this is the default and sole instrumentation point type of the java.util.logging, Apache log4j, and Python tracing domains, but this may change in the future.
List the available Java and Python loggers with lttng list --jul, lttng list --log4j, and lttng list --python. See lttng-list(1) to learn more.
Event name condition¶
An event E satisfies the event name condition of a recording event rule ER if the two following statements are true:
LTTng tracepoint
Note that the full name of a user space tracepoint is PROVIDER:NAME, where PROVIDER is the tracepoint provider name and NAME is the tracepoint name.
Logging statement
Linux system call
The --exclude option is only available with the --userspace option.
This condition is only meaningful for the LTTng tracepoint, logging statement, and Linux system call instrumentation point types: it’s always satisfied for the other types.
In all cases, NAME and XNAME are globbing patterns: the * character means “match anything”. To match a literal * character, use \*. To match a literal , character, use \,.
Important
Make sure to single-quote NAME and XNAME when they contain the * character and when you run the enable-event command from a shell.
With the LTTng tracepoint, logging statement, and Linux system call instrumentation point types, the enable-event command creates or enables one independent recording event rule per NAME argument (non-option, comma-separated). With the --all option, the enable-event command creates or enables a single recording event rule.
Instrumentation point log level condition¶
An event E satisfies the instrumentation point log level condition of a recording event rule if either:
With the --loglevel=LOGLEVEL option
With the --loglevel-only=LOGLEVEL option
This condition is only meaningful for the LTTng user space tracepoint and logging statement instrumentation point types: it’s always satisfied for other types.
The available values of LOGLEVEL are, depending on the tracing domain, from the most to the least severe:
User space (--userspace option)
java.util.logging (--jul option)
Apache log4j (--log4j option)
Python (--python option)
Event payload and context filter condition¶
An event E satisfies the event payload and context filter condition of a recording event rule if the --filter=EXPR option is missing or if EXPR is true.
This condition is only meaningful for the LTTng tracepoint and Linux system call instrumentation point types: it’s always satisfied for other types.
EXPR can contain references to the payload fields of E and to the current context fields.
Important
Make sure to single-quote EXPR when you run the enable-event command from a shell, as filter expressions typically include characters having a special meaning for most shells.
The expected syntax of EXPR is similar to the syntax of a C language conditional expression (an expression which an if statement can evaluate), but there are a few differences:
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, EXPR is false.
The value of an enumeration field is an integer.
When a field expression doesn’t exist, EXPR is false.
Examples: my_field, target_cpu, seq[7], msg.user[1].data[2][17].
List the available statically-known context field names with the lttng-add-context(1) command.
When a field expression doesn’t exist, EXPR is false.
Examples: $ctx.prio, $ctx.preemptible, $ctx.perf:cpu:stalled-cycles-frontend.
When a field expression doesn’t exist, EXPR is false.
Example: $app.server:cur_user.
When comparing to a string literal, the * character means “match anything”. To match a literal * character, use \*.
Examples: my_field == "user34", my_field == my_other_field, my_field == "192.168.*".
Precedence | Operator | Description | Associativity |
1 | - | Unary minus | Right-to-left |
1 | + | Unary plus | Right-to-left |
1 | ! | Logical NOT | Right-to-left |
1 | ~ | Bitwise NOT | Right-to-left |
2 | << | Bitwise left shift | Left-to-right |
2 | >> | Bitwise right shift | Left-to-right |
3 | & | Bitwise AND | Left-to-right |
4 | ^ | Bitwise XOR | Left-to-right |
5 | | | Bitwise OR | Left-to-right |
6 | < | Less than | Left-to-right |
6 | <= | Less than or equal to | Left-to-right |
6 | > | Greater than | Left-to-right |
6 | >= | Greater than or equal to | Left-to-right |
7 | == | Equal to | Left-to-right |
7 | != | Not equal to | Left-to-right |
8 | && | Logical AND | Left-to-right |
9 | || | Logical OR | Left-to-right |
Parentheses are supported to bypass the default order.
Important
LTTng first casts all integer constants and fields to signed 64-bit integers. The representation of negative integers is two’s complement. This means that, for example, the signed 8-bit integer field 0xff (-1) becomes 0xffffffffffffffff (still -1) once casted.
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’s the equivalent of this C expression:
(int64_t) ~((uint64_t) val)
For the binary bitwise operators, it’s the equivalent of those C expressions:
(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)
If the right-hand side of a bitwise shift operator (<< and >>) is not in the [0, 63] range, then EXPR is false.
Note
Use the lttng-track(1) and lttng-untrack(1) commands to allow or disallow processes to record LTTng events based on their attributes instead of using equivalent statically-known context fields in EXPR like $ctx.pid.
The former method is much more efficient.
EXPR examples:
msg_id == 23 && size >= 2048
$ctx.procname == "lttng*" && (!flag || poel < 34)
$app.my_provider:my_context == 17.34e9 || some_enum >= 14
$ctx.cpu_id == 2 && filename != "*.log"
eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
Event record name¶
When LTTng records an event E, the resulting event record has a name which depends on the instrumentation point type condition (see the “Instrumentation point type condition” section above) of the recording event rule which matched E:
LTTng tracepoint (--kernel/--userspace and --tracepoint options)
Note that the full name of a user space tracepoint is PROVIDER:NAME, where PROVIDER is the tracepoint provider name and NAME is the tracepoint name.
java.util.logging logging statement (--jul and --tracepoint options)
Such an event record has a string field logger_name which contains the name of the java.util.logging logger from which LTTng creates E.
Apache log4j logging statement (--log4j and --tracepoint options)
Such an event record has a string field logger_name which contains the name of the Apache log4j logger from which LTTng creates E.
Python logging statement (--python and --tracepoint options)
Such an event record has a string field logger_name which contains the name of the Python logger from which LTTng creates E.
Linux system call (--kernel and --syscall options)
Entry
Exit
Linux kprobe (--kernel and --probe options), Linux user space probe (--kernel and --userspace-probe options)
Linux kretprobe (--kernel and --function options)
Entry
Exit
Enable a disabled recording event rule¶
The enable-event command can enable a disabled recording event rule, as listed in the output of the lttng-list(1) command.
You may enable a disabled recording event rule regardless of the activity (started or stopped) of its recording session (see lttng-start(1) and lttng-stop(1)).
To enable a disabled recording event rule, run the enable-event command with the exact same options and arguments that you used to create it. In particular, with the --filter=EXPR option, EXPR must be the exact same string as the one you used on creation.
OPTIONS¶
See lttng(1) for GENERAL OPTIONS.
Tracing domain¶
One of:
-j, --jul
-k, --kernel
-l, --log4j
-p, --python
-u, --userspace
Recording target¶
-c CHANNEL, --channel=CHANNEL
-s SESSION, --session=SESSION
Instrumentation point type condition¶
See the “Instrumentation point type condition” section above.
At most one of:
--function=LOC
Only available with the --kernel option.
LOC is one of:
You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.
--probe=LOC
Only available with the --kernel option.
LOC is one of:
You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.
--userspace-probe=LOC
Only available with the --kernel option.
LOC is one of:
[elf:]PATH:SYMBOL
PATH
One of:
SYMBOL
SYMBOL can be any defined code symbol in the output of the nm(1) command, including with its --dynamic option, which lists dynamic symbols.
As of LTTng 2.13.11, not specifying elf: is equivalent to specifying it, but this default may change in the future.
Examples:
sdt:PATH:PROVIDER:NAME
PATH
This can be:
PROVIDER, NAME
For example, with the following USDT probe:
DTRACE_PROBE2("server", "accept_request",
request_id, ip_addr);
The provider/probe name pair is server:accept_request.
Example: --userspace-probe=sdt:./build/server:server:accept_request
You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.
--syscall
Only available with the --kernel option.
--tracepoint
With the --kernel or --userspace option
With the --jul, --log4j, or --python option
With the --kernel, not specifying any of the instrumentation point type options is equivalent to specifying the --tracepoint option, but this default may change in the future.
With the --userspace, --jul, --log4j, and --python options, not specifying the --tracepoint option is equivalent to specifying it, but this default may change in the future.
Event name condition¶
See the “Event name condition” section above.
-a, --all
You may NOT use this option with a NAME argument.
-x XNAME[,XNAME]..., --exclude=XNAME[,XNAME]...
Only available with the --userspace option.
XNAME is a globbing pattern: the * character means “match anything”. To match a literal * character, use \*. To match a literal , character, use \,.
Instrumentation point log level condition¶
See the “Instrumentation point log level condition” section above.
At most one of:
--loglevel=LOGLEVEL
--loglevel-only=LOGLEVEL
The instrumentation point log level options above are NOT available with the --kernel option.
Event payload and context filter condition¶
See the “Event payload and context filter condition” section above.
-f EXPR, --filter=EXPR
This option is only available with the --tracepoint or --syscall option.
Program information¶
-h, --help
This option attempts to launch /usr/bin/man to view this manual page. Override the manual pager path with the LTTNG_MAN_BIN_PATH environment variable.
--list-options
EXIT STATUS¶
0
1
2
3
4
ENVIRONMENT¶
LTTNG_ABORT_ON_ERROR
LTTNG_HOME
Defaults to $HOME.
Useful when the Unix user running the commands has a non-writable home directory.
LTTNG_MAN_BIN_PATH
LTTNG_SESSION_CONFIG_XSD_PATH
LTTNG_SESSIOND_PATH
The --sessiond-path general option overrides this environment variable.
FILES¶
$LTTNG_HOME/.lttngrc
This is where LTTng stores the name of the Unix user’s current recording session between executions of lttng(1). lttng-create(1) and lttng-set-session(1) set the current recording session.
$LTTNG_HOME/lttng-traces
Override this path with the --output option of the lttng-create(1) command.
$LTTNG_HOME/.lttng
$LTTNG_HOME/.lttng/sessions
/usr/local/etc/lttng/sessions
Note
$LTTNG_HOME defaults to the value of the HOME environment variable.
EXAMPLES¶
Example 1. Create a recording event rule which matches all Linux system call events (current recording session, default channel).
See the --all and --syscall options.
$ lttng enable-event --kernel --all --syscall
Example 2. Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel).
The recording event rule below matches all user space tracepoint events of which the name starts with my_provider:msg.
$ lttng enable-event --userspace 'my_provider:msg*'
Example 3. Create three recording event rules which match Python logging events named specifically (current recording session, default channel).
$ lttng enable-event --python server3,ui.window,user-mgmt
Example 4. Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel).
See the --channel, --all, and --loglevel options.
$ lttng enable-event --log4j --channel=my-loggers \
--all --loglevel=INFO
Example 5. Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel).
The recording event rule below matches the entry of usb_disconnect() Linux kernel function calls. The records of such events are named usbd (see the “Event record name” section above).
See the --probe option.
$ lttng enable-event --kernel --probe=usb_disconnect usbd
Example 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).
See the --session and --filter options.
$ lttng enable-event --kernel --session=my-session 'sched_*' \
--filter='$ctx.preemptible && comm != "systemd*"'
Example 7. Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel).
See the --channel option.
$ lttng enable-event --kernel --channel=tva ja,wendy
RESOURCES¶
COPYRIGHT¶
This program is part of the LTTng-tools project.
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 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.
THANKS¶
Special thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for the LTTng journey.
Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases.
SEE ALSO¶
lttng(1), lttng-disable-event(1), lttng-enable-channel(1), lttng-list(1), lttng-start(1), lttng-track(1), lttng-concepts(7)
14 June 2021 | LTTng 2.13.11 |