3 :revdate: 13 April 2021
8 lttng-enable-event - Create or enable LTTng recording event rules
13 Create or enable one or more recording event rules to match Linux kernel
14 tracepoint or system call events:
17 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall]
18 (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
19 [option:--session='SESSION'] [option:--channel='CHANNEL']
21 Create or enable a recording event rule to match Linux kernel events
22 created from a dynamic instrumentation point:
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
26 (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
27 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
29 Create or enable one or more recording event rules to match
30 user space tracepoint events:
33 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint]
34 (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...]
35 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
36 [option:--session='SESSION'] [option:--channel='CHANNEL']
38 Create or enable one or more recording event rules to match
39 Java/Python logging events:
42 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python)
43 [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...)
44 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR']
45 [option:--session='SESSION'] [option:--channel='CHANNEL']
49 The `lttng enable-event` command does one of:
51 * Create one or more recording event rules.
53 * Enable one or more existing, disabled recording event rules.
55 See the <<enable,Enable a disabled recording event rule>> section
58 An _instrumentation point_ is a point, within a piece of software,
59 which, when executed, creates an LTTng _event_.
61 LTTng offers various types of instrumentation; see the
62 <<inst-point-type-cond,Instrumentation point type condition>> section
63 below to learn about them.
65 An _event rule_ is a set of conditions to match a set of events. A
66 _recording event rule_ is a specific type of event rule of which the
67 associated action is to serialize and record the matched event.
69 When LTTng creates an event{nbsp}__E__, a recording event
70 rule{nbsp}__ER__ is said to __match__{nbsp}__E__ when{nbsp}__E__
71 satisfies *all* the conditions of{nbsp}__ER__. This concept is similar
72 to a regular expression which matches a set of strings.
74 When a recording event rule matches an event, LTTng _emits_ the event,
75 therefore attempting to serialize and record it to one of the
76 sub-buffers of its attached channel (see man:lttng-enable-channel(1) to
77 learn more about LTTng channels).
79 Without the option:--channel option, the `enable-event` command selects
80 the channel named `channel0`. When the `enable-event` command creates a
81 recording event rule, it automatically creates the `channel0` channel
82 (for the specified tracing domain in the selected tracing session) if it
85 When multiple matching recording event rules are attached to the same
86 channel, LTTng attempts to serialize and record the matched event
87 _once_. In the following example, the second recording event
88 rule is redundant when both are enabled:
92 $ lttng enable-event --userspace hello:world
93 $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
96 Without the option:--session option, the `enable-event` command selects
97 the current tracing session (see man:lttng-create(1) and
98 man:lttng-set-session(1) to learn more about the current tracing
103 The event creation and emission processes are documentation concepts to
104 help understand the journey from an instrumentation point to the
105 serialization and recording of an event.
107 The actual creation of an event can be costly because LTTng needs to
108 evalute the arguments of the instrumentation point.
110 In practice, LTTng implements various optimizations for the Linux kernel
111 and user space tracing domains (option:--kernel and option:--userspace
112 options) to avoid actually creating an event when the tracer knows,
113 thanks to properties which are independent from the event payload and
114 current context, that it would never emit such an event. Those
117 * The status of the rule itself (enabled or disabled).
118 * The status of the channel (enabled or disabled; see
119 man:lttng-enable-channel(1) and man:lttng-disable-channel(1)).
120 * The activity of the tracing session (started or stopped; see
121 man:lttng-start(1) and man:lttng-stop(1)).
122 * The instrumentation point type (see the
123 <<inst-point-type-cond,Instrumentation point type>> section below).
124 * The instrumentation point name (or event name)
125 (see the <<event-name-cond,Event name condition>> section below).
126 * The instrumentation point log level (see the
127 <<inst-point-log-level-cond,Instrumentation point log level condition>>
130 In other words: if, for a given instrumentation point{nbsp}__IP__, the
131 LTTng tracer knows that it would never emit and record an event,
132 executing{nbsp}__IP__ represents a simple boolean variable check and,
133 for the kernel tracer, a few process attribute checks.
136 List the existing recording event rules of a given tracing session
137 and/or channel with the man:lttng-list(1) command.
139 Disable an existing, enabled recording event rule with the
140 man:lttng-disable-event(1) command.
143 Recording event rule overview
144 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145 For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must
146 satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that
149 Explicit conditions::
150 You set the following conditions when you create or
151 enable{nbsp}__ER__ with the `enable-event` command:
154 * The instrumentation point type from which LTTng creates{nbsp}__E__
157 See the <<inst-point-type-cond,Instrumentation point type condition>>
160 * A pattern matches the name of{nbsp}__E__ while another pattern
163 See the <<event-name-cond,Event name condition>> section below.
165 * The log level of the instrumentation point from which LTTng
166 creates{nbsp}__E__ is at least as severe as some value, or is exactly
169 See the <<inst-point-log-level-cond,Instrumentation point log level condition>>
172 * The fields of the payload of{nbsp}__E__ and the current context fields
173 satisfy a filter expression.
175 See the <<filter-cond,Event payload and context filter condition>>
179 Implicit conditions::
182 * _ER_ itself is enabled.
184 A recording event rule is enabled on creation.
186 Enable an existing, disabled recording event rule with the
187 `enable-event` command.
189 * The channel to which{nbsp}__ER__ is attached is enabled.
191 A channel is enabled on creation.
193 Enable an existing, disabled channel with the
194 man:lttng-enable-channel(1) command.
196 * The tracing session of{nbsp}__ER__ is active (started).
198 A tracing session is inactive (stopped) on creation.
200 Start an inactive tracing session with the man:lttng-start(1) command.
202 * The process for which LTTng creates{nbsp}__E__ to match is allowed to
205 All processes are allowed to record events on tracing session
208 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select
209 which processes are allowed to record events based on specific process
213 The dedicated command-line options of most conditions are optional: if
214 you don't specify the option, the associated condition is always
218 [[inst-point-type-cond]]
219 Instrumentation point type condition
220 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221 An event{nbsp}__E__ satisfies the instrumentation point type condition
222 of a recording event rule if the instrumentation point from which LTTng
223 creates{nbsp}__E__ is:
225 For the Linux kernel tracing domain (option:--kernel option)::
226 With the option:--tracepoint option or without any other instrumentation point type option:::
227 An LTTng kernel tracepoint, that is, a statically defined point
228 in the source code of the kernel image or of a kernel module
229 with LTTng kernel tracer macros.
231 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
232 point type of the Linux kernel tracing domain, but this may change in
235 List the available Linux kernel tracepoints with `lttng list --kernel`.
236 See man:lttng-list(1) to learn more.
238 With the option:--syscall option:::
239 The entry and exit of a Linux kernel system call.
241 List the available Linux kernel system call instrumentation points with
242 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
244 With the option:--probe option:::
245 A Linux kprobe, that is, a single probe dynamically placed in
246 the compiled kernel code.
248 The argument of the option:--probe option is the location of the
249 kprobe to insert, either a symbol or a
250 memory address, while 'RECORDNAME' is the name of the record
251 of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
253 The payload of a Linux kprobe event is empty.
255 With the option:--userspace-probe option:::
256 A Linux user space probe, that is, a single probe dynamically
257 placed at the entry of a compiled user space application/library
258 function through the kernel.
260 The argument of the option:--userspace-probe option is the location
261 of the user space probe to insert, one of:
264 * A path and symbol (ELF method).
265 * A path, provider name, and probe name (SystemTap User-level Statically
266 Defined Tracing (USDT) method; a DTrace-style marker).
268 As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which
269 are :not: reference-counted.
272 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
273 <<er-name,Event record name>> section below).
275 The payload of a Linux user space probe event is empty.
277 With the option:--function option:::
278 A Linux kretprobe, that is, two probes dynamically placed at the
279 entry and exit of a function in the compiled kernel code.
281 The argument of the option:--function option is the location of the
282 Linux kretprobe to insert, either a symbol or
283 a memory address, while 'RECORDNAME' is the name of the record
284 of{nbsp}__E__ (see the <<er-name,Event record name>> section below).
286 The payload of a Linux kretprobe event is empty.
288 For the user space tracing domain (option:--userspace option)::
289 With or without the option:--tracepoint option:::
290 An LTTng user space tracepoint, that is, a statically defined
291 point in the source code of a C/$$C++$$ application/library with
292 LTTng user space tracer macros.
294 As of LTTng{nbsp}{lttng_version}, this is the default and sole
295 instrumentation point type of the user space tracing domain, but this
296 may change in the future.
298 List the available user space tracepoints with `lttng list --userspace`.
299 See man:lttng-list(1) to learn more.
301 For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains::
302 With or without the option:--tracepoint option:::
305 As of LTTng{nbsp}{lttng_version}, this is the default and sole
306 instrumentation point type of the `java.util.logging`, Apache log4j, and
307 Python tracing domains, but this may change in the future.
309 List the available Java and Python loggers with `lttng list --jul`,
310 `lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
317 An event{nbsp}__E__ satisfies the event name condition of a recording
318 event rule{nbsp}__ER__ if the two following statements are true:
320 * You specify the option:--all option or, depending on the
321 instrumentation type condition (see the
322 <<inst-point-type-cond,Instrumentation point type condition>> section
323 above) of{nbsp}__ER__, 'NAME' matches:
327 The full name of the tracepoint from which LTTng creates{nbsp}__E__.
329 Note that the full name of a user space tracepoint is
330 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
331 name and __NAME__ is the tracepoint name.
334 The name of the Java or Python logger from which LTTng
338 The name of the system call, without any `sys_` prefix, from which
339 LTTng creates{nbsp}__E__.
342 * You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]...
343 option or, depending on the instrumentation type condition
344 of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of
345 the user space tracepoint from which LTTng creates{nbsp}__E__.
347 The option:--exclude option is only available with the option:--userspace
350 This condition is only meaningful for the LTTng tracepoint, logging
351 statement, and Linux system call instrumentation point types: it's
352 always satisfied for the other types.
354 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
355 character means ``match anything''. To match a literal `*` character,
356 use :escwc:. To match a literal `,` character, use
359 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
360 contain the `*` character and when you run the `enable-event` command
363 With the LTTng tracepoint, logging statement, and Linux system call
364 instrumentation point types, the `enable-event` command creates or
365 enables one independent recording event rule per 'NAME' argument
366 (non-option, comma-separated). With the option:--all option, the
367 `enable-event` command creates or enables a single recording event rule.
370 [[inst-point-log-level-cond]]
371 Instrumentation point log level condition
372 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373 An event{nbsp}__E__ satisfies the instrumentation point log level
374 condition of a recording event rule if either:
376 * The option:--loglevel and option:--loglevel-only options are
379 * The log level of the LTTng user space tracepoint or logging statement
380 which creates{nbsp}__E__ is:
381 With the option:--loglevel='LOGLEVEL' option::
382 At least as severe as 'LOGLEVEL'.
384 With the option:--loglevel-only='LOGLEVEL' option::
387 This condition is only meaningful for the LTTng user space tracepoint
388 and logging statement instrumentation point types: it's always satisfied
391 The available values of 'LOGLEVEL' are, depending on the tracing domain,
392 from the most to the least severe:
394 User space (option:--userspace option)::
395 Shortcuts such as `system` are allowed.
401 * `TRACE_WARNING` (4)
404 * `TRACE_DEBUG_SYSTEM` (7)
405 * `TRACE_DEBUG_PROGRAM` (8)
406 * `TRACE_DEBUG_PROCESS` (9)
407 * `TRACE_DEBUG_MODULE` (10)
408 * `TRACE_DEBUG_UNIT` (11)
409 * `TRACE_DEBUG_FUNCTION` (12)
410 * `TRACE_DEBUG_LINE` (13)
413 `java.util.logging` (option:--jul option)::
414 Shortcuts such as `severe` are allowed.
416 * `JUL_OFF` (`INT32_MAX`)
417 * `JUL_SEVERE` (1000)
418 * `JUL_WARNING` (900)
424 * `JUL_ALL` (`INT32_MIN`)
426 Apache log4j (option:--log4j option)::
427 Shortcuts such as `severe` are allowed.
429 * `LOG4J_OFF` (`INT32_MAX`)
430 * `LOG4J_FATAL` (50000)
431 * `LOG4J_ERROR` (40000)
432 * `LOG4J_WARN` (30000)
433 * `LOG4J_INFO` (20000)
434 * `LOG4J_DEBUG` (10000)
435 * `LOG4J_TRACE` (5000)
436 * `LOG4J_ALL` (`INT32_MIN`)
438 Python (option:--python option)::
439 Shortcuts such as `critical` are allowed.
441 * `PYTHON_CRITICAL` (50)
442 * `PYTHON_ERROR` (40)
443 * `PYTHON_WARNING` (30)
445 * `PYTHON_DEBUG` (10)
446 * `PYTHON_NOTSET` (0)
450 Event payload and context filter condition
451 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
452 An event{nbsp}__E__ satisfies the event payload and context filter
453 condition of a recording event rule if the option:--filter='EXPR'
454 option is missing or if 'EXPR' is _true_.
456 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
457 to the current context fields.
459 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the
460 `enable-event` command from a shell, as filter expressions typically
461 include characters having a special meaning for most shells.
463 The expected syntax of 'EXPR' is similar to the syntax of a
464 C{nbsp}language conditional expression (an expression which an `if`
465 statement can evaluate), but there are a few differences:
467 * A _NAME_ expression identifies an event payload field named
468 _NAME_ (a C{nbsp}identifier).
470 Use the C{nbsp}language dot and square bracket notations to access
471 nested structure and array/sequence fields. You can only use a constant,
472 positive integer number within square brackets. If the index is out of
473 bounds, 'EXPR' is _false_.
475 The value of an enumeration field is an integer.
477 When a field expression doesn't exist, 'EXPR' is _false_.
479 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
481 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
482 field having the type _TYPE_ (a C{nbsp}identifier).
484 List the available statically-known context field names with the
485 man:lttng-add-context(1) command.
487 When a field expression doesn't exist, 'EXPR' is _false_.
489 Examples: `$ctx.prio`, `$ctx.preemptible`,
490 `$ctx.perf:cpu:stalled-cycles-frontend`.
492 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
493 application-specific context field having the type _TYPE_ (a
494 C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
496 When a field expression doesn't exist, 'EXPR' is _false_.
498 Example: `$app.server:cur_user`.
500 * Compare strings, either string fields or string literals
501 (double-quoted), with the `==` and `!=` operators.
503 When comparing to a string literal, the `*` character means ``match
504 anything''. To match a literal `*` character, use :escwc:.
506 Examples: `my_field == "user34"`, `my_field == my_other_field`,
507 `my_field == "192.168.*"`.
509 * The precedence table of the operators which are supported in 'EXPR'
510 is as follows. In this table, the highest precedence is{nbsp}1:
514 |Precedence |Operator |Description |Associativity
515 |1 |`-` |Unary minus |Right-to-left
516 |1 |`+` |Unary plus |Right-to-left
517 |1 |`!` |Logical NOT |Right-to-left
518 |1 |`~` |Bitwise NOT |Right-to-left
519 |2 |`<<` |Bitwise left shift |Left-to-right
520 |2 |`>>` |Bitwise right shift |Left-to-right
521 |3 |`&` |Bitwise AND |Left-to-right
522 |4 |`^` |Bitwise XOR |Left-to-right
523 |5 |`\|` |Bitwise OR |Left-to-right
524 |6 |`<` |Less than |Left-to-right
525 |6 |`<=` |Less than or equal to |Left-to-right
526 |6 |`>` |Greater than |Left-to-right
527 |6 |`>=` |Greater than or equal to |Left-to-right
528 |7 |`==` |Equal to |Left-to-right
529 |7 |`!=` |Not equal to |Left-to-right
530 |8 |`&&` |Logical AND |Left-to-right
531 |9 |`\|\|` |Logical OR |Left-to-right
534 Parentheses are supported to bypass the default order.
536 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
537 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
538 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
539 is _true_ while the equivalent C{nbsp}expression is _false_.
541 The arithmetic operators are :not: supported.
543 LTTng first casts all integer constants and fields to signed 64-bit
544 integers. The representation of negative integers is two's complement.
545 This means that, for example, the signed 8-bit integer field 0xff (-1)
546 becomes 0xffffffffffffffff (still -1) once casted.
548 Before a bitwise operator is applied, LTTng casts all its operands to
549 unsigned 64-bit integers, and then casts the result back to a signed
550 64-bit integer. For the bitwise NOT operator, it's the equivalent of
551 this C{nbsp}expression:
555 (int64_t) ~((uint64_t) val)
558 For the binary bitwise operators, it's the equivalent of those
563 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
564 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
565 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
566 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
567 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
570 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
571 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
575 Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or
576 disallow processes to record LTTng events based on their attributes
577 instead of using equivalent statically-known context fields in 'EXPR'
580 The former method is much more efficient.
585 ----------------------------
586 msg_id == 23 && size >= 2048
587 ----------------------------
589 -------------------------------------------------
590 $ctx.procname == "lttng*" && (!flag || poel < 34)
591 -------------------------------------------------
593 ---------------------------------------------------------
594 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
595 ---------------------------------------------------------
597 ---------------------------------------
598 $ctx.cpu_id == 2 && filename != "*.log"
599 ---------------------------------------
601 ------------------------------------------------
602 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
603 ------------------------------------------------
609 When LTTng records an event{nbsp}__E__, the resulting event record has a
610 name which depends on the instrumentation point type condition (see the
611 <<inst-point-type-cond,Instrumentation point type condition>> section)
612 of the recording event rule which matched{nbsp}__E__:
614 LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options)::
615 Full name of the tracepoint from which LTTng creates{nbsp}__E__.
617 Note that the full name of a user space tracepoint is
618 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
619 name and __NAME__ is the tracepoint name.
621 `java.util.logging` logging statement (option:--jul and option:--tracepoint options)::
624 Such an event record has a string field `logger_name` which contains the
625 name of the `java.util.logging` logger from which LTTng
628 Apache log4j logging statement (option:--log4j and option:--tracepoint options)::
631 Such an event record has a string field `logger_name` which contains the
632 name of the Apache log4j logger from which LTTng creates{nbsp}__E__.
634 Python logging statement (option:--python and option:--tracepoint options)::
637 Such an event record has a string field `logger_name` which contains the
638 name of the Python logger from which LTTng creates{nbsp}__E__.
640 Linux system call (option:--kernel and option:--syscall options)::
642 ++syscall_entry_++__NAME__, where _NAME_ is the name of the
643 system call from which LTTng creates{nbsp}__E__, without any
647 ++syscall_exit_++__NAME__, where _NAME_ is the name of the
648 system call from which LTTng creates{nbsp}__E__, without any
651 Linux kprobe (option:--kernel and option:--probe options)::
652 Linux user space probe (option:--kernel and option:--userspace-probe options)::
653 'RECORDNAME' (first non-option argument).
655 Linux kretprobe (option:--kernel and option:--function options)::
657 __RECORDNAME__++_entry++
660 __RECORDNAME__++_exit++
664 Enable a disabled recording event rule
665 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
666 The `enable-event` command can enable an existing, disabled recording
667 event rule, as listed in the output of the man:lttng-list(1) command.
669 You may enable a disabled recording event rule regardless of the
670 activity (started or stopped) of its tracing session (see
671 man:lttng-start(1) and man:lttng-stop(1)).
673 To enable a disabled recording event rule, run the `enable-event`
674 command with the exact same options and arguments that you used to
675 create it. In particular, with the option:--filter='EXPR' option, 'EXPR'
676 must be the exact same string as the one you used on creation.
679 include::common-cmd-options-head.txt[]
686 option:-j, option:--jul::
687 Create or enable recording event rules in the `java.util.logging`
688 (JUL) tracing domain.
690 option:-k, option:--kernel::
691 Create or enable recording event rules in the Linux kernel tracing
694 option:-l, option:--log4j::
695 Create or enable recording event rules in the Apache log4j tracing
698 option:-p, option:--python::
699 Create or enable recording event rules in the Python tracing domain.
701 option:-u, option:--userspace::
702 Create or enable recording event rules in the user space tracing
708 option:-c 'CHANNEL', option:--channel='CHANNEL'::
709 Create or enable recording event rules attached to the channel named
710 'CHANNEL' instead of `channel0`.
712 option:-s 'SESSION', option:--session='SESSION'::
713 Create or enable recording event rules in the tracing session named
714 'SESSION' instead of the current tracing session.
717 Instrumentation point type condition
718 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
719 See the <<inst-point-type-cond,Instrumentation point type condition>>
724 option:--function='LOC'::
725 Only match Linux kretprobe events.
727 Only available with the option:--kernel option.
732 * A function address (`0x` hexadecimal prefix supported).
733 * A function symbol name.
734 * A function symbol name and an offset
735 (__SYMBOL__++pass:[+]++__OFFSET__ format).
738 You must specify the event record name with 'RECORDNAME'. See the
739 <<er-name,Event record name>> section above to learn more.
741 option:--probe='LOC'::
742 Only match Linux kprobe events.
744 Only available with the option:--kernel option.
749 * An address (`0x` hexadecimal prefix supported).
751 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
754 You must specify the event record name with 'RECORDNAME'. See the
755 <<er-name,Event record name>> section above to learn more.
757 option:--userspace-probe='LOC'::
758 Only match Linux user space probe events.
760 Only available with the option:--kernel option.
765 \[++elf:++]__PATH__++:++__SYMBOL__::
766 Probe an available symbol within a user space application or
771 Application or library path.
777 * The name of an application as found in the directories listed in the
778 `PATH` environment variable.
781 Symbol name of the function of which to instrument the entry.
783 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
784 command, including with its nloption:--dynamic option, which lists
788 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
789 specifying it, but this default may change in the future.
793 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
794 * `--userspace-probe=./myapp:createUser`
795 * `--userspace-probe=elf:httpd:ap_run_open_htaccess`
797 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
798 Use a SystemTap User-level Statically Defined Tracing (USDT) probe
799 within a user space application or library.
803 Application or library path.
809 * The name of an application as found in the directories listed in the
810 `PATH` environment variable.
814 USDT provider and probe names.
816 For example, with the following USDT probe:
820 DTRACE_PROBE2("server", "accept_request",
821 request_id, ip_addr);
824 The provider/probe name pair is `server:accept_request`.
827 Example: `--userspace-probe=sdt:./build/server:server:accept_request`
830 You must specify the event record name with 'RECORDNAME'. See the
831 <<er-name,Event record name>> section above to learn more.
834 Only match Linux system call events.
836 Only available with the option:--kernel option.
838 option:--tracepoint::
841 With the option:--kernel or option:--userspace option:::
842 LTTng tracepoint events.
843 With the option:--jul, option:--log4j, or option:--python option:::
846 With the option:--kernel, not specifying any of the instrumentation
847 point type options is equivalent to specifying the option:--tracepoint
848 option, but this default may change in the future.
850 With the option:--userspace, option:--jul, option:--log4j, and
851 option:--python options, not specifying the option:--tracepoint option
852 is equivalent to specifying it, but this default may change in the
858 See the <<event-name-cond,Event name condition>> section above.
860 option:-a, option:--all::
861 Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
862 name) set to `*` (match anything).
864 You may :not: use this option with a 'NAME' argument.
866 option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...::
867 Only match events of which none of the 'XNAME' arguments
868 matches the full name of the LTTng user space tracepoint.
870 Only available with the option:--userspace option.
872 'XNAME' is a globbing pattern: the `*` character means ``match
873 anything''. To match a literal `*` character, use :escwc:. To match
874 a literal `,` character, use :esccomma:.
877 Instrumentation point log level condition
878 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
879 See the <<inst-point-log-level-cond,Instrumentation point log level
880 condition>> section above.
884 option:--loglevel='LOGLEVEL'::
885 Only match events of which the log level of the LTTng tracepoint or
886 logging statement is at least as severe as 'LOGLEVEL'.
888 option:--loglevel-only='LOGLEVEL'::
889 Only match events of which the log level of the LTTng tracepoint or
890 logging statement is exactly 'LOGLEVEL'.
892 The instrumentation point log level options above are :not: available
893 with the option:--kernel option.
896 Event payload and context filter condition
897 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
898 See the <<filter-cond,Event payload and context filter condition>>
901 option:-f 'EXPR', option:--filter='EXPR'::
902 Only match events of which 'EXPR', which can contain references to
903 event payload and current context fields, is _true_.
906 include::common-cmd-help-options.txt[]
909 include::common-cmd-footer.txt[]
915 man:lttng-disable-event(1),
916 man:lttng-enable-channel(1),