8 lttng-event-rule - Common LTTng event rule specification
13 Specify an event rule to match Linux kernel tracepoint or system call
17 option:--type=(**kernel:tracepoint** | **kernel: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:--type=(**kernel:kprobe** | **kernel:uprobe**) option:--location='LOC'
25 pass:[[]option:--event-name='EVENTNAME']
27 Specify an event rule to match user space tracepoint events:
30 option:--type=**user: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:--type=(**jul** | **log4j** | **python**)**: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
73 condition>>'' section below.
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, depending on the argument of the option:--type
106 `kernel:tracepoint`::
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 List the available Linux kernel tracepoints with `lttng list --kernel`.
112 See man:lttng-list(1) to learn more.
114 `kernel:syscall:entry`::
115 `kernel:syscall:exit`::
116 `kernel:syscall:entry+exit`::
117 The entry, exit, or entry and exit of a Linux kernel system
120 List the available Linux kernel system call instrumentation points with
121 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
124 A Linux kprobe, that is, a single probe dynamically placed in
125 the compiled kernel code.
127 You must specify the kprobe location with the option:--location option.
129 The payload of a Linux kprobe event is empty.
132 A Linux user space probe, that is, a single probe dynamically
133 placed at the entry of a compiled user space application/library
134 function through the kernel.
136 LTTng{nbsp}{lttng_version} supports the ELF and SystemTap User-level
137 Statically Defined Tracing (USDT; a DTrace-style marker) probing
138 methods. LTTng only supports USDT probes which are :not:
141 You must specify the user space probe location with the
142 option:--location option.
144 The payload of a Linux user space probe event is empty.
147 An LTTng user space tracepoint, that is, a statically defined point
148 in the source code of a C/$$C++$$ application/library with LTTng
149 user space tracer macros.
151 List the available user space tracepoints with `lttng list --userspace`.
152 See man:lttng-list(1) to learn more.
155 A `java.util.logging` logging statement.
157 List the available `java.util.logging` loggers with `lttng list --jul`
158 See man:lttng-list(1) to learn more.
161 An Apache log4j logging statement.
163 List the available Apache log4j loggers with `lttng list --log4j`
164 See man:lttng-list(1) to learn more.
167 A Python logging statement.
169 List the available Python loggers with `lttng list --python` See
170 man:lttng-list(1) to learn more.
176 An event{nbsp}__E__ satisfies the event name condition of an event
177 rule{nbsp}__ER__ if the two following statements are true:
179 * You don't specify the option:--name='NAME' option or, depending on the
180 instrumentation type condition (see the
181 ``<<inst-point-type-cond,Instrumentation point type condition>>''
182 section above) of{nbsp}__ER__, 'NAME' matches:
185 `kernel:tracepoint`::
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.
196 The name of the Java or Python logger from which LTTng
199 `kernel:syscall:entry`::
200 `kernel:syscall:exit`::
201 `kernel:syscall:entry+exit`::
202 The name of the system call, without any `sys_` prefix, from which
203 LTTng creates{nbsp}__E__.
206 * You don't specify any option:--exclude-name='XNAME' option or
207 none of the 'XNAME' arguments matches the full name of the user space
208 tracepoint from which LTTng creates{nbsp}__E__.
210 The option:--exclude-name option is only available with the
211 option:--type=++user:tracepoint++ option.
213 This condition is only meaningful for the LTTng tracepoint, logging
214 statement, and Linux system call instrumentation point types: it's
215 always satisfied for the other types.
217 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
218 character means ``match anything''. To match a literal `*` character,
221 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
222 contain the `*` character and when you run an man:lttng(1) command from
225 As of LTTng{nbsp}{lttng_version}, not specifying the option:--name
226 option is equivalent to specifying option:--name=++\'*\'++, but this
227 default may change in the future.
230 [[inst-point-log-level-cond]]
231 Instrumentation point log level condition
232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233 An event{nbsp}__E__ satisfies the instrumentation point log level
234 condition of an event rule if either:
236 * You specify the option:--log-level=++..++ option or you don't specify
237 the option:--log-level option.
239 Defaulting to option:--log-level=++..++ when you don't specify the
240 option:--log-level option is specific to LTTng{nbsp}{lttng_version} and
241 may change in the future.
243 * The log level of the LTTng user space tracepoint or logging statement
244 from which LTTng creates{nbsp}__E__ is:
245 With the option:--log-level=__LOGLEVEL__++..++ option::
246 At least as severe as 'LOGLEVEL'.
248 With the option:--log-level=__LOGLEVEL__ option::
251 As of LTTng{nbsp}{lttng_version}, the ++..++__LOGLEVEL__ and
252 __LOGLEVEL__++..++__LOGLEVEL__ formats are :not: supported.
254 This condition is only meaningful for the LTTng user space tracepoint
255 and logging statement instrumentation point types: it's always satisfied
258 The available values of 'LOGLEVEL' are, depending on the argument of
259 the option:--type option, from the most to the least severe:
271 * `DEBUG_PROGRAM` (8)
272 * `DEBUG_PROCESS` (9)
273 * `DEBUG_MODULE` (10)
275 * `DEBUG_FUNCTION` (12)
281 * `OFF` (`INT32_MAX`)
289 * `ALL` (`INT32_MIN`)
293 * `OFF` (`INT32_MAX`)
300 * `ALL` (`INT32_MIN`)
313 Event payload and context filter condition
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315 An event{nbsp}__E__ satisfies the event payload and context filter
316 condition of an event rule if the option:--filter='EXPR' option is
317 missing or if 'EXPR' is _true_.
319 This condition is only meaningful for the LTTng tracepoint and Linux
320 system call instrumentation point types: it's always satisfied for other
323 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
324 to the current context fields.
326 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an
327 man:lttng(1) command from a shell, as filter expressions typically
328 include characters having a special meaning for most shells.
330 The expected syntax of 'EXPR' is similar to the syntax of a
331 C{nbsp}language conditional expression (an expression which an `if`
332 statement can evaluate), but there are a few differences:
334 * A _NAME_ expression identifies an event payload field named
335 _NAME_ (a C{nbsp}identifier).
337 Use the C{nbsp}language dot and square bracket notations to access
338 nested structure and array/sequence fields. You can only use a constant,
339 positive integer number within square brackets. If the index is out of
340 bounds, 'EXPR' is _false_.
342 The value of an enumeration field is an integer.
344 When a field expression doesn't exist, 'EXPR' is _false_.
346 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
348 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
349 field having the type _TYPE_ (a C{nbsp}identifier).
351 List the available statically-known context field names with the
352 man:lttng-add-context(1) command.
354 When a field expression doesn't exist, 'EXPR' is _false_.
356 Examples: `$ctx.prio`, `$ctx.preemptible`,
357 `$ctx.perf:cpu:stalled-cycles-frontend`.
359 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
360 application-specific context field having the type _TYPE_ (a
361 C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
363 When a field expression doesn't exist, 'EXPR' is _false_.
365 Example: `$app.server:cur_user`.
367 * Compare strings, either string fields or string literals
368 (double-quoted), with the `==` and `!=` operators.
370 When comparing to a string literal, the `*` character means ``match
371 anything''. To match a literal `*` character, use :escwc:.
373 Examples: `my_field == "user34"`, `my_field == my_other_field`,
374 `my_field == "192.168.*"`.
376 * The precedence table of the operators which are supported in 'EXPR'
377 is as follows. In this table, the highest precedence is{nbsp}1:
381 |Precedence |Operator |Description |Associativity
382 |1 |`-` |Unary minus |Right-to-left
383 |1 |`+` |Unary plus |Right-to-left
384 |1 |`!` |Logical NOT |Right-to-left
385 |1 |`~` |Bitwise NOT |Right-to-left
386 |2 |`<<` |Bitwise left shift |Left-to-right
387 |2 |`>>` |Bitwise right shift |Left-to-right
388 |3 |`&` |Bitwise AND |Left-to-right
389 |4 |`^` |Bitwise XOR |Left-to-right
390 |5 |`\|` |Bitwise OR |Left-to-right
391 |6 |`<` |Less than |Left-to-right
392 |6 |`<=` |Less than or equal to |Left-to-right
393 |6 |`>` |Greater than |Left-to-right
394 |6 |`>=` |Greater than or equal to |Left-to-right
395 |7 |`==` |Equal to |Left-to-right
396 |7 |`!=` |Not equal to |Left-to-right
397 |8 |`&&` |Logical AND |Left-to-right
398 |9 |`\|\|` |Logical OR |Left-to-right
401 Parentheses are supported to bypass the default order.
403 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
404 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
405 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
406 is _true_ while the equivalent C{nbsp}expression is _false_.
408 The arithmetic operators are :not: supported.
410 LTTng first casts all integer constants and fields to signed 64-bit
411 integers. The representation of negative integers is two's complement.
412 This means that, for example, the signed 8-bit integer field 0xff (-1)
413 becomes 0xffffffffffffffff (still -1) once casted.
415 Before a bitwise operator is applied, LTTng casts all its operands to
416 unsigned 64-bit integers, and then casts the result back to a signed
417 64-bit integer. For the bitwise NOT operator, it's the equivalent of
418 this C{nbsp}expression:
422 (int64_t) ~((uint64_t) val)
425 For the binary bitwise operators, it's the equivalent of those
430 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
431 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
432 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
433 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
434 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
437 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
438 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
442 ----------------------------
443 msg_id == 23 && size >= 2048
444 ----------------------------
446 -------------------------------------------------
447 $ctx.procname == "lttng*" && (!flag || poel < 34)
448 -------------------------------------------------
450 ---------------------------------------------------------
451 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
452 ---------------------------------------------------------
454 ---------------------------------------
455 $ctx.cpu_id == 2 && filename != "*.log"
456 ---------------------------------------
458 ------------------------------------------------
459 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
460 ------------------------------------------------
463 Migration from a recording event rule specification
464 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465 Since LTTng{nbsp}2.13, what this manual page documents is the standard,
466 common way to specify an LTTng event rule.
468 With the man:lttng-enable-event(1) command, you also specify an event
469 rule, but with deprecated options and arguments.
471 The following table shows how to translate from the
472 man:lttng-enable-event(1) options and arguments to the common event
473 rule specification options:
477 |Recording event rule option(s)/argument(s) |Common event rule option(s)
479 |nloption:--kernel and nloption:--tracepoint
480 |option:--type=++kernel:tracepoint++
482 |nloption:--kernel and nloption:--syscall
483 |option:--type=++kernel:syscall:entry+exit++
485 |nloption:--probe='LOC' and 'RECORDNAME' (non-option)
486 |option:--type=++kernel:kprobe++, option:--location='LOC', and
487 option:--event-name='RECORDNAME'
489 |nloption:--userspace-probe='LOC' and 'RECORDNAME' (non-option)
490 |option:--type=++kernel:uprobe++, option:--location='LOC', and
491 option:--event-name='RECORDNAME'
493 |nloption:--function='LOC' and 'RECORDNAME' (non-option)
494 |Not available as of LTTng{nbsp}{lttng_version}
496 |nloption:--userspace and nloption:--tracepoint
497 |option:--type=++user:tracepoint++
499 |nloption:--jul and nloption:--tracepoint
500 |option:--type=++jul:logging++
502 |nloption:--log4j and nloption:--tracepoint
503 |option:--type=++log4j:logging++
505 |nloption:--python and nloption:--tracepoint
506 |option:--type=++python:logging++
509 |option:--name='NAME'
512 |option:--name=++\'*\'++ or no option:--name option
514 |nloption:--exclude=__XNAME__[++,++__XNAME__]...
515 |option:--exclude-name='XNAME' for each 'XNAME'
517 |nloption:--loglevel='LOGLEVEL'
518 |option:--log-level=__LOGLEVEL__++..++
520 |nloption:--loglevel-only='LOGLEVEL'
521 |option:--log-level=__LOGLEVEL__
523 |nloption:--filter='EXPR'
524 |option:--filter='EXPR'
530 Instrumentation point type condition
531 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
532 See the ``<<inst-point-type-cond,Instrumentation point type
533 condition>>'' section above.
535 option:-E 'NAME', option:--event-name='NAME'::
536 With the option:--type=++kernel:kprobe++ or
537 option:--type=++kernel:uprobe++ option, set the name of the emitted
538 events to 'NAME' instead of the 'LOC' argument of the
539 option:--location='LOC' option.
541 Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may
542 change in the future.
544 option:-L 'LOC', option:--location='LOC'::
545 With the option:--type=++kernel:kprobe++ option:::
546 Set the location of the Linux kprobe to insert to 'LOC'.
550 * An address (`0x` hexadecimal prefix supported).
552 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
554 With the option:--type=++kernel:uprobe++ option:::
555 Set the location of the user space probe to insert to 'LOC'.
559 \[++elf:++]__PATH__++:++__SYMBOL__::::
560 An available symbol within a user space application or library.
564 Application or library path.
570 * The name of an application as found in the directories listed in the
571 `PATH` environment variable.
574 Symbol name of the function of which to instrument the entry.
576 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
577 command, including with its nloption:--dynamic option, which lists
581 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
582 specifying it, but this default may change in the future.
586 * `/usr/lib/libc.so.6:malloc`
587 * `./myapp:createUser`
588 * `elf:httpd:ap_run_open_htaccess`
590 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::::
591 A SystemTap User-level Statically Defined Tracing (USDT) probe
592 within a user space application or library.
596 Application or library path.
602 * The name of an application as found in the directories listed in the
603 `PATH` environment variable.
607 USDT provider and probe names.
609 For example, with the following USDT probe:
613 DTRACE_PROBE2("server", "accept_request",
614 request_id, ip_addr);
617 The provider/probe name pair is `server:accept_request`.
620 Example: `sdt:./build/server:server:accept_request`
622 option:-t 'TYPE', option:--type='TYPE'::
623 Only match events which LTTng creates from an instrumentation point
624 having the type 'TYPE'.
628 `kernel:tracepoint`:::
629 LTTng kernel tracepoint.
631 As of LTTng{nbsp}{lttng_version}, `kernel` is an alias, but this may
632 change in the future.
635 LTTng user space tracepoint.
637 As of LTTng{nbsp}{lttng_version}, `user` is an alias, but this may
638 change in the future.
640 `kernel:syscall:entry`:::
641 Linux system call entry.
643 As of LTTng{nbsp}{lttng_version}, `syscall:entry` is an alias, but this
644 may change in the future.
646 `kernel:syscall:exit`:::
647 Linux system call exit.
649 As of LTTng{nbsp}{lttng_version}, `syscall:exit` is an alias, but this
650 may change in the future.
652 `kernel:syscall:entry+exit`:::
653 Linux system call entry and exit (two distinct instrumentation
656 As of LTTng{nbsp}{lttng_version}, the following are aliases, but this
657 may change in the future:
659 * `syscall:entry+exit`
666 As of LTTng{nbsp}{lttng_version}, `kprobe` is an alias, but this may
667 change in the future.
669 You must specify the location of the kprobe to insert with the
670 option:--location option.
672 You may specify the name of the emitted events with the
673 option:--event-name option.
676 Linux user space probe.
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.
685 `java.util.logging` logging statement.
687 As of LTTng{nbsp}{lttng_version}, `jul` is an alias, but this may change
691 Apache log4j logging statement.
693 As of LTTng{nbsp}{lttng_version}, `log4j` is an alias, but this may
694 change in the future.
697 Python logging statement.
699 As of LTTng{nbsp}{lttng_version}, `python` is an alias, but this may
700 change in the future.
705 See the ``<<event-name-cond,Event name condition>>'' section above.
707 option:-n 'NAME', option:--name='NAME'::
708 Only match events of which 'NAME' matches, depending on the
709 argument of the option:--type option:
712 `kernel:tracepoint`::
714 The full name of the LTTng tracepoint.
719 The Java or Python logger name.
721 `kernel:syscall:entry`::
722 `kernel:syscall:exit`::
723 `kernel:syscall:entry+exit`::
724 The name of the system call, without any `sys_` prefix.
727 This option is :not: available with other instrumentation point types.
729 As of LTTng{nbsp}{lttng_version}, not specifying this option is
730 equivalent to specifying option:--name=++\'*\'++ (when it applies), but
731 this default may change in the future.
733 option:-x 'XNAME', option:--exclude-name='XNAME'::
734 Only match events of which 'XNAME' does :not: match the full name of
735 the LTTng user space tracepoint.
737 Only available with the option:--type=++user:tracepoint++ option.
739 'NAME' and 'XNAME' are globbing patterns: the `*` character means
740 ``match anything''. To match a literal `*` character, use :escwc:.
743 Instrumentation point log level condition
744 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
745 See the ``<<inst-point-log-level-cond,Instrumentation point log level
746 condition>>'' section above.
748 option:-l 'LOGLEVELSPEC', option:--log-level='LOGLEVELSPEC'::
749 Only match events of which the log level of the LTTng tracepoint or
750 logging statement is, depending on the format of 'LOGLEVELSPEC':
754 At least as severe as 'LOGLEVEL'.
763 This option is :not: available with the following options:
765 * option:--type=++kernel:tracepoint++
766 * option:--type=++kernel:syscall:entry++
767 * option:--type=++kernel:syscall:exit++
768 * option:--type=++kernel:syscall:entry+exit++
769 * option:--type=++kernel:kprobe++
770 * option:--type=++kernel:uprobe++
772 As of LTTng{nbsp}{lttng_version}, not specifying this option is
773 equivalent to specifying option:--log-level=++..++ (when it applies),
774 but this default may change in the future.
777 Event payload and context filter condition
778 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
779 See the ``<<filter-cond,Event payload and context filter condition>>''
782 option:-f 'EXPR', option:--filter='EXPR'::
783 Only match events of which 'EXPR', which can contain references to
784 event payload and current context fields, is _true_.
786 This option is only available with the following options:
788 * option:--type=++kernel:tracepoint++
789 * option:--type=++kernel:syscall:entry++
790 * option:--type=++kernel:syscall:exit++
791 * option:--type=++kernel:syscall:entry+exit++
794 include::common-footer.txt[]
800 man:lttng-add-trigger(1),
802 man:lttng-concepts(7)