lttng-event-rule - Man Page

For LTTng to emit an event ​E, ​E must satisfy all the conditions of an event rule, that is:

• The instrumentation point from which LTTng creates ​E has a specific type​.

  See the “Instrumentation point type condition” section below​.

• A pattern matches the name of ​E while another pattern doesn’t​.

  See the “Event name condition” section below​.

• The log level of the instrumentation point from which LTTng creates ​E is at least as severe as some value, or is exactly some value​.

  See the “Instrumentation point log level condition” section below​.

• The fields of the payload of ​E and the current context fields satisfy a filter expression​.

  See the “Event payload and context filter condition” section below​.

The dedicated command-line options of most conditions are optional: if you don’t specify the option, the associated condition is always satisfied​.

An event ​E satisfies the instrumentation point type condition of an event rule if the instrumentation point from which LTTng creates ​E is, depending on the argument of the --type option:

kernel:tracepoint

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​.

List the available Linux kernel tracepoints with lttng list --kernel​. See lttng-list(1) to learn more​.

kernel:syscall:entry, kernel:syscall:exit, kernel:syscall:entry+exit

The entry, exit, or entry and exit of a Linux kernel system call​.

List the available Linux kernel system call instrumentation points with lttng list --kernel --syscall​. See lttng-list(1) to learn more​.

kernel:kprobe

A Linux kprobe, that is, a single probe dynamically placed in the compiled kernel code​.

You must specify the kprobe location with the --location option​.

The payload of a Linux kprobe event is empty​.

kernel:uprobe

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​.

LTTng ​2​.16​.0 supports the ELF and SystemTap User-level Statically Defined Tracing (USDT; a DTrace-style marker) probing methods​. LTTng only supports USDT probes which are NOT reference-counted​.

You must specify the user space probe location with the --location option​.

The payload of a Linux user space probe event is empty​.

user:tracepoint

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​.

List the available user space tracepoints with lttng list --userspace​. See lttng-list(1) to learn more​.

jul:logging

A java.util.logging logging statement​.

List the available java.util.logging loggers with lttng list --jul​. See lttng-list(1) to learn more​.

log4j:logging

An Apache log4j ​1​.x logging statement​.

List the available Apache log4j ​1​.x loggers with lttng list --log4j​. See lttng-list(1) to learn more​.

log4j2:logging

An Apache Log4j ​2 logging statement​.

List the available Apache Log4j ​2 loggers with lttng list --log4j2​. See lttng-list(1) to learn more​.

python:logging

A Python logging statement​.

List the available Python loggers with lttng list --python​. See lttng-list(1) to learn more​.

An event ​E satisfies the event name condition of an event rule ​ER if the two following statements are true:

• You don’t specify any --exclude-name=XNAME option or none of the XNAME arguments matches the full name of the user space tracepoint from which LTTng creates ​E​.

  The --exclude-name option is only available with the --type=user:tracepoint 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 \*​.
Important

As of LTTng ​2​.16​.0, not specifying the --name option is equivalent to specifying --name='*´, but this default may change in the future​.

An event ​E satisfies the instrumentation point log level condition of an event rule if either:

• You specify the --log-level=.. option or you don’t specify the --log-level option​.

  Defaulting to --log-level=.. when you don’t specify the --log-level option is specific to LTTng ​2​.16​.0 and may change in the future​.

As of LTTng ​2​.16​.0, the ..LOGLEVEL and LOGLEVEL..LOGLEVEL formats are NOT supported​.

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 argument of the --type option, from the most to the least severe:

user:tracepoint

• EMERG (0)
• ALERT (1)
• CRIT (2)
• ERR (3)
• WARNING (4)
• NOTICE (5)
• INFO (6)
• DEBUG_SYSTEM (7)
• DEBUG_PROGRAM (8)
• DEBUG_PROCESS (9)
• DEBUG_MODULE (10)
• DEBUG_UNIT (11)
• DEBUG_FUNCTION (12)
• DEBUG_LINE (13)
• DEBUG (14)

jul:logging

• OFF (INT32_MAX)
• SEVERE (1000)
• WARNING (900)
• INFO (800)
• CONFIG (700)
• FINE (500)
• FINER (400)
• FINEST (300)
• ALL (INT32_MIN)

log4j:logging

• OFF (INT32_MAX)
• FATAL (50000)
• ERROR (40000)
• WARN (30000)
• INFO (20000)
• DEBUG (10000)
• TRACE (5000)
• ALL (INT32_MIN)

log4j2:logging

• OFF (0)
• FATAL (100)
• ERROR (200)
• WARN (300)
• INFO (400)
• DEBUG (500)
• TRACE (600)
• ALL (INT32_MAX)

python:logging

• CRITICAL (50)
• ERROR (40)
• WARNING (30)
• INFO (20)
• DEBUG (10)
• NOTSET (0)

An event ​E satisfies the event payload and context filter condition of an 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

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:

• A NAME expression identifies an event payload field named NAME (a C ​identifier)​.

  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]​.

• A $ctx.TYPE expression identifies the statically-known context field having the type TYPE (a C ​identifier)​.

  List the available statically-known context field names with the lttng-add-context(1) command​. As of LTTng ​2​.16​.0, context field names starting with perf: aren’t supported​.

  When a field expression doesn’t exist, EXPR is false​.

  Examples: $ctx.prio, $ctx.gid, $ctx.preemptible​.

• A $app.PROVIDER:TYPE expression identifies the application-specific context field having the type TYPE (a C ​identifier) from the provider PROVIDER (a C ​identifier)​.

  When a field expression doesn’t exist, EXPR is false​.

  Example: $app.server:cur_user​.

• Compare strings, either string fields or string literals (double-quoted), with the == and != operators​.

  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.*"​.

• The precedence table of the operators which are supported in EXPR is as follows​. In this table, the highest precedence is ​1:

  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

  Unlike the C ​language, the bitwise AND and OR operators (& and |) in EXPR take precedence over relational operators (<, <=, >, >=, ==, and !=)​. This means the expression 2 & 2 == 2 is true while the equivalent C ​expression is false​.

  The arithmetic operators are NOT supported​.

  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​.

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

Since LTTng ​2​.13, what this manual page documents is the standard, common way to specify an LTTng event rule​.

With the lttng-enable-event(1) command, you also specify an event rule, but with deprecated options and arguments​.

The following table shows how to translate from the lttng-enable-event(1) options and arguments to the common event rule specification options:

See the “Instrumentation point type condition” section above​.

-E NAME, --event-name=NAME

With the --type=kernel:kprobe or --type=kernel:uprobe option, set the name of the emitted events to NAME instead of the LOC argument of the --location=LOC option​.

Defaulting to LOC is specific to LTTng ​2​.16​.0 and may change in the future​.

-L LOC, --location=LOC

With the --type=kernel:kprobe option

Set the location of the Linux kprobe to insert to LOC​.

LOC is one of:

• An address (0x hexadecimal prefix supported)​.
• A symbol name​.
• A symbol name and an offset (SYMBOL+OFFSET format)​.

With the --type=kernel:uprobe option

Set the location of the user space probe to insert to LOC​.

LOC is one of:

[elf:]PATH:SYMBOL

An available symbol within a user space application or library​.

PATH

Application or library path​.

One of:

• An absolute path​.
• A relative path​.
• The name of an application as found in the directories listed in the PATH environment variable​.

SYMBOL

Symbol name of the function of which to instrument the entry​.

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​.16​.0, not specifying elf: is equivalent to specifying it, but this default may change in the future​.

Examples:

• /usr/lib/libc.so.6:malloc
• ./myapp:createUser
• elf:httpd:ap_run_open_htaccess

sdt:PATH:PROVIDER:NAME

A SystemTap User-level Statically Defined Tracing (USDT) probe within a user space application or library​.

PATH

Application or library path​.

This can be:

• An absolute path​.
• A relative path​.
• The name of an application as found in the directories listed in the PATH environment variable​.

PROVIDER, NAME

USDT provider and probe names​.

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: sdt:./build/server:server:accept_request

-t TYPE, --type=TYPE

Only match events which LTTng creates from an instrumentation point having the type TYPE​.

TYPE is one of:

kernel:tracepoint

LTTng kernel tracepoint​.

As of LTTng ​2​.16​.0, kernel is an alias, but this may change in the future​.

user:tracepoint

LTTng user space tracepoint​.

As of LTTng ​2​.16​.0, user is an alias, but this may change in the future​.

kernel:syscall:entry

Linux system call entry​.

As of LTTng ​2​.16​.0, syscall:entry is an alias, but this may change in the future​.

kernel:syscall:exit

Linux system call exit​.

As of LTTng ​2​.16​.0, syscall:exit is an alias, but this may change in the future​.

kernel:syscall:entry+exit

Linux system call entry and exit (two distinct instrumentation points)​.

As of LTTng ​2​.16​.0, the following are aliases, but this may change in the future:

• syscall:entry+exit
• kernel:syscall
• syscall

kernel:kprobe

Linux kprobe​.

As of LTTng ​2​.16​.0, kprobe is an alias, but this may change in the future​.

You must specify the location of the kprobe to insert with the --location option​.

You may specify the name of the emitted events with the --event-name option​.

kernel:uprobe

Linux user space probe​.

You must specify the location of the user space probe to insert with the --location option​.

You may specify the name of the emitted events with the --event-name option​.

jul:logging

java.util.logging logging statement​.

As of LTTng ​2​.16​.0, jul is an alias, but this may change in the future​.

log4j:logging

Apache log4j ​1​.x logging statement​.

As of LTTng ​2​.16​.0, log4j is an alias, but this may change in the future​.

log4j2:logging

Apache Log4j ​2 logging statement​.

As of LTTng ​2​.16​.0, log4j2 is an alias, but this may change in the future​.

python:logging

Python logging statement​.

As of LTTng ​2​.16​.0, python is an alias, but this may change in the future​.

See the “Event name condition” section above​.

-n NAME, --name=NAME

Only match events of which NAME matches, depending on the argument of the --type option:

kernel:tracepoint, user:tracepoint

The full name of the LTTng tracepoint​.

jul:logging, log4j:logging, log4j2:logging, python:logging

The Java or Python logger name​.

kernel:syscall:entry, kernel:syscall:exit, kernel:syscall:entry+exit

The name of the system call, without any sys_ prefix​.

This option is NOT available with other instrumentation point types​.

As of LTTng ​2​.16​.0, not specifying this option is equivalent to specifying --name='*´ (when it applies), but this default may change in the future​.

-x XNAME, --exclude-name=XNAME

Only match events of which XNAME does NOT match the full name of the LTTng user space tracepoint​.

Only available with the --type=user:tracepoint option​.

NAME and XNAME are globbing patterns: the * character means “match anything”​. To match a literal * character, use \*​.

See the “Instrumentation point log level condition” section above​.

-l LOGLEVELSPEC, --log-level=LOGLEVELSPEC

Only match events of which the log level of the LTTng tracepoint or logging statement is, depending on the format of LOGLEVELSPEC:

LOGLEVEL..

At least as severe as LOGLEVEL​.

LOGLEVEL

Exactly LOGLEVEL​.

..

Anything​.

This option is NOT available with the following options:

• --type=kernel:tracepoint
• --type=kernel:syscall:entry
• --type=kernel:syscall:exit
• --type=kernel:syscall:entry+exit
• --type=kernel:kprobe

• --type=kernel:uprobe

  As of LTTng ​2​.16​.0, not specifying this option is equivalent to specifying --log-level=.. (when it applies), but this default may change in the future​.

See the “Event payload and context filter condition” section above​.

-f EXPR, --filter=EXPR

Only match events of which EXPR, which can contain references to event payload and current context fields, is true​.

This option is only available with the following options:

• --type=kernel:tracepoint
• --type=kernel:syscall:entry
• --type=kernel:syscall:exit
• --type=kernel:syscall:entry+exit