1LTTNG-ENABLE-EVENT(1) LTTng Manual LTTNG-ENABLE-EVENT(1)
2
6 lttng-enable-event - Create or enable LTTng recording event rules
7
9 Create or enable one or more recording event rules to match Linux
10 kernel tracepoint or system call events:
11 lttng [GENERAL OPTIONS] enable-event --kernel [--tracepoint | --syscall]
13 (--all | NAME[,NAME]...) [--filter=EXPR]
14 [--session=SESSION] [--channel=CHANNEL]
15 Create or enable a recording event rule to match Linux kernel events
17 created from a dynamic instrumentation point:
18 lttng [GENERAL OPTIONS] enable-event --kernel
20 (--probe=LOC | --function=LOC | --userspace-probe=LOC) RECORDNAME
21 [--session=SESSION] [--channel=CHANNEL]
22 Create or enable one or more recording event rules to match user space
24 tracepoint events:
25 lttng [GENERAL OPTIONS] enable-event --userspace [--tracepoint]
27 (--all | NAME[,NAME]...) [--exclude=XNAME[,XNAME]...]
28 [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
29 [--session=SESSION] [--channel=CHANNEL]
30 Create or enable one or more recording event rules to match Java/Python
32 logging events:
33 lttng [GENERAL OPTIONS] enable-event (--jul | --log4j | --python)
35 [--tracepoint] (--all | NAME[,NAME]...)
36 [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL] [--filter=EXPR]
37 [--session=SESSION] [--channel=CHANNEL]
38
40 The lttng enable-event command does one of:
41 • Create one or more recording event rules.
43 • Enable one or more disabled recording event rules.
45 See the “Enable a disabled recording event rule” section below.
47 See lttng-concepts(7) to learn more about instrumentation points,
49 events, recording event rules, and event records.
50 The recording event rule(s) to create or enable belong to:
52 With the --session=SESSION option
54 The recording session named SESSION.
55 Without the --session option
57 The current recording session (see lttng-concepts(7) to learn more
58 about the current recording session).
59 With the --channel=CHANNEL option
61 The channel named CHANNEL.
62 Without the --channel option
64 The channel named channel0.
65 If there’s already a channel for the selected recording session and
67 domain which isn’t named channel0, the enable-event command fails.
68 Otherwise, it automatically creates it.
69 See the “EXAMPLES” section below for usage examples.
71 List the recording event rules of a specific recording session and/or
73 channel with the lttng-list(1) and lttng-status(1) commands.
74 Disable an enabled recording event rule with the lttng-disable-event(1)
76 command.
77 Overview of recording event rule conditions
79 For LTTng to emit and record an event E, E must satisfy all the
80 conditions of a recording event rule ER, that is:
81 Explicit conditions
83 You set the following conditions when you create or enable ER with
84 the enable-event command:
85 • The instrumentation point type from which LTTng creates E has a
87 specific type.
88 See the “Instrumentation point type condition” section below.
90 • A pattern matches the name of E while another pattern doesn’t.
92 See the “Event name condition” section below.
94 • The log level of the instrumentation point from which LTTng
96 creates E is at least as severe as some value, or is exactly
97 some value.
98 See the “Instrumentation point log level condition” section
100 below.
101 • The fields of the payload of E and the current context fields
103 satisfy a filter expression.
104 See the “Event payload and context filter condition” section
106 below.
107 Implicit conditions
109 • ER itself is enabled.
111 A recording event rule is enabled on creation.
113 Enable a disabled recording event rule with the enable-event
115 command.
116 • The channel to which ER is attached is enabled.
118 A channel is enabled on creation.
120 Enable a disabled channel with the lttng-enable-channel(1)
122 command.
123 • The recording session of ER is active (started).
125 A recording session is inactive (stopped) on creation.
127 Start an inactive recording session with the lttng-start(1)
129 command.
130 • The process for which LTTng creates E is allowed to record
132 events.
133 All processes are allowed to record events on recording session
135 creation.
136 Use the lttng-track(1) and lttng-untrack(1) commands to select
138 which processes are allowed to record events based on specific
139 process attributes.
140 The dedicated command-line options of most conditions are optional: if
142 you don’t specify the option, the associated condition is always
143 satisfied.
144 Instrumentation point type condition
146 An event E satisfies the instrumentation point type condition of a
147 recording event rule if the instrumentation point from which LTTng
148 creates E is:
149 For the Linux kernel tracing domain (--kernel option)
151 With the --tracepoint option or without any other instrumentation
153 point type option
154 An LTTng kernel tracepoint, that is, a statically defined point
155 in the source code of the kernel image or of a kernel module
156 with LTTng kernel tracer macros.
157 As of LTTng 2.13.7, this is the default instrumentation point
159 type of the Linux kernel tracing domain, but this may change in
160 the future.
161 List the available Linux kernel tracepoints with lttng list
163 --kernel. See lttng-list(1) to learn more.
164 With the --syscall option
166 The entry and exit of a Linux kernel system call.
167 List the available Linux kernel system call instrumentation
169 points with lttng list --kernel --syscall. See lttng-list(1) to
170 learn more.
171 With the --probe option
173 A Linux kprobe, that is, a single probe dynamically placed in
174 the compiled kernel code.
175 The argument of the --probe option is the location of the
177 kprobe to insert, either a symbol or a memory address, while
178 RECORDNAME is the name of the record of E (see the “Event
179 record name” section below).
180 The payload of a Linux kprobe event is empty.
182 With the --userspace-probe option
184 A Linux user space probe, that is, a single probe dynamically
185 placed at the entry of a compiled user space
186 application/library function through the kernel.
187 The argument of the --userspace-probe option is the location of
189 the user space probe to insert, one of:
190 • A path and symbol (ELF method).
192 • A path, provider name, and probe name (SystemTap User-level
194 Statically Defined Tracing (USDT) method; a DTrace-style
195 marker).
196 As of LTTng 2.13.7, LTTng only supports USDT probes which
198 are NOT reference-counted.
199 RECORDNAME is the name of the record of E (see the “Event
201 record name” section below).
202 The payload of a Linux user space probe event is empty.
204 With the --function option
206 A Linux kretprobe, that is, two probes dynamically placed at
207 the entry and exit of a function in the compiled kernel code.
208 The argument of the --function option is the location of the
210 Linux kretprobe to insert, either a symbol or a memory address,
211 while RECORDNAME is the name of the record of E (see the “Event
212 record name” section below).
213 The payload of a Linux kretprobe event is empty.
215 For the user space tracing domain (--userspace option)
217 With or without the --tracepoint option
219 An LTTng user space tracepoint, that is, a statically defined
220 point in the source code of a C/C++ application/library with
221 LTTng user space tracer macros.
222 As of LTTng 2.13.7, this is the default and sole
224 instrumentation point type of the user space tracing domain,
225 but this may change in the future.
226 List the available user space tracepoints with lttng list
228 --userspace. See lttng-list(1) to learn more.
229 For the java.util.logging (--jul option), Apache log4j (--log4j
231 option), and Python (--python option) tracing domains
232 With or without the --tracepoint option
234 A logging statement.
235 As of LTTng 2.13.7, this is the default and sole
237 instrumentation point type of the java.util.logging, Apache
238 log4j, and Python tracing domains, but this may change in the
239 future.
240 List the available Java and Python loggers with lttng list
242 --jul, lttng list --log4j, and lttng list --python. See lttng-
243 list(1) to learn more.
244 Event name condition
246 An event E satisfies the event name condition of a recording event
247 rule ER if the two following statements are true:
248 • You specify the --all option or, depending on the instrumentation
250 type condition (see the “Instrumentation point type condition”
251 section above) of ER, NAME matches:
252 LTTng tracepoint
254 The full name of the tracepoint from which LTTng creates E.
255 Note that the full name of a user space tracepoint is
257 PROVIDER:NAME, where PROVIDER is the tracepoint provider name
258 and NAME is the tracepoint name.
259 Logging statement
261 The name of the Java or Python logger from which LTTng
262 creates E.
263 Linux system call
265 The name of the system call, without any sys_ prefix, from
266 which LTTng creates E.
267 • You don’t specify the --exclude=XNAME[,XNAME]... option or,
269 depending on the instrumentation type condition of ER, none of the
270 XNAME arguments matches the full name of the user space tracepoint
271 from which LTTng creates E.
272 The --exclude option is only available with the --userspace option.
274 This condition is only meaningful for the LTTng tracepoint, logging
276 statement, and Linux system call instrumentation point types: it’s
277 always satisfied for the other types.
278 In all cases, NAME and XNAME are globbing patterns: the * character
280 means “match anything”. To match a literal * character, use \*. To
281 match a literal , character, use \,.
282 Important
284 Make sure to single-quote NAME and XNAME when they contain the *
285 character and when you run the enable-event command from a shell.
286 With the LTTng tracepoint, logging statement, and Linux system call
288 instrumentation point types, the enable-event command creates or
289 enables one independent recording event rule per NAME argument
290 (non-option, comma-separated). With the --all option, the enable-event
291 command creates or enables a single recording event rule.
292 Instrumentation point log level condition
294 An event E satisfies the instrumentation point log level condition of a
295 recording event rule if either:
296 • The --loglevel and --loglevel-only options are missing.
298 • The log level of the LTTng user space tracepoint or logging
300 statement which creates E is:
301 With the --loglevel=LOGLEVEL option
303 At least as severe as LOGLEVEL.
304 With the --loglevel-only=LOGLEVEL option
306 Exactly LOGLEVEL.
307 This condition is only meaningful for the LTTng user space tracepoint
309 and logging statement instrumentation point types: it’s always
310 satisfied for other types.
311 The available values of LOGLEVEL are, depending on the tracing domain,
313 from the most to the least severe:
314 User space (--userspace option)
316 • EMERG (0)
318 • ALERT (1)
320 • CRIT (2)
322 • ERR (3)
324 • WARNING (4)
326 • NOTICE (5)
328 • INFO (6)
330 • DEBUG_SYSTEM (7)
332 • DEBUG_PROGRAM (8)
334 • DEBUG_PROCESS (9)
336 • DEBUG_MODULE (10)
338 • DEBUG_UNIT (11)
340 • DEBUG_FUNCTION (12)
342 • DEBUG_LINE (13)
344 • DEBUG (14)
346 java.util.logging (--jul option)
348 • OFF (INT32_MAX)
350 • SEVERE (1000)
352 • WARNING (900)
354 • INFO (800)
356 • CONFIG (700)
358 • FINE (500)
360 • FINER (400)
362 • FINEST (300)
364 • ALL (INT32_MIN)
366 Apache log4j (--log4j option)
368 • OFF (INT32_MAX)
370 • FATAL (50000)
372 • ERROR (40000)
374 • WARN (30000)
376 • INFO (20000)
378 • DEBUG (10000)
380 • TRACE (5000)
382 • ALL (INT32_MIN)
384 Python (--python option)
386 • CRITICAL (50)
388 • ERROR (40)
390 • WARNING (30)
392 • INFO (20)
394 • DEBUG (10)
396 • NOTSET (0)
398 Event payload and context filter condition
400 An event E satisfies the event payload and context filter condition of
401 a recording event rule if the --filter=EXPR option is missing or if
402 EXPR is true.
403 This condition is only meaningful for the LTTng tracepoint and Linux
405 system call instrumentation point types: it’s always satisfied for
406 other types.
407 EXPR can contain references to the payload fields of E and to the
409 current context fields.
410 Important
412 Make sure to single-quote EXPR when you run the enable-event
413 command from a shell, as filter expressions typically include
414 characters having a special meaning for most shells.
415 The expected syntax of EXPR is similar to the syntax of a C language
417 conditional expression (an expression which an if statement can
418 evaluate), but there are a few differences:
419 • A NAME expression identifies an event payload field named NAME (a
421 C identifier).
422 Use the C language dot and square bracket notations to access
424 nested structure and array/sequence fields. You can only use a
425 constant, positive integer number within square brackets. If the
426 index is out of bounds, EXPR is false.
427 The value of an enumeration field is an integer.
429 When a field expression doesn’t exist, EXPR is false.
431 Examples: my_field, target_cpu, seq[7], msg.user[1].data[2][17].
433 • A $ctx.TYPE expression identifies the statically-known context
435 field having the type TYPE (a C identifier).
436 List the available statically-known context field names with the
438 lttng-add-context(1) command.
439 When a field expression doesn’t exist, EXPR is false.
441 Examples: $ctx.prio, $ctx.preemptible, $ctx.perf:cpu:stalled-
443 cycles-frontend.
444 • A $app.PROVIDER:TYPE expression identifies the application-specific
446 context field having the type TYPE (a C identifier) from the
447 provider PROVIDER (a C identifier).
448 When a field expression doesn’t exist, EXPR is false.
450 Example: $app.server:cur_user.
452 • Compare strings, either string fields or string literals
454 (double-quoted), with the == and != operators.
455 When comparing to a string literal, the * character means “match
457 anything”. To match a literal * character, use \*.
458 Examples: my_field == "user34", my_field == my_other_field,
460 my_field == "192.168.*".
461 • The precedence table of the operators which are supported in EXPR
463 is as follows. In this table, the highest precedence is 1:
464 ┌───────────┬──────────┬─────────────────┬───────────────┐
466 │Precedence │ Operator │ Description │ Associativity │
467 ├───────────┼──────────┼─────────────────┼───────────────┤
468 │1 │ - │ Unary minus │ Right-to-left │
469 ├───────────┼──────────┼─────────────────┼───────────────┤
470 │1 │ + │ Unary plus │ Right-to-left │
471 ├───────────┼──────────┼─────────────────┼───────────────┤
472 │1 │ ! │ Logical NOT │ Right-to-left │
473 ├───────────┼──────────┼─────────────────┼───────────────┤
474 │1 │ ~ │ Bitwise NOT │ Right-to-left │
475 ├───────────┼──────────┼─────────────────┼───────────────┤
476 │2 │ << │ Bitwise left │ Left-to-right │
477 │ │ │ shift │ │
478 ├───────────┼──────────┼─────────────────┼───────────────┤
479 │2 │ >> │ Bitwise right │ Left-to-right │
480 │ │ │ shift │ │
481 ├───────────┼──────────┼─────────────────┼───────────────┤
482 │3 │ & │ Bitwise AND │ Left-to-right │
483 ├───────────┼──────────┼─────────────────┼───────────────┤
484 │4 │ ^ │ Bitwise XOR │ Left-to-right │
485 ├───────────┼──────────┼─────────────────┼───────────────┤
486 │5 │ | │ Bitwise OR │ Left-to-right │
487 ├───────────┼──────────┼─────────────────┼───────────────┤
488 │6 │ < │ Less than │ Left-to-right │
489 ├───────────┼──────────┼─────────────────┼───────────────┤
490 │6 │ <= │ Less than or │ Left-to-right │
491 │ │ │ equal to │ │
492 ├───────────┼──────────┼─────────────────┼───────────────┤
493 │6 │ > │ Greater than │ Left-to-right │
494 ├───────────┼──────────┼─────────────────┼───────────────┤
495 │6 │ >= │ Greater than or │ Left-to-right │
496 │ │ │ equal to │ │
497 ├───────────┼──────────┼─────────────────┼───────────────┤
498 │7 │ == │ Equal to │ Left-to-right │
499 ├───────────┼──────────┼─────────────────┼───────────────┤
500 │7 │ != │ Not equal to │ Left-to-right │
501 ├───────────┼──────────┼─────────────────┼───────────────┤
502 │8 │ && │ Logical AND │ Left-to-right │
503 ├───────────┼──────────┼─────────────────┼───────────────┤
504 │9 │ || │ Logical OR │ Left-to-right │
505 └───────────┴──────────┴─────────────────┴───────────────┘
506 Parentheses are supported to bypass the default order.
507 Important
509 Unlike the C language, the bitwise AND and OR operators (& and
510 |) in EXPR take precedence over relational operators (<, <=, >,
511 >=, ==, and !=). This means the expression 2 & 2 == 2 is true
512 while the equivalent C expression is false.
513 The arithmetic operators are NOT supported.
514 LTTng first casts all integer constants and fields to signed 64-bit
516 integers. The representation of negative integers is two’s
517 complement. This means that, for example, the signed 8-bit integer
518 field 0xff (-1) becomes 0xffffffffffffffff (still -1) once casted.
519 Before a bitwise operator is applied, LTTng casts all its operands
521 to unsigned 64-bit integers, and then casts the result back to a
522 signed 64-bit integer. For the bitwise NOT operator, it’s the
523 equivalent of this C expression:
524 (int64_t) ~((uint64_t) val)
526 For the binary bitwise operators, it’s the equivalent of those
528 C expressions:
529 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
531 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
532 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
533 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
534 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
535 If the right-hand side of a bitwise shift operator (<< and >>) is
537 not in the [0, 63] range, then EXPR is false.
538 Note
540 Use the lttng-track(1) and lttng-untrack(1) commands to allow or
541 disallow processes to record LTTng events based on their attributes
542 instead of using equivalent statically-known context fields in EXPR
543 like $ctx.pid.
544 The former method is much more efficient.
546 EXPR examples:
548 msg_id == 23 && size >= 2048
550 $ctx.procname == "lttng*" && (!flag || poel < 34)
552 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
554 $ctx.cpu_id == 2 && filename != "*.log"
556 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
558 Event record name
560 When LTTng records an event E, the resulting event record has a name
561 which depends on the instrumentation point type condition (see the
562 “Instrumentation point type condition” section above) of the recording
563 event rule which matched E:
564 LTTng tracepoint (--kernel/--userspace and --tracepoint options)
566 Full name of the tracepoint from which LTTng creates E.
567 Note that the full name of a user space tracepoint is
569 PROVIDER:NAME, where PROVIDER is the tracepoint provider name and
570 NAME is the tracepoint name.
571 java.util.logging logging statement (--jul and --tracepoint options)
573 lttng_jul:event
574 Such an event record has a string field logger_name which contains
576 the name of the java.util.logging logger from which LTTng
577 creates E.
578 Apache log4j logging statement (--log4j and --tracepoint options)
580 lttng_log4j:event
581 Such an event record has a string field logger_name which contains
583 the name of the Apache log4j logger from which LTTng creates E.
584 Python logging statement (--python and --tracepoint options)
586 lttng_python:event
587 Such an event record has a string field logger_name which contains
589 the name of the Python logger from which LTTng creates E.
590 Linux system call (--kernel and --syscall options)
592 Entry
594 syscall_entry_NAME, where NAME is the name of the system call
595 from which LTTng creates E, without any sys_ prefix.
596 Exit
598 syscall_exit_NAME, where NAME is the name of the system call
599 from which LTTng creates E, without any sys_ prefix.
600 Linux kprobe (--kernel and --probe options), Linux user space probe
602 (--kernel and --userspace-probe options)
603 RECORDNAME (first non-option argument).
604 Linux kretprobe (--kernel and --function options)
606 Entry
608 RECORDNAME_entry
609 Exit
611 RECORDNAME_exit
612 Enable a disabled recording event rule
614 The enable-event command can enable a disabled recording event rule, as
615 listed in the output of the lttng-list(1) command.
616 You may enable a disabled recording event rule regardless of the
618 activity (started or stopped) of its recording session (see lttng-
619 start(1) and lttng-stop(1)).
620 To enable a disabled recording event rule, run the enable-event command
622 with the exact same options and arguments that you used to create it.
623 In particular, with the --filter=EXPR option, EXPR must be the exact
624 same string as the one you used on creation.
625
627 See lttng(1) for GENERAL OPTIONS.
628 Tracing domain
630 One of:
631 -j, --jul
633 Create or enable recording event rules in the java.util.logging
634 (JUL) tracing domain.
635 -k, --kernel
637 Create or enable recording event rules in the Linux kernel tracing
638 domain.
639 -l, --log4j
641 Create or enable recording event rules in the Apache log4j tracing
642 domain.
643 -p, --python
645 Create or enable recording event rules in the Python tracing
646 domain.
647 -u, --userspace
649 Create or enable recording event rules in the user space tracing
650 domain.
651 Recording target
653 -c CHANNEL, --channel=CHANNEL
654 Create or enable recording event rules attached to the channel
655 named CHANNEL instead of channel0.
656 -s SESSION, --session=SESSION
658 Create or enable recording event rules in the recording session
659 named SESSION instead of the current recording session.
660 Instrumentation point type condition
662 See the “Instrumentation point type condition” section above.
663 At most one of:
665 --function=LOC
667 Only match Linux kretprobe events.
668 Only available with the --kernel option.
670 LOC is one of:
672 • A function address (0x hexadecimal prefix supported).
674 • A function symbol name.
676 • A function symbol name and an offset (SYMBOL+OFFSET format).
678 You must specify the event record name with RECORDNAME. See the
680 “Event record name” section above to learn more.
681 --probe=LOC
683 Only match Linux kprobe events.
684 Only available with the --kernel option.
686 LOC is one of:
688 • An address (0x hexadecimal prefix supported).
690 • A symbol name.
692 • A symbol name and an offset (SYMBOL+OFFSET format).
694 You must specify the event record name with RECORDNAME. See the
696 “Event record name” section above to learn more.
697 --userspace-probe=LOC
699 Only match Linux user space probe events.
700 Only available with the --kernel option.
702 LOC is one of:
704 [elf:]PATH:SYMBOL
706 Probe an available symbol within a user space application or
707 library.
708 PATH
710 Application or library path.
711 One of:
713 • An absolute path.
715 • A relative path.
717 • The name of an application as found in the directories
719 listed in the PATH environment variable.
720 SYMBOL
722 Symbol name of the function of which to instrument the
723 entry.
724 SYMBOL can be any defined code symbol in the output of the
726 nm(1) command, including with its --dynamic option, which
727 lists dynamic symbols.
728 As of LTTng 2.13.7, not specifying elf: is equivalent to
730 specifying it, but this default may change in the future.
731 Examples:
733 • --userspace-probe=/usr/lib/libc.so.6:malloc
735 • --userspace-probe=./myapp:createUser
737 • --userspace-probe=elf:httpd:ap_run_open_htaccess
739 sdt:PATH:PROVIDER:NAME
741 Use a SystemTap User-level Statically Defined Tracing (USDT)
742 probe within a user space application or library.
743 PATH
745 Application or library path.
746 This can be:
748 • An absolute path.
750 • A relative path.
752 • The name of an application as found in the directories
754 listed in the PATH environment variable.
755 PROVIDER, NAME
757 USDT provider and probe names.
758 For example, with the following USDT probe:
760 DTRACE_PROBE2("server", "accept_request",
762 request_id, ip_addr);
763 The provider/probe name pair is server:accept_request.
765 Example: --userspace-
767 probe=sdt:./build/server:server:accept_request
768 You must specify the event record name with RECORDNAME. See the
770 “Event record name” section above to learn more.
771 --syscall
773 Only match Linux system call events.
774 Only available with the --kernel option.
776 --tracepoint
778 Only match:
779 With the --kernel or --userspace option
781 LTTng tracepoint events.
782 With the --jul, --log4j, or --python option
784 Logging events.
785 With the --kernel, not specifying any of the instrumentation point type
787 options is equivalent to specifying the --tracepoint option, but this
788 default may change in the future.
789 With the --userspace, --jul, --log4j, and --python options, not
791 specifying the --tracepoint option is equivalent to specifying it, but
792 this default may change in the future.
793 Event name condition
795 See the “Event name condition” section above.
796 -a, --all
798 Equivalent to a single NAME argument (LTTng tracepoint or logger
799 name) set to * (match anything).
800 You may NOT use this option with a NAME argument.
802 -x XNAME[,XNAME]..., --exclude=XNAME[,XNAME]...
804 Only match events of which none of the XNAME arguments matches the
805 full name of the LTTng user space tracepoint.
806 Only available with the --userspace option.
808 XNAME is a globbing pattern: the * character means “match
810 anything”. To match a literal * character, use \*. To match a
811 literal , character, use \,.
812 Instrumentation point log level condition
814 See the “Instrumentation point log level condition” section above.
815 At most one of:
817 --loglevel=LOGLEVEL
819 Only match events of which the log level of the LTTng tracepoint or
820 logging statement is at least as severe as LOGLEVEL.
821 --loglevel-only=LOGLEVEL
823 Only match events of which the log level of the LTTng tracepoint or
824 logging statement is exactly LOGLEVEL.
825 The instrumentation point log level options above are NOT available
827 with the --kernel option.
828 Event payload and context filter condition
830 See the “Event payload and context filter condition” section above.
831 -f EXPR, --filter=EXPR
833 Only match events of which EXPR, which can contain references to
834 event payload and current context fields, is true.
835 This option is only available with the --tracepoint or --syscall
837 option.
838 Program information
840 -h, --help
841 Show help.
842 This option attempts to launch /usr/bin/man to view this manual
844 page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
845 environment variable.
846 --list-options
848 List available command options and quit.
849
851 0
852 Success
853 1
855 Command error
856 2
858 Undefined command
859 3
861 Fatal error
862 4
864 Command warning (something went wrong during the command)
865
867 LTTNG_ABORT_ON_ERROR
868 Set to 1 to abort the process after the first error is encountered.
869 LTTNG_HOME
871 Path to the LTTng home directory.
872 Defaults to $HOME.
874 Useful when the Unix user running the commands has a non-writable
876 home directory.
877 LTTNG_MAN_BIN_PATH
879 Absolute path to the manual pager to use to read the LTTng
880 command-line help (with lttng-help(1) or with the --help option)
881 instead of /usr/bin/man.
882 LTTNG_SESSION_CONFIG_XSD_PATH
884 Path to the directory containing the session.xsd recording session
885 configuration XML schema.
886 LTTNG_SESSIOND_PATH
888 Absolute path to the LTTng session daemon binary (see lttng-
889 sessiond(8)) to spawn from the lttng-create(1) command.
890 The --sessiond-path general option overrides this environment
892 variable.
893
895 $LTTNG_HOME/.lttngrc
896 Unix user’s LTTng runtime configuration.
897 This is where LTTng stores the name of the Unix user’s current
899 recording session between executions of lttng(1). lttng-create(1)
900 and lttng-set-session(1) set the current recording session.
901 $LTTNG_HOME/lttng-traces
903 Default output directory of LTTng traces in local and snapshot
904 modes.
905 Override this path with the --output option of the lttng-create(1)
907 command.
908 $LTTNG_HOME/.lttng
910 Unix user’s LTTng runtime and configuration directory.
911 $LTTNG_HOME/.lttng/sessions
913 Default directory containing the Unix user’s saved recording
914 session configurations (see lttng-save(1) and lttng-load(1)).
915 /usr/local/etc/lttng/sessions
917 Directory containing the system-wide saved recording session
918 configurations (see lttng-save(1) and lttng-load(1)).
919 Note
921 $LTTNG_HOME defaults to the value of the HOME environment variable.
922
924 Example 1. Create a recording event rule which matches all Linux system
925 call events (current recording session, default channel).
926 See the --all and --syscall options.
928 $ lttng enable-event --kernel --all --syscall
930 Example 2. Create a recording event rule which matches user space
932 tracepoint events named specifically (current recording session,
933 default channel).
934 The recording event rule below matches all user space tracepoint
936 events of which the name starts with my_provider:msg.
937 $ lttng enable-event --userspace 'my_provider:msg*'
939 Example 3. Create three recording event rules which match Python
941 logging events named specifically (current recording session, default
942 channel).
943 $ lttng enable-event --python server3,ui.window,user-mgmt
945 Example 4. Create a recording event rule which matches Apache log4j
947 logging events with a specific log level range (current recording
948 session, specific channel).
949 See the --channel, --all, and --loglevel options.
951 $ lttng enable-event --log4j --channel=my-loggers \
953 --all --loglevel=INFO
954 Example 5. Create a recording event rule which matches specific Linux
956 kprobe events (current recording session, default channel).
957 The recording event rule below matches the entry of
959 usb_disconnect() Linux kernel function calls. The records of such
960 events are named usbd (see the “Event record name” section above).
961 See the --probe option.
963 $ lttng enable-event --kernel --probe=usb_disconnect usbd
965 Example 6. Create a recording event rule which matches Linux kernel
967 tracepoint events which satisfy an event payload and context filter
968 (specific recording session, default channel).
969 See the --session and --filter options.
971 $ lttng enable-event --kernel --session=my-session 'sched_*' \
973 --filter='$ctx.preemptible && comm != "systemd*"'
974 Example 7. Enable two Linux kernel tracepoint recording event rules
976 (current recording session, specific channel).
977 See the --channel option.
979 $ lttng enable-event --kernel --channel=tva ja,wendy
981
983 • LTTng project website <https://lttng.org>
984 • LTTng documentation <https://lttng.org/docs>
986 • LTTng bug tracker <https://bugs.lttng.org>
988 • Git repositories <https://git.lttng.org>
990 • GitHub organization <https://github.com/lttng>
992 • Continuous integration <https://ci.lttng.org/>
994 • Mailing list <https://lists.lttng.org/> for support and
996 development: lttng-dev@lists.lttng.org
997 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
999
1001 This program is part of the LTTng-tools project.
1002 LTTng-tools is distributed under the GNU General Public License
1004 version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
1005 See the LICENSE <https://github.com/lttng/lttng-
1006 tools/blob/master/LICENSE> file for details.
1007
1009 Special thanks to Michel Dagenais and the DORSAL laboratory
1010 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
1011 the LTTng journey.
1012 Also thanks to the Ericsson teams working on tracing which helped us
1014 greatly with detailed bug reports and unusual test cases.
1015
1017 lttng(1), lttng-disable-event(1), lttng-enable-channel(1), lttng-
1018 list(1), lttng-start(1), lttng-track(1), lttng-concepts(7)
1019LTTng 2.13.7 14 June 2021 LTTNG-ENABLE-EVENT(1)