-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, option:--userspace-probe, and option:--function
- option's argument) which must match event source's equivalent.
-+
-You can use `*` characters at any place in the tracepoint or system
-call name as wildcards to match zero or more characters. To use a
-literal `*` character, use :escwc:.
-
-* Filter expression (option:--filter option) executed against the
- dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-expr,Filter expression>> 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.
-+
-You can use `*` characters at any place in the tracepoint name as
-wildcards to match zero or more characters. To use a literal `*`
-character, use :escwc:. When you create an event rule with a tracepoint
-name containing a wildcard, you can exclude specific tracepoint names
-from the match with 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-expr,Filter expression>> 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 man: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-expr]]
-Filter expression
-~~~~~~~~~~~~~~~~~
-A filter expression 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.
+Without the option:--session option, the `enable-event` command selects
+the current tracing session (see man:lttng-create(1) and
+man:lttng-set-session(1) to learn more about the current tracing
+session).
+
+[NOTE]
+====
+The event creation and emission processes are documentation concepts to
+help understand the journey from an instrumentation point to the
+serialization and recording of an event.
+
+The actual creation of an event can be costly because LTTng needs to
+evalute the arguments of the instrumentation point.
+
+In practice, LTTng implements various optimizations for the Linux kernel
+and user space tracing domains (option:--kernel and option:--userspace
+options) to avoid actually creating an event when the tracer knows,
+thanks to properties which are independent from the event payload and
+current context, that it would never emit such an event. Those
+properties are:
+
+* The status of the rule itself (enabled or disabled).
+* The status of the channel (enabled or disabled; see
+ man:lttng-enable-channel(1) and man:lttng-disable-channel(1)).
+* The activity of the tracing session (started or stopped; see
+ man:lttng-start(1) and man:lttng-stop(1)).
+* The instrumentation point type (see the
+ <<inst-point-type-cond,Instrumentation point type>> section below).
+* The instrumentation point name (or event name)
+ (see the <<event-name-cond,Event name condition>> section below).
+* The instrumentation point log level (see the
+ <<inst-point-log-level-cond,Instrumentation point log level condition>>
+ section below).
+
+In other words: if, for a given instrumentation point{nbsp}__IP__, the
+LTTng tracer knows that it would never emit and record an event,
+executing{nbsp}__IP__ represents a simple boolean variable check and,
+for the kernel tracer, a few process attribute checks.
+====
+
+List the existing recording event rules of a given tracing session
+and/or channel with the man:lttng-list(1) command.
+
+Disable an existing, enabled recording event rule with the
+man:lttng-disable-event(1) command.
+
+
+Recording event rule overview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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 an existing, 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 an existing, 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__ to match 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.
projects / lttng-tools.git / blobdiff