X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=doc%2Fman%2Flttng-event-rule.7.txt;h=9e67149ea205b6c6bcef860a7fe7697af850c96e;hb=2ed07e9727517de5f57bc9b3aaf6aaeb8836520c;hp=b28d23aae4acb97aaac6768e11e4748dbaf43532;hpb=484b2a0cbefcf0c7072622a5a411ea5ed849da28;p=lttng-tools.git diff --git a/doc/man/lttng-event-rule.7.txt b/doc/man/lttng-event-rule.7.txt index b28d23aae..9e67149ea 100644 --- a/doc/man/lttng-event-rule.7.txt +++ b/doc/man/lttng-event-rule.7.txt @@ -1,6 +1,6 @@ lttng-event-rule(7) =================== -:revdate: 19 April 2021 +:revdate: 12 May 2021 NAME @@ -14,26 +14,26 @@ Specify an event rule to match Linux kernel tracepoint or system call 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'] @@ -46,6 +46,9 @@ As of LTTng{nbsp}{lttng_version}, the command-line options documented 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 @@ -58,57 +61,8 @@ condition. ==== -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 -<> 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 - <> section below). -* The instrumentation point name (or event name) - (see the <> section below). -* The instrumentation point log level (see the - <> - 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: @@ -301,58 +255,54 @@ The available values of 'LOGLEVEL' are, depending on the tracing domain, 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]] @@ -362,6 +312,10 @@ An event{nbsp}__E__ satisfies the event payload and context filter 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. @@ -800,9 +754,22 @@ section above. 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)