Create or enable Linux kernel event rules:
[verse]
-*lttng* ['GENERAL OPTIONS'] *enable-event* option:--kernel
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
[option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall]
[option:--filter='EXPR'] [option:--session='SESSION']
[option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
Create or enable an "all" Linux kernel event rule:
[verse]
-*lttng* ['GENERAL OPTIONS'] *enable-event* option:--kernel option:--all [option:--syscall]
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
[option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
Create or enable application event rules:
[verse]
-*lttng* ['GENERAL OPTIONS'] *enable-event*
+*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
(option:--userspace | option:--jul | option:--log4j | option:--python)
[option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
[option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
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.
+Event sources can be listed with the man:lttng-list(1) command.
-The linklttng:lttng-disable-event(1) command can be used to disable
+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
from the current tracing session.
Events can be enabled while tracing is active
-(use linklttng:lttng-start(1) to make a tracing session active).
+(use man:lttng-start(1) to make a tracing session active).
Event source types
For example, consider the following commands:
+[role="term"]
----------------------------------------------------------------
lttng enable-event --userspace hello:world
lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
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)).
+(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'
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 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.
+man: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).
+context field with the man: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 `\\*`.
+This wildcard can be escaped using :escwc:.
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)).
+which is much more efficient (see man:lttng-track(1)).
Examples:
Target
~~~~~~
-option:-c, option:--channel='CHANNEL'::
+option:-c 'CHANNEL', option:--channel='CHANNEL'::
Create or enable event rules in the channel named 'CHANNEL' instead
of the default channel name `channel0`.
-option:-s, option:--session='SESSION'::
+option:-s 'SESSION', option:--session='SESSION'::
Create or enable event rules in the tracing session named 'SESSION'
instead of the current tracing session.
Filtering and exclusion
~~~~~~~~~~~~~~~~~~~~~~~
-option:-x, option:--exclude='EVENT'[,'EVENT']...::
+option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
Exclude events named 'EVENT' from the event rule. This option
can be used when the command's 'EVENT' argument contains a wildcard
(`*`) to exclude specific names. Only available with application
domains.
-option:-f, option:--filter='EXPR'::
+option:-f 'EXPR', option:--filter='EXPR'::
Add filter expression condition to the event rule. Expression 'EXPR'
must evaluate to true when executed against the dynamic values of
event fields. See the <<filter-syntax,Filter expression syntax>>
SEE ALSO
--------
-linklttng:lttng-disable-event(1),
-linklttng:lttng(1)
+man:lttng-disable-event(1),
+man:lttng(1)