lttng-event-rule(7)
===================
-:revdate: 19 April 2021
+:revdate: 12 May 2021
NAME
events:
[verse]
-option:--domain=kernel option:--type=(tracepoint | syscall[:entry|:exit|:entry+exit])]
+option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])]
pass:[[]option:--name='NAME'] [option:--filter='EXPR']
Specify an event rule to match Linux kernel kprobe or user space
probe events:
[verse]
-option:--domain=kernel option:--type=(kprobe | uprobe) option:--location='LOC'
-pass:[[]option:--event-name='EVENTNAME'] [option:--filter='EXPR']
+option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC'
+pass:[[]option:--event-name='EVENTNAME']
Specify an event rule to match user space tracepoint events:
[verse]
-option:--domain=user [option:--type=tracepoint] [option:--name='NAME'] [option:--exclude-name='XNAME']...
+option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']...
pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
Specify an event rule to match Java/Python logging events:
[verse]
-option:--domain=(jul | log4j | python) [option:--type=logging] [option:--name='NAME']
+option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME']
pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
here only apply to the `event-rule-matches` trigger condition specifier
(see man:lttng-add-trigger(1)).
+See man:lttng-concepts(7) to learn more about instrumentation points,
+events, and event rules.
+
[NOTE]
====
This manual page only describes the common event rule options. The
====
-Core concepts
-~~~~~~~~~~~~~
-An _instrumentation point_ is a point, within a piece of software,
-which, when executed, creates an LTTng _event_.
-
-LTTng offers various types of instrumentation; see the
-<<inst-point-type-cond,Instrumentation point type condition>> section
-below to learn about them.
-
-An _event rule_ is a set of conditions to match a set of events.
-
-When LTTng creates an event{nbsp}__E__, a event rule{nbsp}__ER__ is said
-to __match__{nbsp}__E__ when{nbsp}__E__ satisfies *all* the conditions
-of{nbsp}__ER__. This concept is similar to a regular expression which
-matches a set of strings.
-
-When an event rule matches an event, LTTng _emits_ the event,
-therefore attempting to execute one or more actions.
-
-[NOTE]
-====
-The event creation and emission processes are documentation concepts to
-help understand the journey from an instrumentation point to the
-execution of actions.
-
-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:--domain=++kernel++ and
-option:--domain=++user++ 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 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 an event,
-executing{nbsp}__IP__ represents a simple boolean variable check.
-====
-
-
-Event rule overview
-~~~~~~~~~~~~~~~~~~~
+Overview of event rule condtions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
conditions of an event rule, that is:
from the most to the least severe:
User space (option:--domain=++user++ option)::
- Shortcuts such as `system` are allowed.
-+
-* `TRACE_EMERG` (0)
-* `TRACE_ALERT` (1)
-* `TRACE_CRIT` (2)
-* `TRACE_ERR` (3)
-* `TRACE_WARNING` (4)
-* `TRACE_NOTICE` (5)
-* `TRACE_INFO` (6)
-* `TRACE_DEBUG_SYSTEM` (7)
-* `TRACE_DEBUG_PROGRAM` (8)
-* `TRACE_DEBUG_PROCESS` (9)
-* `TRACE_DEBUG_MODULE` (10)
-* `TRACE_DEBUG_UNIT` (11)
-* `TRACE_DEBUG_FUNCTION` (12)
-* `TRACE_DEBUG_LINE` (13)
-* `TRACE_DEBUG` (14)
++
+* `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:--domain=++jul++ option)::
- Shortcuts such as `severe` are allowed.
-+
-* `JUL_OFF` (`INT32_MAX`)
-* `JUL_SEVERE` (1000)
-* `JUL_WARNING` (900)
-* `JUL_INFO` (800)
-* `JUL_CONFIG` (700)
-* `JUL_FINE` (500)
-* `JUL_FINER` (400)
-* `JUL_FINEST` (300)
-* `JUL_ALL` (`INT32_MIN`)
++
+* `OFF` (`INT32_MAX`)
+* `SEVERE` (1000)
+* `WARNING` (900)
+* `INFO` (800)
+* `CONFIG` (700)
+* `FINE` (500)
+* `FINER` (400)
+* `FINEST` (300)
+* `ALL` (`INT32_MIN`)
Apache log4j (option:--domain=++log4j++ option)::
- Shortcuts such as `severe` are allowed.
+
-* `LOG4J_OFF` (`INT32_MAX`)
-* `LOG4J_FATAL` (50000)
-* `LOG4J_ERROR` (40000)
-* `LOG4J_WARN` (30000)
-* `LOG4J_INFO` (20000)
-* `LOG4J_DEBUG` (10000)
-* `LOG4J_TRACE` (5000)
-* `LOG4J_ALL` (`INT32_MIN`)
+* `OFF` (`INT32_MAX`)
+* `FATAL` (50000)
+* `ERROR` (40000)
+* `WARN` (30000)
+* `INFO` (20000)
+* `DEBUG` (10000)
+* `TRACE` (5000)
+* `ALL` (`INT32_MIN`)
Python (option:--domain=++python++ option)::
- Shortcuts such as `critical` are allowed.
+
-* `PYTHON_CRITICAL` (50)
-* `PYTHON_ERROR` (40)
-* `PYTHON_WARNING` (30)
-* `PYTHON_INFO` (20)
-* `PYTHON_DEBUG` (10)
-* `PYTHON_NOTSET` (0)
+* `CRITICAL` (50)
+* `ERROR` (40)
+* `WARNING` (30)
+* `INFO` (20)
+* `DEBUG` (10)
+* `NOTSET` (0)
[[filter-cond]]
condition of an 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.
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 following options:
++
+* option:--type=++tracepoint++
+* option:--type=++syscall++
+* option:--type=++syscall:entry++
+* option:--type=++syscall:exit++
+* option:--type=++syscall:entry+exit++
+
+
+include::common-footer.txt[]
SEE ALSO
--------
man:lttng(1),
-man:lttng-add-trigger(1)
+man:lttng-add-trigger(1),
+man:lttng-list(1),
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff