-The `lttng enable-event` command can create a new event rule, or enable
-one or more existing and disabled ones.
-
-An event rule created by `lttng enable-event` is a set of conditions
-that must be satisfied in order for an actual event to be emitted by
-an LTTng tracer when the execution of an application or the Linux kernel
-reaches an event source (tracepoint, system call, dynamic probe).
-Event sources can be listed with the linklttng:lttng-list(1) command.
-
-The linklttng:lttng-disable-event(1) command can be used to disable
-existing event rules.
-
-Event rules are always assigned to a channel when they are created. If
-the option:--channel option is omitted, a default channel named
-`channel0` is used (and created automatically if it does not exist for
-the specified domain in the selected tracing session).
-
-If the option:--session option is omitted, the chosen channel is picked
-from the current tracing session.
-
-Events can be enabled while tracing is active
-(use linklttng:lttng-start(1) to make a tracing session active).
-
-
-Event source types
-~~~~~~~~~~~~~~~~~~
-Four types of event sources are available in the Linux kernel tracing
-domain (option:--kernel option):
-
-Tracepoint (option:--tracepoint option; default)::
- A Linux kernel tracepoint, that is, a static instrumentation point
- placed in the kernel source code. Standard tracepoints are designed
- and placed in the source code by developers and record useful
- payload fields.
-
-Dynamic probe (option:--probe option)::
- A Linux kernel kprobe, that is, an instrumentation point placed
- dynamically in the compiled kernel code. Dynamic probe events do not
- record any payload field.
-
-Function probe (option:--function option)::
- A Linux kernel kretprobe, that is, two instrumentation points placed
- dynamically where a function is entered and where it returns in the
- compiled kernel code. Function probe events do not record any
- payload field.
-
-System call (option:--syscall option)::
- A Linux kernel system call. Two instrumentation points are
- statically placed where a system call function is entered and where
- it returns in the compiled kernel code. System call event sources
- record useful payload fields.
-
-The application tracing domains (option:--userspace, option:--jul,
-option:--log4j, or option:--python options) only support tracepoints.
-In the cases of the JUL, Apache log4j, and Python domains, the event
-names correspond to _logger_ names.
-
-
-Understanding event rule conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When creating an event rule with `lttng enable-event`, conditions are
-specified using options. The logical conjunction (logical AND) of all
-those conditions must be true when an event source is reached by an
-application or by the Linux kernel in order for an actual event
-to be emitted by an LTTng tracer.
-
-Any condition that is not explicitly specified on creation is considered
-a _don't care_.
-
-For example, consider the following commands:
-
-[role="term"]
-----------------------------------------------------------------
-lttng enable-event --userspace hello:world
-lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
-----------------------------------------------------------------
-
-Here, two event rules are created. The first one has a single condition:
-the tracepoint name must match `hello:world`. The second one has two
-conditions:
-
-* The tracepoint name must match `hello:world`, _and_
-* The tracepoint's defined log level must be at least as severe as
- the `TRACE_INFO` level.
-
-In this case, the second event rule is pointless because the first one
-is more general: it does not care about the tracepoint's log level.
-If an event source matching both event rules is reached by the
-application's execution, only one event is emitted.
-
-The available conditions for the Linux kernel domain are:
-
-* Tracepoint/system call name ('EVENT' argument with
- option:--tracepoint or option:--syscall options) or
- dynamic probe/function name/address
- (option:--probe or option:--function option's argument) which must
- match event source's equivalent.
-+
-Wildcard using the `*` character are supported _at the end_ of
-tracepoint and system call names.
-
-* Filter expression (option:--filter option) executed against the
- dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-syntax,Filter expression syntax>> section
- below for more information.
-
-The available conditions for the application domains are:
-
-* Tracepoint name ('EVENT' with option:--tracepoint option) which must
- match event source's equivalent.
-+
-Wildcard using the `*` character are supported _at the end_ of
-tracepoint names. When creating an event rule with a tracepoint name
-containing a wildcard, specific tracepoint names can be excluded from
-the match using the option:--exclude option.
-
-* Filter expression (option:--filter option) executed against the
- dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-syntax,Filter expression syntax>> section
- below for more information.
-* Event's log level that must be at least as severe as a given
- log level (option:--loglevel option) or match exactly a given log
- level (option:--loglevel-only option).
-
-When using `lttng enable-event` with a set of conditions that does not
-currently exist for the chosen tracing session, domain, and channel,
-a new event rule is created. Otherwise, the existing event rule is
-enabled if it is currently disabled
-(see linklttng:lttng-disable-event(1)).
-
-The option:--all option can be used alongside the option:--tracepoint
-or option:--syscall options. When this option is used, no 'EVENT'
-argument must be specified. This option defines a single event rule
-matching _all_ the possible events of a given tracing domain for the
-chosen channel and tracing session. It is the equivalent of an 'EVENT'
-argument named `*` (wildcard).
-
-
-[[filter-syntax]]
-Filter expression syntax
-~~~~~~~~~~~~~~~~~~~~~~~~
-Filter expressions can be specified with the option:--filter option
-when creating a new event rule. If the filter expression evaluates
-to true when executed against the dynamic values of an event's fields
-when tracing, the filtering condition passes.
-
-NOTE: Make sure to **single-quote** the filter expression when running
-the command from a shell, as filter expressions typically include
-characters having a special meaning for most shells.
-
-The filter expression syntax is very similar to C language conditional
-expressions (expressions that can be evaluated by an `if` statement).
-
-The following logical operators are supported:
-
-[width="40%",options="header"]
-|=====================================
-| Name | Syntax
-| Logical negation (NOT) | `!a`
-| Logical conjunction (AND) | `a && b`
-| Logical disjunction (OR) | `a \|\| b`
-|=====================================
-
-The following comparison operators/relational operators are supported:
-
-[width="40%",options="header"]
-|====================================
-| Name | Syntax
-| Equal to | `a == b`
-| Not equal to | `a != b`
-| Greater than | `a > b`
-| Less than | `a < b`
-| Greater than or equal to | `a >= b`
-| Less than or equal to | `a <= b`
-|====================================
-
-The arithmetic and bitwise operators are :not: supported.
-
-The precedence table of the operators above is the same as the one of
-the C language. Parentheses are supported to bypass this.
-
-The dynamic value of an event field is read by using its name as
-a C identifier.
-
-The dynamic value of a statically-known context field is read by
-prefixing its name with `$ctx.`. Statically-known context fields are
-context fields added to channels without the `$app.` prefix using the
-linklttng:lttng-add-context(1) command.
-
-The dynamic value of an application-specific context field is read by
-prefixing its name with `$app.` (follows the format used to add such a
-context field with the linklttng:lttng-add-context(1) command).
-
-When a comparison includes a non existent event field, the whole filter
-expression evaluates to false (the event is discarded).
-
-C integer and floating point number constants are supported, as well as
-literal strings between double quotes (`"`). Literal strings can contain
-a wildcard character (`*`) at the end to match more than one string.
-This wildcard can be escaped using `\\*`.
-
-LTTng-UST enumeration fields can be compared to integer values (fields
-or constants).
-
-NOTE: Although it is possible to filter the process ID of an event when
-the `pid` context has been added to its channel using, for example,
-`$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
-which is much more efficient (see linklttng:lttng-track(1)).