-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 man:lttng-list(1) command.
-
-The man: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 man: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
-----
+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 <<enable,Enable a disabled recording event rule>> 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 tracing session named 'SESSION'.
+
+Without the option:--session option::
+ The current tracing session (see man:lttng-concepts(7) to learn more
+ about the current tracing session).
+
+With the option:--channel='CHANNEL' option::
+ The channel named 'CHANNEL'.
+
+Without the option:--channel option::
+ The channel named `channel0`.
++
+If such a channel doesn't exist, the `enable-event` automatically
+creates it.
+
+List the recording event rules of a specific tracing 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 <<inst-point-type-cond,Instrumentation point type condition>>
+section below.
+
+* A pattern matches the name of{nbsp}__E__ while another pattern
+ doesn't.
++
+See the <<event-name-cond,Event name condition>> 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 <<inst-point-log-level-cond,Instrumentation point log level condition>>
+section below.
+
+* The fields of the payload of{nbsp}__E__ and the current context fields
+ satisfy a filter expression.
++
+See the <<filter-cond,Event payload and context filter condition>>
+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 tracing session of{nbsp}__ER__ is active (started).
++
+A tracing session is inactive (stopped) on creation.
++
+Start an inactive tracing 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 tracing 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 <<er-name,Event record name>> 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
+<<er-name,Event record name>> 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 <<er-name,Event record name>> 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
+ <<inst-point-type-cond,Instrumentation point type condition>> 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.