lttng-enable-event - Man Page

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

Implicit conditions

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 a recording event rule if the instrumentation point from which LTTng creates E is:

For the Linux kernel tracing domain (--kernel option)

For the user space tracing domain (--userspace option)

For the java.util.logging (--jul option), Apache log4j (--log4j option), and Python (--python option) tracing domains

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

• You don’t specify the --exclude=XNAME[,XNAME]... option or, depending on the instrumentation type condition of ER, none of the XNAME arguments matches the full name of the user space tracepoint from which LTTng creates E.

  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

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.

An event E satisfies the instrumentation point log level condition of a recording event rule if either:

• The --loglevel and --loglevel-only options are missing.

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)

• 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)

java.util.logging (--jul option)

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

Apache log4j (--log4j option)

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

Python (--python option)

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

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

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.

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

  Examples: $ctx.prio, $ctx.preemptible, $ctx.perf:cpu:stalled-cycles-frontend.

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

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

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)

Full name of the tracepoint from which LTTng creates E.

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)

lttng_jul:event

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)

lttng_log4j:event

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)

lttng_python:event

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

syscall_entry_NAME, where NAME is the name of the system call from which LTTng creates E, without any sys_ prefix.

Exit

syscall_exit_NAME, where NAME is the name of the system call from which LTTng creates E, without any sys_ prefix.

Linux kprobe (--kernel and --probe options), Linux user space probe (--kernel and --userspace-probe options)

Linux kretprobe (--kernel and --function options)

Entry

RECORDNAME_entry

Exit

RECORDNAME_exit

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.

One of:

-j,  --jul

Create or enable recording event rules in the java.util.logging (JUL) tracing domain.

-k,  --kernel

Create or enable recording event rules in the Linux kernel tracing domain.

-l,  --log4j

Create or enable recording event rules in the Apache log4j tracing domain.

-p,  --python

Create or enable recording event rules in the Python tracing domain.

-u,  --userspace

Create or enable recording event rules in the user space tracing domain.

-c CHANNEL, --channel=CHANNEL

Create or enable recording event rules attached to the channel named CHANNEL instead of channel0.

-s SESSION, --session=SESSION

Create or enable recording event rules in the recording session named SESSION instead of the current recording session.

See the “Instrumentation point type condition” section above.

At most one of:

--function=LOC

Only match Linux kretprobe events.

Only available with the --kernel option.

LOC is one of:

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

You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.

--probe=LOC

Only match Linux kprobe events.

Only available with the --kernel option.

LOC is one of:

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

You must specify the event record name with RECORDNAME. See the “Event record name” section above to learn more.

--userspace-probe=LOC

Only match Linux user space probe events.

Only available with the --kernel option.

LOC is one of:

[elf:]PATH:SYMBOL

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

Examples:

• --userspace-probe=/usr/lib/libc.so.6:malloc
• --userspace-probe=./myapp:createUser
• --userspace-probe=elf:httpd:ap_run_open_htaccess

sdt:PATH:PROVIDER:NAME

Use 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: --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 match Linux system call events.

Only available with the --kernel option.

--tracepoint

Only match:

With the --kernel or --userspace option

LTTng tracepoint events.

With the --jul, --log4j, or --python option

Logging events.

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.

See the “Event name condition” section above.

-a,  --all

Equivalent to a single NAME argument (LTTng tracepoint or logger name) set to * (match anything).

You may NOT use this option with a NAME argument.

-x XNAME[,XNAME]..., --exclude=XNAME[,XNAME]...

Only match events of which none of the XNAME arguments matches the full name of the LTTng user space tracepoint.

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 \,.

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

At most one of:

--loglevel=LOGLEVEL

Only match events of which the log level of the LTTng tracepoint or logging statement is at least as severe as LOGLEVEL.

--loglevel-only=LOGLEVEL

Only match events of which the log level of the LTTng tracepoint or logging statement is exactly LOGLEVEL.

The instrumentation point log level options above are NOT available with the --kernel option.

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 --tracepoint or --syscall option.

-h,  --help

Show 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

List available command options and quit.