8 lttng-event-rule - Common LTTng event rule specification
13 Specify an event rule to match Linux kernel tracepoint or system call
17 option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])]
18 pass:[[]option:--name='NAME'] [option:--filter='EXPR']
20 Specify an event rule to match Linux kernel kprobe or user space
24 option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC'
25 pass:[[]option:--event-name='EVENTNAME']
27 Specify an event rule to match user space tracepoint events:
30 option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']...
31 pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
33 Specify an event rule to match Java/Python logging events:
36 option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME']
37 pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
42 This manual page shows how to specify an LTTng event rule on the command
45 As of LTTng{nbsp}{lttng_version}, the command-line options documented
46 here only apply to the `event-rule-matches` trigger condition specifier
47 (see man:lttng-add-trigger(1)).
49 See man:lttng-concepts(7) to learn more about instrumentation points,
50 events, and event rules.
54 This manual page only describes the common event rule options. The
55 man:lttng(1) commands which require an event rule specification may
56 accept or require other options and arguments, depending on the context.
58 For example, the man:lttng-add-trigger(1) command also accepts
59 nloption:--capture options with the `event-rule-matches` trigger
64 Overview of event rule condtions
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
67 conditions of an event rule, that is:
69 * The instrumentation point from which LTTng creates{nbsp}__E__ has a
72 See the <<inst-point-type-cond,Instrumentation point type condition>>
75 * A pattern matches the name of{nbsp}__E__ while another pattern
78 See the <<event-name-cond,Event name condition>> section below.
80 * The log level of the instrumentation point from which LTTng
81 creates{nbsp}__E__ is at least as severe as some value, or is exactly
84 See the <<inst-point-log-level-cond,Instrumentation point log level
85 condition>> section below.
87 * The fields of the payload of{nbsp}__E__ and the current context fields
88 satisfy a filter expression.
90 See the <<filter-cond,Event payload and context filter condition>>
93 The dedicated command-line options of most conditions are optional: if
94 you don't specify the option, the associated condition is always
98 [[inst-point-type-cond]]
99 Instrumentation point type condition
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101 An event{nbsp}__E__ satisfies the instrumentation point type condition
102 of an event rule if the instrumentation point from which LTTng
103 creates{nbsp}__E__ is:
105 For the Linux kernel tracing domain (option:--domain=++kernel++ option)::
106 With the option:--type=++tracepoint++ option or without any option:--type option:::
107 An LTTng kernel tracepoint, that is, a statically defined point
108 in the source code of the kernel image or of a kernel module
109 with LTTng kernel tracer macros.
111 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
112 point type of the Linux kernel tracing domain, but this may change in
115 List the available Linux kernel tracepoints with `lttng list --kernel`.
116 See man:lttng-list(1) to learn more.
118 With the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, or option:--type=++syscall:entry+exit++ option:::
119 The entry, exit, or entry and exit of a Linux kernel system
122 List the available Linux kernel system call instrumentation points with
123 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
125 With the option:--type=++kprobe++ option:::
126 A Linux kprobe, that is, a single probe dynamically placed in
127 the compiled kernel code.
129 You must specify the kprobe location with the option:--location option.
131 The payload of a Linux kprobe event is empty.
133 With the option:--type=++uprobe++ option:::
134 A Linux user space probe, that is, a single probe dynamically
135 placed at the entry of a compiled user space application/library
136 function through the kernel.
138 LTTng{nbsp}{lttng_version} supports the ELF and SystemTap User-level
139 Statically Defined Tracing (USDT; a DTrace-style marker) probing
140 methods. LTTng only supports USDT probes which are :not:
143 You must specify the user space probe location with the
144 option:--location option.
146 The payload of a Linux user space probe event is empty.
148 For the user space tracing domain (option:--domain=++user++ option)::
149 With or without the option:--type=++tracepoint++ option:::
150 An LTTng user space tracepoint, that is, a statically defined point
151 in the source code of a C/$$C++$$ application/library
152 with LTTng user space tracer macros.
154 As of LTTng{nbsp}{lttng_version}, this is the default and sole
155 instrumentation point type of the user space tracing domain, but this
156 may change in the future.
158 List the available user space tracepoints with `lttng list --userspace`.
159 See man:lttng-list(1) to learn more.
161 For the `java.util.logging` (option:--domain=++jul++ option), Apache log4j (option:--domain=++log4j++ option), and Python (option:--domain=++python++ option) tracing domains::
162 With or without the option:--type=++logging++ option:::
165 As of LTTng{nbsp}{lttng_version}, this is the default and sole
166 instrumentation point type of the `java.util.logging`, Apache log4j, and
167 Python tracing domains, but this may change in the future.
169 List the available Java and Python loggers with `lttng list --jul`,
170 `lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
177 An event{nbsp}__E__ satisfies the event name condition of an event
178 rule{nbsp}__ER__ if the two following statements are true:
180 * You don't specify the option:--name='NAME' option or, depending on the
181 instrumentation type condition (see the
182 <<inst-point-type-cond,Instrumentation point type condition>> section
183 above) of{nbsp}__ER__, 'NAME' matches:
187 The full name of the tracepoint from which LTTng creates{nbsp}__E__.
189 Note that the full name of a user space tracepoint is
190 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
191 name and __NAME__ is the tracepoint name.
194 The name of the Java or Python logger from which LTTng
198 The name of the system call, without any `sys_` prefix, from which
199 LTTng creates{nbsp}__E__.
202 * You don't specify any option:--exclude-name='XNAME' option or
203 none of the 'XNAME' arguments matches the full name of the user space
204 tracepoint from which LTTng creates{nbsp}__E__.
206 The option:--exclude-name option is only available with the
207 option:--domain=++user++ option.
209 This condition is only meaningful for the LTTng tracepoint, logging
210 statement, and Linux system call instrumentation point types: it's
211 always satisfied for the other types.
213 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
214 character means ``match anything''. To match a literal `*` character,
217 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
218 contain the `*` character and when you run an man:lttng(1) command from
221 As of LTTng{nbsp}{lttng_version}, not specifying the option:--name
222 option is equivalent to specifying option:--name=++\'*\'++, but this
223 default may change in the future.
226 [[inst-point-log-level-cond]]
227 Instrumentation point log level condition
228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229 An event{nbsp}__E__ satisfies the instrumentation point log level
230 condition of an event rule if either:
232 * You specify the option:--log-level=++..++ option or you don't specify
233 the option:--log-level option.
235 Defaulting to option:--log-level=++..++ when you don't specify the
236 option:--log-level option is specific to LTTng{nbsp}{lttng_version} and
237 may change in the future.
239 * The log level of the LTTng user space tracepoint or logging statement
240 from which LTTng creates{nbsp}__E__ is:
241 With the option:--log-level=__LOGLEVEL__++..++ option::
242 At least as severe as 'LOGLEVEL'.
244 With the option:--log-level=__LOGLEVEL__ option::
247 As of LTTng{nbsp}{lttng_version}, the ++..++__LOGLEVEL__ and
248 __LOGLEVEL__++..++__LOGLEVEL__ formats are :not: supported.
250 This condition is only meaningful for the LTTng user space tracepoint
251 and logging statement instrumentation point types: it's always satisfied
254 The available values of 'LOGLEVEL' are, depending on the tracing domain,
255 from the most to the least severe:
257 User space (option:--domain=++user++ option)::
267 * `DEBUG_PROGRAM` (8)
268 * `DEBUG_PROCESS` (9)
269 * `DEBUG_MODULE` (10)
271 * `DEBUG_FUNCTION` (12)
275 `java.util.logging` (option:--domain=++jul++ option)::
277 * `OFF` (`INT32_MAX`)
285 * `ALL` (`INT32_MIN`)
287 Apache log4j (option:--domain=++log4j++ option)::
289 * `OFF` (`INT32_MAX`)
296 * `ALL` (`INT32_MIN`)
298 Python (option:--domain=++python++ option)::
309 Event payload and context filter condition
310 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311 An event{nbsp}__E__ satisfies the event payload and context filter
312 condition of an event rule if the option:--filter='EXPR' option is
313 missing or if 'EXPR' is _true_.
315 This condition is only meaningful for the LTTng tracepoint and Linux
316 system call instrumentation point types: it's always satisfied for other
319 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
320 to the current context fields.
322 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an
323 man:lttng(1) command from a shell, as filter expressions typically
324 include characters having a special meaning for most shells.
326 The expected syntax of 'EXPR' is similar to the syntax of a
327 C{nbsp}language conditional expression (an expression which an `if`
328 statement can evaluate), but there are a few differences:
330 * A _NAME_ expression identifies an event payload field named
331 _NAME_ (a C{nbsp}identifier).
333 Use the C{nbsp}language dot and square bracket notations to access
334 nested structure and array/sequence fields. You can only use a constant,
335 positive integer number within square brackets. If the index is out of
336 bounds, 'EXPR' is _false_.
338 The value of an enumeration field is an integer.
340 When a field expression doesn't exist, 'EXPR' is _false_.
342 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
344 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
345 field having the type _TYPE_ (a C{nbsp}identifier).
347 List the available statically-known context field names with the
348 man:lttng-add-context(1) command.
350 When a field expression doesn't exist, 'EXPR' is _false_.
352 Examples: `$ctx.prio`, `$ctx.preemptible`,
353 `$ctx.perf:cpu:stalled-cycles-frontend`.
355 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
356 application-specific context field having the type _TYPE_ (a
357 C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
359 When a field expression doesn't exist, 'EXPR' is _false_.
361 Example: `$app.server:cur_user`.
363 * Compare strings, either string fields or string literals
364 (double-quoted), with the `==` and `!=` operators.
366 When comparing to a string literal, the `*` character means ``match
367 anything''. To match a literal `*` character, use :escwc:.
369 Examples: `my_field == "user34"`, `my_field == my_other_field`,
370 `my_field == "192.168.*"`.
372 * The precedence table of the operators which are supported in 'EXPR'
373 is as follows. In this table, the highest precedence is{nbsp}1:
377 |Precedence |Operator |Description |Associativity
378 |1 |`-` |Unary minus |Right-to-left
379 |1 |`+` |Unary plus |Right-to-left
380 |1 |`!` |Logical NOT |Right-to-left
381 |1 |`~` |Bitwise NOT |Right-to-left
382 |2 |`<<` |Bitwise left shift |Left-to-right
383 |2 |`>>` |Bitwise right shift |Left-to-right
384 |3 |`&` |Bitwise AND |Left-to-right
385 |4 |`^` |Bitwise XOR |Left-to-right
386 |5 |`\|` |Bitwise OR |Left-to-right
387 |6 |`<` |Less than |Left-to-right
388 |6 |`<=` |Less than or equal to |Left-to-right
389 |6 |`>` |Greater than |Left-to-right
390 |6 |`>=` |Greater than or equal to |Left-to-right
391 |7 |`==` |Equal to |Left-to-right
392 |7 |`!=` |Not equal to |Left-to-right
393 |8 |`&&` |Logical AND |Left-to-right
394 |9 |`\|\|` |Logical OR |Left-to-right
397 Parentheses are supported to bypass the default order.
399 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
400 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
401 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
402 is _true_ while the equivalent C{nbsp}expression is _false_.
404 The arithmetic operators are :not: supported.
406 LTTng first casts all integer constants and fields to signed 64-bit
407 integers. The representation of negative integers is two's complement.
408 This means that, for example, the signed 8-bit integer field 0xff (-1)
409 becomes 0xffffffffffffffff (still -1) once casted.
411 Before a bitwise operator is applied, LTTng casts all its operands to
412 unsigned 64-bit integers, and then casts the result back to a signed
413 64-bit integer. For the bitwise NOT operator, it's the equivalent of
414 this C{nbsp}expression:
418 (int64_t) ~((uint64_t) val)
421 For the binary bitwise operators, it's the equivalent of those
426 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
427 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
428 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
429 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
430 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
433 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
434 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
438 ----------------------------
439 msg_id == 23 && size >= 2048
440 ----------------------------
442 -------------------------------------------------
443 $ctx.procname == "lttng*" && (!flag || poel < 34)
444 -------------------------------------------------
446 ---------------------------------------------------------
447 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
448 ---------------------------------------------------------
450 ---------------------------------------
451 $ctx.cpu_id == 2 && filename != "*.log"
452 ---------------------------------------
454 ------------------------------------------------
455 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
456 ------------------------------------------------
459 Migration from a recording event rule specification
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461 Since LTTng{nbsp}2.13, what this manual page documents is the standard,
462 common way to specify an LTTng event rule.
464 With the man:lttng-enable-event(1) command, you also specify an event
465 rule, but with deprecated options and arguments.
467 The following table shows how to translate from the
468 man:lttng-enable-event(1) options and arguments to the common event
469 rule specification options:
473 |Recording event rule option(s)/argument(s) |Common event rule option(s)
475 |nloption:--kernel |option:--domain=++kernel++
476 |nloption:--userspace |option:--domain=++user++
477 |nloption:--jul |option:--domain=++jul++
478 |nloption:--log4j |option:--domain=++log4j++
479 |nloption:--python |option:--domain=++python++
480 |nloption:--tracepoint (with nloption:--kernel/nloption:--userspace) |option:--type=++tracepoint++ or no option:--type option
481 |nloption:--tracepoint (with nloption:--jul/nloption:--log4j/nloption:--python) |option:--type=++logging++ or no option:--type option
482 |nloption:--syscall |option:--type=++syscall++ or option:--type=++syscall:entry+exit++
483 |nloption:--probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++kprobe++, option:--location='LOC', and option:--event-name='RECORDNAME'
484 |nloption:--userspace-probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++uprobe++, option:--location='LOC', and option:--event-name='RECORDNAME'
485 |nloption:--function='LOC' and 'RECORDNAME' (non-option) |Not available as of LTTng{nbsp}{lttng_version}
486 |'NAME' (non-option) |option:--name='NAME'
487 |nloption:--all |option:--name=++\'*\'++ or no option:--name option
488 |nloption:--exclude=__XNAME__[++,++__XNAME__]... |option:--exclude-name='XNAME' for each 'XNAME'
489 |nloption:--loglevel='LOGLEVEL' |option:--log-level=__LOGLEVEL__++..++
490 |nloption:--loglevel-only='LOGLEVEL' |option:--log-level=__LOGLEVEL__
491 |nloption:--filter='EXPR' |option:--filter='EXPR'
499 option:-d 'DOMAIN', option:--domain='DOMAIN'::
500 Only match events which LTTng creates in the tracing domain
519 This option is mandatory.
522 Instrumentation point type condition
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
524 See the <<inst-point-type-cond,Instrumentation point type condition>>
527 option:-E 'NAME', option:--event-name='NAME'::
528 With the option:--type=++kprobe++ or option:--type=++uprobe++
529 option, set the name of the emitted events to 'NAME' instead of the
530 'LOC' argument of the option:--location='LOC' option.
532 Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may
533 change in the future.
535 option:-L 'LOC', option:--location='LOC'::
536 With the option:--type=++kprobe++ option:::
537 Set the location of the Linux kprobe to insert to 'LOC'.
541 * An address (`0x` hexadecimal prefix supported).
543 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
545 With the option:--type=++uprobe++ option:::
546 Set the location of the user space probe to insert to 'LOC'.
550 \[++elf:++]__PATH__++:++__SYMBOL__::::
551 An available symbol within a user space application or library.
555 Application or library path.
561 * The name of an application as found in the directories listed in the
562 `PATH` environment variable.
565 Symbol name of the function of which to instrument the entry.
567 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
568 command, including with its nloption:--dynamic option, which lists
572 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
573 specifying it, but this default may change in the future.
577 * `/usr/lib/libc.so.6:malloc`
578 * `./myapp:createUser`
579 * `elf:httpd:ap_run_open_htaccess`
581 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::::
582 A SystemTap User-level Statically Defined Tracing (USDT) probe
583 within a user space application or library.
587 Application or library path.
593 * The name of an application as found in the directories listed in the
594 `PATH` environment variable.
598 USDT provider and probe names.
600 For example, with the following USDT probe:
604 DTRACE_PROBE2("server", "accept_request",
605 request_id, ip_addr);
608 The provider/probe name pair is `server:accept_request`.
611 Example: `sdt:./build/server:server:accept_request`
613 option:-t 'TYPE', option:--type='TYPE'::
614 Only match events which LTTng creates from an instrumentation point
615 having the type 'TYPE'.
623 Only available with the option:--domain=++kernel++ and
624 option:--domain=++user++ options.
626 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
627 point type of the Linux kernel and user space tracing domains, but this
628 may change in the future.
633 Only available with the option:--domain=++jul++,
634 option:--domain=++log4j++, and option:--domain=++python++ options.
636 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
637 point type of the `java.util.logging`, Apache log4j, and Python tracing
638 domains, but this may change in the future.
641 As of LTTng{nbsp}{lttng_version}, equivalent to
642 `syscall:entry+exit`, but this default may change in the future.
644 Only available with the option:--domain=++kernel++ option.
647 Linux system call entry.
649 Only available with the option:--domain=++kernel++ option.
652 Linux system call exit.
654 Only available with the option:--domain=++kernel++ option.
656 `syscall:entry+exit`::
657 Linux system call entry and exit (two distinct instrumentation
660 Only available with the option:--domain=++kernel++ option.
665 Only available with the option:--domain=++kernel++ option.
667 You must specify the location of the kprobe to insert with the
668 option:--location option.
670 You may specify the name of the emitted events with the
671 option:--event-name option.
673 `uprobe` or `userspace-probe`::
674 Linux user space probe.
676 Only available with the option:--domain=++kernel++ option.
678 You must specify the location of the user space probe to insert with the
679 option:--location option.
681 You may specify the name of the emitted events with the
682 option:--event-name option.
688 See the <<event-name-cond,Event name condition>> section above.
690 option:-n 'NAME', option:--name='NAME'::
691 Only match events of which 'NAME' matches:
694 With the option:--domain=++kernel++ or option:--domain=++user++ option, with the option:--type=++tracepoint++ option or without the option:--type option:::
695 The full name of the LTTng tracepoint.
697 With the option:--domain=++jul++, option:--domain=++log4j++, or option:--domain=++python++ option:::
698 The Java or Python logger name.
700 With the option:--domain=++kernel++ option and one of the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, and option:--type=++syscall:entry+exit++ options:::
701 The name of the system call, without any `sys_` prefix.
704 This option is :not: available with the option:--type=++kprobe++ and
705 option:--type=++uprobe++ options.
707 As of LTTng{nbsp}{lttng_version}, not specifying this option is
708 equivalent to specifying option:--name=++\'*\'++ (when it applies), but
709 this default may change in the future.
711 option:-x 'XNAME', option:--exclude='XNAME'::
712 Only match events of which 'XNAME' does :not: match the full name of
713 the LTTng user space tracepoint.
715 Only available with the option:--domain=++user++ option.
717 'NAME' and 'XNAME' are globbing patterns: the `*` character means
718 ``match anything''. To match a literal `*` character, use :escwc:.
721 Instrumentation point log level condition
722 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
723 See the <<inst-point-log-level-cond,Instrumentation point log level
724 condition>> section above.
726 option:-l 'LOGLEVELSPEC', option:--log-level='LOGLEVELSPEC'::
727 Only match events of which the log level of the LTTng tracepoint or
728 logging statement is, depending on the format of 'LOGLEVELSPEC':
732 At least as severe as 'LOGLEVEL'.
741 This option is :not: available with the option:--domain=++kernel++
744 As of LTTng{nbsp}{lttng_version}, not specifying this option is
745 equivalent to specifying option:--log-level=++..++ (when it applies),
746 but this default may change in the future.
749 Event payload and context filter condition
750 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
751 See the <<filter-cond,Event payload and context filter condition>>
754 option:-f 'EXPR', option:--filter='EXPR'::
755 Only match events of which 'EXPR', which can contain references to
756 event payload and current context fields, is _true_.
758 This option is only available with the following options:
760 * option:--type=++tracepoint++
761 * option:--type=++syscall++
762 * option:--type=++syscall:entry++
763 * option:--type=++syscall:exit++
764 * option:--type=++syscall:entry+exit++
767 include::common-footer.txt[]
773 man:lttng-add-trigger(1),
775 man:lttng-concepts(7)