lttng-enable-event(1) ===================== :revdate: 14 June 2021 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: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall] (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] Create or enable a recording event rule to match Linux kernel events created from a dynamic instrumentation point: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME' [option:--session='SESSION'] [option:--channel='CHANNEL'] Create or enable one or more recording event rules to match user space tracepoint events: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...] [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] Create or enable one or more recording event rules to match Java/Python logging events: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python) [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...) [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] DESCRIPTION ----------- The `lttng enable-event` command does one of: * Create one or more recording event rules. * Enable one or more disabled recording event rules. + See the ``<>'' section below. See man: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 option:--session='SESSION' option:: The recording session named 'SESSION'. Without the option:--session option:: The current recording session (see man:lttng-concepts(7) to learn more about the current recording session). With the option:--channel='CHANNEL' option:: The channel named 'CHANNEL'. Without the option:--channel option:: The channel named `channel0`. + 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 ``<>'' section below for usage examples. List the recording event rules of a specific recording session and/or channel with the man:lttng-list(1) and man:lttng-status(1) commands. Disable an enabled recording event rule with the man:lttng-disable-event(1) command. Overview of recording event rule conditions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that is: Explicit conditions:: You set the following conditions when you create or enable{nbsp}__ER__ with the `enable-event` command: + -- * The instrumentation point type 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. -- Implicit conditions:: + -- * _ER_ itself is enabled. + A recording event rule is enabled on creation. + Enable a disabled recording event rule with the `enable-event` command. * The channel to which{nbsp}__ER__ is attached is enabled. + A channel is enabled on creation. + Enable a disabled channel with the man:lttng-enable-channel(1) command. * The recording session of{nbsp}__ER__ is active (started). + A recording session is inactive (stopped) on creation. + Start an inactive recording session with the man:lttng-start(1) command. * The process for which LTTng creates{nbsp}__E__ is allowed to record events. + All processes are allowed to record events on recording session creation. + Use the man:lttng-track(1) and man: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. [[inst-point-type-cond]] Instrumentation point type condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the instrumentation point type condition of a recording event rule if the instrumentation point from which LTTng creates{nbsp}__E__ is: For the Linux kernel tracing domain (option:--kernel option):: With the option:--tracepoint option or without any other instrumentation point 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:--syscall option::: The 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:--probe option::: A Linux kprobe, that is, a single probe dynamically placed in the compiled kernel code. + The argument of the option:--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{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux kprobe event is empty. With the option:--userspace-probe 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. + The argument of the option:--userspace-probe option is the location of the user space probe to insert, one of: + -- * A path and symbol (ELF method). * A path, provider name, and probe name (SystemTap User-level Statically Defined Tracing (USDT) method; a DTrace-style marker). + As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which are :not: reference-counted. -- + 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux user space probe event is empty. With the option:--function option::: A Linux kretprobe, that is, two probes dynamically placed at the entry and exit of a function in the compiled kernel code. + The argument of the option:--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{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux kretprobe event is empty. For the user space tracing domain (option:--userspace option):: With or without the option:--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:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains:: With or without the option:--tracepoint 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 a recording event rule{nbsp}__ER__ if the two following statements are true: * You specify the option:--all 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 the option:--exclude=__XNAME__[++,++__XNAME__]... option or, depending on the instrumentation type condition of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of the user space tracepoint from which LTTng creates{nbsp}__E__. + The option:--exclude option is only available with the option:--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 :escwc:. To match a literal `,` character, use :esccomma:. 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 option:--all option, the `enable-event` command creates or enables a single recording event rule. [[inst-point-log-level-cond]] Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the instrumentation point log level condition of a recording event rule if either: * The option:--loglevel and option:--loglevel-only options are missing. * The log level of the LTTng user space tracepoint or logging statement which creates{nbsp}__E__ is: With the option:--loglevel='LOGLEVEL' option:: At least as severe as 'LOGLEVEL'. With the option:--loglevel-only='LOGLEVEL' option:: Exactly 'LOGLEVEL'. 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:--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` (option:--jul option):: + * `OFF` (`INT32_MAX`) * `SEVERE` (1000) * `WARNING` (900) * `INFO` (800) * `CONFIG` (700) * `FINE` (500) * `FINER` (400) * `FINEST` (300) * `ALL` (`INT32_MIN`) Apache log4j (option:--log4j option):: + * `OFF` (`INT32_MAX`) * `FATAL` (50000) * `ERROR` (40000) * `WARN` (30000) * `INFO` (20000) * `DEBUG` (10000) * `TRACE` (5000) * `ALL` (`INT32_MIN`) Python (option:--python option):: + * `CRITICAL` (50) * `ERROR` (40) * `WARNING` (30) * `INFO` (20) * `DEBUG` (10) * `NOTSET` (0) [[filter-cond]] Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An event{nbsp}__E__ satisfies the event payload and context filter condition of a recording 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 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{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_. [NOTE] ==== Use the man:lttng-track(1) and man: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 ------------------------------------------------ [[er-name]] Event record name ~~~~~~~~~~~~~~~~~ When LTTng records an event{nbsp}__E__, the resulting event record has a name which depends on the instrumentation point type condition (see the ``<>'' section above) of the recording event rule which matched{nbsp}__E__: LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options):: 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. `java.util.logging` logging statement (option:--jul and option:--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{nbsp}__E__. Apache log4j logging statement (option:--log4j and option:--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{nbsp}__E__. Python logging statement (option:--python and option:--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{nbsp}__E__. Linux system call (option:--kernel and option:--syscall options):: Entry::: ++syscall_entry_++__NAME__, where _NAME_ is the name of the system call from which LTTng creates{nbsp}__E__, without any `sys_` prefix. Exit::: ++syscall_exit_++__NAME__, where _NAME_ is the name of the system call from which LTTng creates{nbsp}__E__, without any `sys_` prefix. Linux kprobe (option:--kernel and option:--probe options):: Linux user space probe (option:--kernel and option:--userspace-probe options):: 'RECORDNAME' (first non-option argument). Linux kretprobe (option:--kernel and option:--function options):: Entry::: __RECORDNAME__++_entry++ Exit::: __RECORDNAME__++_exit++ [[enable]] Enable a disabled recording event rule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `enable-event` command can enable a disabled recording event rule, as listed in the output of the man:lttng-list(1) command. You may enable a disabled recording event rule regardless of the activity (started or stopped) of its recording session (see man:lttng-start(1) and man: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 option:--filter='EXPR' option, 'EXPR' must be the exact same string as the one you used on creation. include::common-lttng-cmd-options-head.txt[] Tracing domain ~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: Create or enable recording event rules in the `java.util.logging` (JUL) tracing domain. option:-k, option:--kernel:: Create or enable recording event rules in the Linux kernel tracing domain. option:-l, option:--log4j:: Create or enable recording event rules in the Apache log4j tracing domain. option:-p, option:--python:: Create or enable recording event rules in the Python tracing domain. option:-u, option:--userspace:: Create or enable recording event rules in the user space tracing domain. Recording target ~~~~~~~~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: Create or enable recording event rules attached to the channel named 'CHANNEL' instead of `channel0`. option:-s 'SESSION', option:--session='SESSION':: Create or enable recording event rules in the recording session named 'SESSION' instead of the current recording session. Instrumentation point type condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the ``<>'' section above. At most one of: option:--function='LOC':: Only match Linux kretprobe events. + Only available with the option:--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__++pass:[+]++__OFFSET__ format). -- + You must specify the event record name with 'RECORDNAME'. See the ``<>'' section above to learn more. option:--probe='LOC':: Only match Linux kprobe events. + Only available with the option:--kernel option. + 'LOC' is one of: + -- * An address (`0x` hexadecimal prefix supported). * A symbol name. * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format). -- + You must specify the event record name with 'RECORDNAME'. See the ``<>'' section above to learn more. option:--userspace-probe='LOC':: Only match Linux user space probe events. + Only available with the option:--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 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: + * `--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: + [source,c] ---- 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 ``<>'' section above to learn more. option:--syscall:: Only match Linux system call events. + Only available with the option:--kernel option. option:--tracepoint:: Only match: + With the option:--kernel or option:--userspace option::: LTTng tracepoint events. With the option:--jul, option:--log4j, or option:--python option::: Logging events. With the option:--kernel, not specifying any of the instrumentation point type options is equivalent to specifying the option:--tracepoint option, but this default may change in the future. With the option:--userspace, option:--jul, option:--log4j, and option:--python options, not specifying the option:--tracepoint option is equivalent to specifying it, but this default may change in the future. Event name condition ~~~~~~~~~~~~~~~~~~~~ See the ``<>'' section above. option:-a, option:--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. option:-x 'XNAME'[,'XNAME']..., option:--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 option:--userspace option. + 'XNAME' is a globbing pattern: the `*` character means ``match anything''. To match a literal `*` character, use :escwc:. To match a literal `,` character, use :esccomma:. Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See the ``<>'' section above. At most one of: option:--loglevel='LOGLEVEL':: Only match events of which the log level of the LTTng tracepoint or logging statement is at least as severe as 'LOGLEVEL'. option:--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 option:--kernel option. 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 option:--tracepoint or option:--syscall option. include::common-lttng-cmd-help-options.txt[] include::common-lttng-cmd-after-options.txt[] [[examples]] EXAMPLES -------- .Create a recording event rule which matches all Linux system call events (current recording session, default channel). ==== See the option:--all and option:--syscall options. [role="term"] ---- $ lttng enable-event --kernel --all --syscall ---- ==== .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`. [role="term"] ---- $ lttng enable-event --userspace 'my_provider:msg*' ---- ==== .Create three recording event rules which match Python logging events named specifically (current recording session, default channel). ==== [role="term"] ---- $ lttng enable-event --python server3,ui.window,user-mgmt ---- ==== .Create a recording event rule which matches Apache log4j logging events with a specific log level range (current recording session, specific channel). ==== See the option:--channel, option:--all, and option:--loglevel options. [role="term"] ---- $ lttng enable-event --log4j --channel=my-loggers \ --all --loglevel=INFO ---- ==== .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 ``<>'' section above). See the option:--probe option. [role="term"] ---- $ lttng enable-event --kernel --probe=usb_disconnect usbd ---- ==== .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 option:--session and option:--filter options. [role="term"] ---- $ lttng enable-event --kernel --session=my-session 'sched_*' \ --filter='$ctx.preemptible && comm != "systemd*"' ---- ==== .Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel). ==== See the option:--channel option. [role="term"] ---- $ lttng enable-event --kernel --channel=tva ja,wendy ---- ==== include::common-footer.txt[] SEE ALSO -------- man:lttng(1), man:lttng-disable-event(1), man:lttng-enable-channel(1), man:lttng-list(1), man:lttng-start(1), man:lttng-track(1), man:lttng-concepts(7)