1LTTNG-ENABLE-EVENT(1) LTTng Manual LTTNG-ENABLE-EVENT(1)
2
6 lttng-enable-event - Create or enable LTTng event rules
7
9 Create or enable Linux kernel event rules:
10 lttng [GENERAL OPTIONS] enable-event --kernel
12 [--probe=SOURCE | --function=SOURCE | --syscall |
13 --userspace-probe=SOURCE]
14 [--filter=EXPR] [--session=SESSION]
15 [--channel=CHANNEL] EVENT[,EVENT]...
16 Create or enable an "all" Linux kernel event rule:
18 lttng [GENERAL OPTIONS] enable-event --kernel --all [--syscall]
20 [--filter=EXPR] [--session=SESSION] [--channel=CHANNEL]
21 Create or enable application/library event rules:
23 lttng [GENERAL OPTIONS] enable-event
25 (--userspace | --jul | --log4j | --python)
26 [--filter=EXPR] [--exclude=EVENT[,EVENT]...]
27 [--loglevel=LOGLEVEL | --loglevel-only=LOGLEVEL]
28 [--session=SESSION] [--channel=CHANNEL] (--all | EVENT[,EVENT]...)
29
31 The lttng enable-event command can create a new event rule, or enable
32 one or more existing and disabled ones.
33 An event rule created by lttng enable-event is a set of conditions that
35 must be satisfied in order for an actual event to be emitted by an
36 LTTng tracer when the execution of an application or a library or the
37 Linux kernel reaches an event source (tracepoint, system call, dynamic
38 probe). Event sources can be listed with the lttng-list(1) command.
39 The lttng-disable-event(1) command can be used to disable existing
41 event rules.
42 Event rules are always assigned to a channel when they are created. If
44 the --channel option is omitted, a default channel named channel0 is
45 used (and created automatically if it does not exist for the specified
46 domain in the selected tracing session).
47 If the --session option is omitted, the chosen channel is picked from
49 the current tracing session.
50 Events can be enabled while tracing is active (use lttng-start(1) to
52 make a tracing session active).
53 Event source types
55 Five types of event sources are available in the Linux kernel tracing
56 domain (--kernel option):
57 Tracepoint (--tracepoint option; default)
59 A Linux kernel tracepoint, that is, a static instrumentation point
60 placed in the kernel source code. Standard tracepoints are designed
61 and placed in the source code by developers and record useful
62 payload fields.
63 Dynamic kernel probe (--probe option)
65 A Linux kernel kprobe, that is, an instrumentation point placed
66 dynamically in the compiled kernel code. Dynamic probe events do
67 not record any payload field.
68 Dynamic user space probe (--userspace-probe option)
70 A Linux kernel uprobe, that is, an instrumentation point placed
71 dynamically in the compiled user space application/library through
72 the kernel. Dynamic user space probe events do not record any
73 payload field.
74 See the Dynamic user space probes section for more information.
76 Function probe (--function option)
78 A Linux kernel kretprobe, that is, two instrumentation points
79 placed dynamically where a function is entered and where it returns
80 in the compiled kernel code. Function probe events do not record
81 any payload field.
82 System call (--syscall option)
84 A Linux kernel system call. Two instrumentation points are
85 statically placed where a system call function is entered and where
86 it returns in the compiled kernel code. System call event sources
87 record useful payload fields.
88 The application tracing domains (--userspace, --jul, --log4j, or
90 --python options) only support tracepoints. In the cases of the JUL,
91 Apache log4j, and Python domains, the event names correspond to logger
92 names.
93 Understanding event rule conditions
95 When creating an event rule with lttng enable-event, conditions are
96 specified using options. The logical conjunction (logical AND) of all
97 those conditions must be true when an event source is reached by an
98 application or by the Linux kernel in order for an actual event to be
99 emitted by an LTTng tracer.
100 Any condition that is not explicitly specified on creation is
102 considered a don’t care.
103 For example, consider the following commands:
105 $ lttng enable-event --userspace hello:world
107 $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
108 Here, two event rules are created. The first one has a single
110 condition: the tracepoint name must match hello:world. The second one
111 has two conditions:
112 • The tracepoint name must match hello:world, and
114 • The tracepoint’s defined log level must be at least as severe as
116 the TRACE_INFO level.
117 In this case, the second event rule is pointless because the first one
119 is more general: it does not care about the tracepoint’s log level. If
120 an event source matching both event rules is reached by the
121 application’s execution, only one event is emitted.
122 The available conditions for the Linux kernel domain are:
124 • Tracepoint/system call name (EVENT argument with --tracepoint or
126 --syscall options) or dynamic probe/function name/address (--probe,
127 --userspace-probe, and --function option’s argument) which must
128 match event source’s equivalent.
129 You can use * characters at any place in the tracepoint or system
131 call name as wildcards to match zero or more characters. To use a
132 literal * character, use \*.
133 • Filter expression (--filter option) executed against the dynamic
135 values of event fields at execution time that must evaluate to
136 true. See the Filter expression section below for more information.
137 The available conditions for the application domains are:
139 • Tracepoint name (EVENT with --tracepoint option) which must match
141 event source’s equivalent.
142 You can use * characters at any place in the tracepoint name as
144 wildcards to match zero or more characters. To use a literal *
145 character, use \*. When you create an event rule with a tracepoint
146 name containing a wildcard, you can exclude specific tracepoint
147 names from the match with the --exclude option.
148 • Filter expression (--filter option) executed against the dynamic
150 values of event fields at execution time that must evaluate to
151 true. See the Filter expression section below for more information.
152 • Event’s log level that must be at least as severe as a given log
154 level (--loglevel option) or match exactly a given log level
155 (--loglevel-only option).
156 When using lttng enable-event with a set of conditions that does not
158 currently exist for the chosen tracing session, domain, and channel, a
159 new event rule is created. Otherwise, the existing event rule is
160 enabled if it is currently disabled (see lttng-disable-event(1)).
161 The --all option can be used alongside the --tracepoint or --syscall
163 options. When this option is used, no EVENT argument must be specified.
164 This option defines a single event rule matching all the possible
165 events of a given tracing domain for the chosen channel and tracing
166 session. It is the equivalent of an EVENT argument named * (wildcard).
167 Filter expression
169 A filter expression can be specified with the --filter option when
170 creating a new event rule. If the filter expression evaluates to true
171 when executed against the dynamic values of an event’s fields when
172 tracing, the filtering condition passes.
173 Note
175 Make sure to single-quote the filter expression when running the
176 command from a shell, as filter expressions typically include
177 characters having a special meaning for most shells.
178 The filter expression syntax is similar to C language conditional
180 expressions (expressions that can be evaluated by an if statement),
181 albeit with a few differences:
182 • C integer and floating point number constants are supported, as
184 well as literal strings between double quotes ("). You can use *
185 characters at any place in a literal string as wildcards to match
186 zero or more characters. To use a literal * character, use \*.
187 Examples: 32, -0x17, 0755, 12.34, "a \"literal string\"",
189 "src/*/*.h".
190 • The dynamic value of an event field is read by using its name as a
192 C identifier.
193 The dot and square bracket notations are available, like in the C
195 language, to access nested structure and array/sequence fields.
196 Only a constant, positive integer number can be used within square
197 brackets. If the index is out of bounds, the whole filter
198 expression evaluates to false (the event is discarded).
199 An enumeration field’s value is an integer.
201 When the expression’s field does not exist, the whole filter
203 expression evaluates to false.
204 Examples: my_field, target_cpu, seq[7], msg.user[1].data[2][17].
206 • The dynamic value of a statically-known context field is read by
208 prefixing its name with $ctx.. Statically-known context fields are
209 context fields added to channels without the $app. prefix using
210 the lttng-add-context(1) command.
211 When the expression’s statically-known context field does not
213 exist, the whole filter expression evaluates to false.
214 Examples: $ctx.prio, $ctx.preemptible, $ctx.perf:cpu:stalled-
216 cycles-frontend.
217 • The dynamic value of an application-specific context field is read
219 by prefixing its name with $app. (follows the format used to add
220 such a context field with the lttng-add-context(1) command).
221 When the expression’s application-specific context field does not
223 exist, the whole filter expression evaluates to false.
224 Example: $app.server:cur_user.
226 The following precedence table shows the operators which are supported
228 in a filter expression. In this table, the highest precedence is 1.
229 Parentheses are supported to bypass the default order.
230 Important
232 Unlike the C language, the lttng enable-event filter expression
233 syntax’s bitwise AND and OR operators (& and |) take precedence
234 over relational operators (<, <=, >, >=, ==, and !=). This means
235 the filter expression 2 & 2 == 2 is true while the equivalent C
236 expression is false.
237 ┌───────────┬──────────┬─────────────────┬───────────────┐
239 │Precedence │ Operator │ Description │ Associativity │
240 ├───────────┼──────────┼─────────────────┼───────────────┤
241 │ │ │ │ │
242 │1 │ - │ Unary minus │ Right-to-left │
243 ├───────────┼──────────┼─────────────────┼───────────────┤
244 │ │ │ │ │
245 │1 │ + │ Unary plus │ Right-to-left │
246 ├───────────┼──────────┼─────────────────┼───────────────┤
247 │ │ │ │ │
248 │1 │ ! │ Logical NOT │ Right-to-left │
249 ├───────────┼──────────┼─────────────────┼───────────────┤
250 │ │ │ │ │
251 │1 │ ~ │ Bitwise NOT │ Right-to-left │
252 ├───────────┼──────────┼─────────────────┼───────────────┤
253 │ │ │ │ │
254 │2 │ << │ Bitwise left │ Left-to-right │
255 │ │ │ shift │ │
256 ├───────────┼──────────┼─────────────────┼───────────────┤
257 │ │ │ │ │
258 │2 │ >> │ Bitwise right │ Left-to-right │
259 │ │ │ shift │ │
260 ├───────────┼──────────┼─────────────────┼───────────────┤
261 │ │ │ │ │
262 │3 │ & │ Bitwise AND │ Left-to-right │
263 ├───────────┼──────────┼─────────────────┼───────────────┤
264 │ │ │ │ │
265 │4 │ ^ │ Bitwise XOR │ Left-to-right │
266 ├───────────┼──────────┼─────────────────┼───────────────┤
267 │ │ │ │ │
268 │5 │ | │ Bitwise OR │ Left-to-right │
269 ├───────────┼──────────┼─────────────────┼───────────────┤
270 │ │ │ │ │
271 │6 │ < │ Less than │ Left-to-right │
272 ├───────────┼──────────┼─────────────────┼───────────────┤
273 │ │ │ │ │
274 │6 │ <= │ Less than or │ Left-to-right │
275 │ │ │ equal to │ │
276 ├───────────┼──────────┼─────────────────┼───────────────┤
277 │ │ │ │ │
278 │6 │ > │ Greater than │ Left-to-right │
279 ├───────────┼──────────┼─────────────────┼───────────────┤
280 │ │ │ │ │
281 │6 │ >= │ Greater than or │ Left-to-right │
282 │ │ │ equal to │ │
283 ├───────────┼──────────┼─────────────────┼───────────────┤
284 │ │ │ │ │
285 │7 │ == │ Equal to │ Left-to-right │
286 ├───────────┼──────────┼─────────────────┼───────────────┤
287 │ │ │ │ │
288 │7 │ != │ Not equal to │ Left-to-right │
289 ├───────────┼──────────┼─────────────────┼───────────────┤
290 │ │ │ │ │
291 │8 │ && │ Logical AND │ Left-to-right │
292 ├───────────┼──────────┼─────────────────┼───────────────┤
293 │ │ │ │ │
294 │9 │ || │ Logical OR │ Left-to-right │
295 └───────────┴──────────┴─────────────────┴───────────────┘
296 The arithmetic operators are NOT supported.
298 All integer constants and fields are first casted to signed 64-bit
300 integers. The representation of negative integers is two’s complement.
301 This means that, for example, the signed 8-bit integer field 0xff (-1)
302 becomes 0xffffffffffffffff (still -1) once casted.
303 Before a bitwise operator is applied, all its operands are casted to
305 unsigned 64-bit integers, and the result is casted back to a signed
306 64-bit integer. For the bitwise NOT operator, it is the equivalent of
307 this C expression:
308 (int64_t) ~((uint64_t) val)
310 For the binary bitwise operators, it is the equivalent of those C
312 expressions:
313 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
315 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
316 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
317 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
318 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
319 If the right-hand side of a bitwise shift operator (<< and >>) is not
321 in the [0, 63] range, the whole filter expression evaluates to false.
322 Note
324 Although it is possible to filter the process ID of an event when
325 the pid context has been added to its channel using, for example,
326 $ctx.pid == 2832, it is recommended to use the PID tracker instead,
327 which is much more efficient (see lttng-track(1)).
328 Filter expression examples:
330 msg_id == 23 && size >= 2048
332 $ctx.procname == "lttng*" && (!flag || poel < 34)
334 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
336 $ctx.cpu_id == 2 && filename != "*.log"
338 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
340 Log levels
342 Tracepoints and log statements in applications have an attached log
343 level. Application event rules can contain a log level condition.
344 With the --loglevel option, the event source’s log level must be at
346 least as severe as the option’s argument. With the --loglevel-only
347 option, the event source’s log level must match the option’s argument.
348 The available log levels are:
350 User space domain (--userspace option)
352 Shortcuts such as system are allowed.
353 • TRACE_EMERG (0)
355 • TRACE_ALERT (1)
357 • TRACE_CRIT (2)
359 • TRACE_ERR (3)
361 • TRACE_WARNING (4)
363 • TRACE_NOTICE (5)
365 • TRACE_INFO (6)
367 • TRACE_DEBUG_SYSTEM (7)
369 • TRACE_DEBUG_PROGRAM (8)
371 • TRACE_DEBUG_PROCESS (9)
373 • TRACE_DEBUG_MODULE (10)
375 • TRACE_DEBUG_UNIT (11)
377 • TRACE_DEBUG_FUNCTION (12)
379 • TRACE_DEBUG_LINE (13)
381 • TRACE_DEBUG (14)
383 java.util.logging domain (--jul option)
385 Shortcuts such as severe are allowed.
386 • JUL_OFF (INT32_MAX)
388 • JUL_SEVERE (1000)
390 • JUL_WARNING (900)
392 • JUL_INFO (800)
394 • JUL_CONFIG (700)
396 • JUL_FINE (500)
398 • JUL_FINER (400)
400 • JUL_FINEST (300)
402 • JUL_ALL (INT32_MIN)
404 Apache log4j domain (--log4j option)
406 Shortcuts such as severe are allowed.
407 • LOG4J_OFF (INT32_MAX)
409 • LOG4J_FATAL (50000)
411 • LOG4J_ERROR (40000)
413 • LOG4J_WARN (30000)
415 • LOG4J_INFO (20000)
417 • LOG4J_DEBUG (10000)
419 • LOG4J_TRACE (5000)
421 • LOG4J_ALL (INT32_MIN)
423 Python domain (--python option)
425 Shortcuts such as critical are allowed.
426 • PYTHON_CRITICAL (50)
428 • PYTHON_ERROR (40)
430 • PYTHON_WARNING (30)
432 • PYTHON_INFO (20)
434 • PYTHON_DEBUG (10)
436 • PYTHON_NOTSET (0)
438 Dynamic user space probes
440 With the --userspace-probe option, you can instrument function entries
441 of any user space binary (application or library) using either an
442 available symbol name or a SystemTap User-level Statically Defined
443 Tracing (USDT, a DTrace-style marker) probe’s provider and probe names.
444 As of this version, only USDT probes that are NOT surrounded by a
445 reference counter (semaphore) are supported.
446 The --userspace-probe option must be specified with the --kernel option
448 because it uses Linux’s uprobe feature to dynamically instrument a user
449 space application or library.
450 As of this version, dynamic probe events do not record any payload
452 field.
453
455 General options are described in lttng(1).
456 Domain
458 One of:
459 -j, --jul
461 Create or enable event rules in the java.util.logging (JUL) domain.
462 -k, --kernel
464 Create or enable event rules in the Linux kernel domain.
465 -l, --log4j
467 Create or enable event rules in the Apache log4j domain.
468 -p, --python
470 Create or enable event rules in the Python domain.
471 -u, --userspace
473 Create or enable event rules in the user space domain.
474 Target
476 -c CHANNEL, --channel=CHANNEL
477 Create or enable event rules in the channel named CHANNEL instead
478 of the default channel name channel0.
479 -s SESSION, --session=SESSION
481 Create or enable event rules in the tracing session named SESSION
482 instead of the current tracing session.
483 Event source type
485 One of:
486 --function=SOURCE
488 Dynamic kernel return probe (kretprobe). Only available with the
489 --kernel domain option. SOURCE is one of:
490 • Function address (0x prefix supported)
492 • Function symbol name
494 • Function symbol name and offset (SYMBOL+OFFSET format)
496 --probe=SOURCE
498 Dynamic kernel probe (kprobe). Only available with the --kernel
499 domain option. SOURCE is one of:
500 • Address (0x prefix supported)
502 • Symbol name
504 • Symbol name and offset (SYMBOL+OFFSET format)
506 --userspace-probe=SOURCE
508 Dynamic user space probe (uprobe). Only available with the --kernel
509 domain option. See the Dynamic user space probes section.
510 SOURCE is one of:
512 [elf:]PATH:SYMBOL
514 Dynamically instrument an available symbol within a user space
515 application or library.
516 PATH
518 Application or library path.
519 This can be:
521 • An absolute path.
523 • A relative path.
525 • An application’s name as found in the directories
527 listed in the PATH environment variable.
528 SYMBOL
530 Symbol name of the function of which to instrument the
531 entry.
532 This can be any defined code symbol listed by the nm(1)
534 command (including with its --dynamic option which lists
535 dynamic symbols).
536 As of this version, not specifying elf: is equivalent to
538 specifying it.
539 Examples:
541 • --userspace-probe=/usr/lib/libc.so.6:malloc
543 • --userspace-probe=./myapp:createUser
545 • --userspace-probe=httpd:ap_run_open_htaccess
547 sdt:PATH:PROVIDER:NAME
549 Dynamically instrument a USDT probe within a user space
550 application or library.
551 PATH
553 Application or library path.
554 This can be:
556 • An absolute path.
558 • A relative path.
560 • An application’s name as found in the directories
562 listed in the PATH environment variable.
563 PROVIDER:NAME
565 USDT provider and probe names.
566 For example, with the following USDT probe:
568 DTRACE_PROBE2("server", "accept_request",
570 request_id, ip_addr);
571 The provider/probe name pair is server:accept_request.
573 Example:
575 • --userspace-probe=sdt:./build/server:server:accept_request
577 --syscall
579 Linux kernel system call. Only available with the --kernel domain
580 option.
581 --tracepoint
583 Linux kernel or application tracepoint (default).
584 Log level
586 One of:
587 --loglevel=LOGLEVEL
589 Add log level condition to the event rule: the event source’s
590 defined log level must be at least as severe as LOGLEVEL. See the
591 Log levels section above for the available log levels. Only
592 available with application domains.
593 --loglevel-only=LOGLEVEL
595 Add log level condition to the event rule: the event source’s
596 defined log level must match LOGLEVEL. See the Log levels section
597 above for the available log levels. Only available with application
598 domains.
599 Filtering and exclusion
601 -x EVENT[,EVENT]..., --exclude=EVENT[,EVENT]...
602 Exclude events named EVENT from the event rule. This option can be
603 used when the command’s EVENT argument contains at least one
604 wildcard star (*) to exclude specific names. EVENT can also
605 contain wildcard stars. To use a literal , character, use \,. Only
606 available with the --userspace domain.
607 -f EXPR, --filter=EXPR
609 Add filter expression condition to the event rule. Expression EXPR
610 must evaluate to true when executed against the dynamic values of
611 event fields. See the Filter expression section above for more
612 information.
613 Shortcuts
615 -a, --all
616 Equivalent to an EVENT argument named * (wildcard) when also using
617 the --tracepoint (default) or --syscall option.
618 Program information
620 -h, --help
621 Show command help.
622 This option, like lttng-help(1), attempts to launch /usr/bin/man to
624 view the command’s man page. The path to the man pager can be
625 overridden by the LTTNG_MAN_BIN_PATH environment variable.
626 --list-options
628 List available command options.
629
631 LTTNG_ABORT_ON_ERROR
632 Set to 1 to abort the process after the first error is encountered.
633 LTTNG_HOME
635 Overrides the $HOME environment variable. Useful when the user
636 running the commands has a non-writable home directory.
637 LTTNG_MAN_BIN_PATH
639 Absolute path to the man pager to use for viewing help information
640 about LTTng commands (using lttng-help(1) or lttng COMMAND --help).
641 LTTNG_SESSION_CONFIG_XSD_PATH
643 Path in which the session.xsd session configuration XML schema may
644 be found.
645 LTTNG_SESSIOND_PATH
647 Full session daemon binary path.
648 The --sessiond-path option has precedence over this environment
650 variable.
651 Note that the lttng-create(1) command can spawn an LTTng session daemon
653 automatically if none is running. See lttng-sessiond(8) for the
654 environment variables influencing the execution of the session daemon.
655
657 $LTTNG_HOME/.lttngrc
658 User LTTng runtime configuration.
659 This is where the per-user current tracing session is stored
661 between executions of lttng(1). The current tracing session can be
662 set with lttng-set-session(1). See lttng-create(1) for more
663 information about tracing sessions.
664 $LTTNG_HOME/lttng-traces
666 Default output directory of LTTng traces. This can be overridden
667 with the --output option of the lttng-create(1) command.
668 $LTTNG_HOME/.lttng
670 User LTTng runtime and configuration directory.
671 $LTTNG_HOME/.lttng/sessions
673 Default location of saved user tracing sessions (see lttng-save(1)
674 and lttng-load(1)).
675 /usr/local/etc/lttng/sessions
677 System-wide location of saved tracing sessions (see lttng-save(1)
678 and lttng-load(1)).
679 Note
681 $LTTNG_HOME defaults to $HOME when not explicitly set.
682
684 0
685 Success
686 1
688 Command error
689 2
691 Undefined command
692 3
694 Fatal error
695 4
697 Command warning (something went wrong during the command)
698
700 If you encounter any issue or usability problem, please report it on
701 the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-tools>.
702
704 • LTTng project website <https://lttng.org>
705 • LTTng documentation <https://lttng.org/docs>
707 • Git repositories <http://git.lttng.org>
709 • GitHub organization <http://github.com/lttng>
711 • Continuous integration <http://ci.lttng.org/>
713 • Mailing list <http://lists.lttng.org> for support and development:
715 lttng-dev@lists.lttng.org
716 • IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
718
720 This program is part of the LTTng-tools project.
721 LTTng-tools is distributed under the GNU General Public License version
723 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the
724 LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file
725 for details.
726
728 Special thanks to Michel Dagenais and the DORSAL laboratory
729 <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
730 the LTTng journey.
731 Also thanks to the Ericsson teams working on tracing which helped us
733 greatly with detailed bug reports and unusual test cases.
734
736 lttng-disable-event(1), lttng(1)
737LTTng 2.12.4 4 April 2019 LTTNG-ENABLE-EVENT(1)