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 ​1​.x (--log4j option), Apache Log4j ​2 (--log4j2 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 ​1​.x (--log4j option)

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

Apache Log4j ​2 (--log4j2 option)

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

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

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 ​1​.x 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 ​1​.x logger from which LTTng creates ​E​.

Apache Log4j ​2 logging statement (--log4j2 and --tracepoint options)

lttng_log4j2:event

Such an event record has a string field logger_name which contains the name of the Apache Log4j ​2 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 ​1​.x tracing domain​.

--log4j2

Create or enable recording event rules in the Apache Log4j ​2 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 event record 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​.16​.0, 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, --log4j2, 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, --log4j2, 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​.