lttng-event-rule(7) =================== :revdate: 12 May 2021 NAME ---- lttng-event-rule - Common LTTng event rule specification SYNOPSIS -------- Specify an event rule to match Linux kernel tracepoint or system call events: [verse] option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])] pass:[[]option:--name='NAME'] [option:--filter='EXPR'] Specify an event rule to match Linux kernel kprobe or user space probe events: [verse] option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC' pass:[[]option:--event-name='EVENTNAME'] Specify an event rule to match user space tracepoint events: [verse] option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']... pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR'] Specify an event rule to match Java/Python logging events: [verse] option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME'] pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR'] DESCRIPTION ----------- This manual page shows how to specify an LTTng event rule on the command line. As of LTTng{nbsp}{lttng_version}, the command-line options documented here only apply to the `event-rule-matches` trigger condition specifier (see man:lttng-add-trigger(1)). See man:lttng-concepts(7) to learn more about instrumentation points, events, and event rules. [NOTE] ==== This manual page only describes the common event rule options. The man:lttng(1) commands which require an event rule specification may accept or require other options and arguments, depending on the context. For example, the man:lttng-add-trigger(1) command also accepts nloption:--capture options with the `event-rule-matches` trigger condition. ==== Overview of event rule condtions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the conditions of an event rule, that is: * The instrumentation point from which LTTng creates{nbsp}__E__ has a specific type. + See the <> section below. * A pattern matches the name of{nbsp}__E__ while another pattern doesn't. + See the <> section below. * The log level of the instrumentation point from which LTTng creates{nbsp}__E__ is at least as severe as some value, or is exactly some value. + See the <> section below. * The fields of the payload of{nbsp}__E__ and the current context fields satisfy a filter expression. + See the <> 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. [[inst-point-type-cond]] Instrumentation point type condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the instrumentation point type condition of an event rule if the instrumentation point from which LTTng creates{nbsp}__E__ is: For the Linux kernel tracing domain (option:--domain=++kernel++ option):: With the option:--type=++tracepoint++ option or without any option:--type option::: 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. + As of LTTng{nbsp}{lttng_version}, 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 man:lttng-list(1) to learn more. With the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, or option:--type=++syscall:entry+exit++ option::: 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 man:lttng-list(1) to learn more. With the option:--type=++kprobe++ option::: A Linux kprobe, that is, a single probe dynamically placed in the compiled kernel code. + You must specify the kprobe location with the option:--location option. + The payload of a Linux kprobe event is empty. With the option:--type=++uprobe++ option::: 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{nbsp}{lttng_version} 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 option:--location option. + The payload of a Linux user space probe event is empty. For the user space tracing domain (option:--domain=++user++ option):: With or without the option:--type=++tracepoint++ option::: 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. + As of LTTng{nbsp}{lttng_version}, 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 man:lttng-list(1) to learn more. For the `java.util.logging` (option:--domain=++jul++ option), Apache log4j (option:--domain=++log4j++ option), and Python (option:--domain=++python++ option) tracing domains:: With or without the option:--type=++logging++ option::: A logging statement. + As of LTTng{nbsp}{lttng_version}, 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 man:lttng-list(1) to learn more. [[event-name-cond]] Event name condition ~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the event name condition of an event rule{nbsp}__ER__ if the two following statements are true: * You don't specify the option:--name='NAME' option or, depending on the instrumentation type condition (see the <> section above) of{nbsp}__ER__, 'NAME' matches: + -- LTTng tracepoint:: The full name of the tracepoint from which LTTng creates{nbsp}__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. Logging statement:: The name of the Java or Python logger from which LTTng creates{nbsp}__E__. Linux system call:: The name of the system call, without any `sys_` prefix, from which LTTng creates{nbsp}__E__. -- * You don't specify any option:--exclude-name='XNAME' option or none of the 'XNAME' arguments matches the full name of the user space tracepoint from which LTTng creates{nbsp}__E__. + The option:--exclude-name option is only available with the option:--domain=++user++ 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 :escwc:. IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they contain the `*` character and when you run an man:lttng(1) command from a shell. As of LTTng{nbsp}{lttng_version}, not specifying the option:--name option is equivalent to specifying option:--name=++\'*\'++, but this default may change in the future. [[inst-point-log-level-cond]] Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the instrumentation point log level condition of an event rule if either: * You specify the option:--log-level=++..++ option or you don't specify the option:--log-level option. + Defaulting to option:--log-level=++..++ when you don't specify the option:--log-level option is specific to LTTng{nbsp}{lttng_version} and may change in the future. * The log level of the LTTng user space tracepoint or logging statement from which LTTng creates{nbsp}__E__ is: With the option:--log-level=__LOGLEVEL__++..++ option:: At least as severe as 'LOGLEVEL'. With the option:--log-level=__LOGLEVEL__ option:: Exactly 'LOGLEVEL'. As of LTTng{nbsp}{lttng_version}, 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 tracing domain, from the most to the least severe: User space (option:--domain=++user++ option):: Shortcuts such as `system` are allowed. + * `TRACE_EMERG` (0) * `TRACE_ALERT` (1) * `TRACE_CRIT` (2) * `TRACE_ERR` (3) * `TRACE_WARNING` (4) * `TRACE_NOTICE` (5) * `TRACE_INFO` (6) * `TRACE_DEBUG_SYSTEM` (7) * `TRACE_DEBUG_PROGRAM` (8) * `TRACE_DEBUG_PROCESS` (9) * `TRACE_DEBUG_MODULE` (10) * `TRACE_DEBUG_UNIT` (11) * `TRACE_DEBUG_FUNCTION` (12) * `TRACE_DEBUG_LINE` (13) * `TRACE_DEBUG` (14) `java.util.logging` (option:--domain=++jul++ option):: Shortcuts such as `severe` are allowed. + * `JUL_OFF` (`INT32_MAX`) * `JUL_SEVERE` (1000) * `JUL_WARNING` (900) * `JUL_INFO` (800) * `JUL_CONFIG` (700) * `JUL_FINE` (500) * `JUL_FINER` (400) * `JUL_FINEST` (300) * `JUL_ALL` (`INT32_MIN`) Apache log4j (option:--domain=++log4j++ option):: Shortcuts such as `severe` are allowed. + * `LOG4J_OFF` (`INT32_MAX`) * `LOG4J_FATAL` (50000) * `LOG4J_ERROR` (40000) * `LOG4J_WARN` (30000) * `LOG4J_INFO` (20000) * `LOG4J_DEBUG` (10000) * `LOG4J_TRACE` (5000) * `LOG4J_ALL` (`INT32_MIN`) Python (option:--domain=++python++ option):: Shortcuts such as `critical` are allowed. + * `PYTHON_CRITICAL` (50) * `PYTHON_ERROR` (40) * `PYTHON_WARNING` (30) * `PYTHON_INFO` (20) * `PYTHON_DEBUG` (10) * `PYTHON_NOTSET` (0) [[filter-cond]] Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the event payload and context filter condition of an event rule if the option:--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{nbsp}__E__ and to the current context fields. IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an man:lttng(1) 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{nbsp}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{nbsp}identifier). + Use the C{nbsp}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{nbsp}identifier). + List the available statically-known context field names with the man: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{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}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 :escwc:. + 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{nbsp}1: + [options="header"] |=== |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{nbsp}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{nbsp}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{nbsp}expression: + [source,c] ---- (int64_t) ~((uint64_t) val) ---- + For the binary bitwise operators, it's the equivalent of those C{nbsp}expressions: + [source,c] ---- (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,{nbsp}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 ------------------------------------------------ Migration from a recording event rule specification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since LTTng{nbsp}2.13, what this manual page documents is the standard, common way to specify an LTTng event rule. With the man: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 man:lttng-enable-event(1) options and arguments to the common event rule specification options: [options="header"] |=== |Recording event rule option(s)/argument(s) |Common event rule option(s) |nloption:--kernel |option:--domain=++kernel++ |nloption:--userspace |option:--domain=++user++ |nloption:--jul |option:--domain=++jul++ |nloption:--log4j |option:--domain=++log4j++ |nloption:--python |option:--domain=++python++ |nloption:--tracepoint (with nloption:--kernel/nloption:--userspace) |option:--type=++tracepoint++ or no option:--type option |nloption:--tracepoint (with nloption:--jul/nloption:--log4j/nloption:--python) |option:--type=++logging++ or no option:--type option |nloption:--syscall |option:--type=++syscall++ or option:--type=++syscall:entry+exit++ |nloption:--probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++kprobe++, option:--location='LOC', and option:--event-name='RECORDNAME' |nloption:--userspace-probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++uprobe++, option:--location='LOC', and option:--event-name='RECORDNAME' |nloption:--function='LOC' and 'RECORDNAME' (non-option) |Not available as of LTTng{nbsp}{lttng_version} |'NAME' (non-option) |option:--name='NAME' |nloption:--all |option:--name=++\'*\'++ or no option:--name option |nloption:--exclude=__XNAME__[++,++__XNAME__]... |option:--exclude-name='XNAME' for each 'XNAME' |nloption:--loglevel='LOGLEVEL' |option:--log-level=__LOGLEVEL__++..++ |nloption:--loglevel-only='LOGLEVEL' |option:--log-level=__LOGLEVEL__ |nloption:--filter='EXPR' |option:--filter='EXPR' |=== OPTIONS ------- Tracing domain ~~~~~~~~~~~~~~ option:-d 'DOMAIN', option:--domain='DOMAIN':: Only match events which LTTng creates in the tracing domain 'DOMAIN'. + 'DOMAIN' is one of: + -- `kernel`::: Linux kernel `user`::: `userspace`::: User space tracing `jul`::: `java.util.logging` `log4j`::: Apache log4j `python`::: Python -- + This option is mandatory. Instrumentation point type condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the <> section above. option:-E 'NAME', option:--event-name='NAME':: With the option:--type=++kprobe++ or option:--type=++uprobe++ option, set the name of the emitted events to 'NAME' instead of the 'LOC' argument of the option:--location='LOC' option. + Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may change in the future. option:-L 'LOC', option:--location='LOC':: With the option:--type=++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__++pass:[+]++__OFFSET__ format). With the option:--type=++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 man:nm(1) command, including with its nloption:--dynamic option, which lists dynamic symbols. -- + As of LTTng{nbsp}{lttng_version}, 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: + [source,c] ---- 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` option:-t 'TYPE', option:--type='TYPE':: Only match events which LTTng creates from an instrumentation point having the type 'TYPE'. + 'TYPE' is one of: + -- `tracepoint`:: LTTng tracepoint. + Only available with the option:--domain=++kernel++ and option:--domain=++user++ options. + As of LTTng{nbsp}{lttng_version}, this is the default instrumentation point type of the Linux kernel and user space tracing domains, but this may change in the future. `logging`:: Logging statement. + Only available with the option:--domain=++jul++, option:--domain=++log4j++, and option:--domain=++python++ options. + As of LTTng{nbsp}{lttng_version}, this is the default instrumentation point type of the `java.util.logging`, Apache log4j, and Python tracing domains, but this may change in the future. `syscall`:: As of LTTng{nbsp}{lttng_version}, equivalent to `syscall:entry+exit`, but this default may change in the future. + Only available with the option:--domain=++kernel++ option. `syscall:entry`:: Linux system call entry. + Only available with the option:--domain=++kernel++ option. `syscall:exit`:: Linux system call exit. + Only available with the option:--domain=++kernel++ option. `syscall:entry+exit`:: Linux system call entry and exit (two distinct instrumentation points). + Only available with the option:--domain=++kernel++ option. `kprobe`:: Linux kprobe. + Only available with the option:--domain=++kernel++ option. + You must specify the location of the kprobe to insert with the option:--location option. + You may specify the name of the emitted events with the option:--event-name option. `uprobe` or `userspace-probe`:: Linux user space probe. + Only available with the option:--domain=++kernel++ option. + You must specify the location of the user space probe to insert with the option:--location option. + You may specify the name of the emitted events with the option:--event-name option. -- Event name condition ~~~~~~~~~~~~~~~~~~~~ See the <> section above. option:-n 'NAME', option:--name='NAME':: Only match events of which 'NAME' matches: + -- With the option:--domain=++kernel++ or option:--domain=++user++ option, with the option:--type=++tracepoint++ option or without the option:--type option::: The full name of the LTTng tracepoint. With the option:--domain=++jul++, option:--domain=++log4j++, or option:--domain=++python++ option::: The Java or Python logger name. With the option:--domain=++kernel++ option and one of the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, and option:--type=++syscall:entry+exit++ options::: The name of the system call, without any `sys_` prefix. -- + This option is :not: available with the option:--type=++kprobe++ and option:--type=++uprobe++ options. + As of LTTng{nbsp}{lttng_version}, not specifying this option is equivalent to specifying option:--name=++\'*\'++ (when it applies), but this default may change in the future. option:-x 'XNAME', option:--exclude='XNAME':: Only match events of which 'XNAME' does :not: match the full name of the LTTng user space tracepoint. + Only available with the option:--domain=++user++ option. 'NAME' and 'XNAME' are globbing patterns: the `*` character means ``match anything''. To match a literal `*` character, use :escwc:. Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the <> section above. option:-l 'LOGLEVELSPEC', option:--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 option:--domain=++kernel++ option. + As of LTTng{nbsp}{lttng_version}, not specifying this option is equivalent to specifying option:--log-level=++..++ (when it applies), but this default may change in the future. Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the <> section above. option:-f 'EXPR', option:--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: + * option:--type=++tracepoint++ * option:--type=++syscall++ * option:--type=++syscall:entry++ * option:--type=++syscall:exit++ * option:--type=++syscall:entry+exit++ include::common-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-add-trigger(1), man:lttng-list(1), man:lttng-concepts(7)