2 id: enabling-disabling-events
5 Inside a tracing session, individual events may be enabled or disabled
6 so that tracing them may or may not generate trace data.
8 We sometimes use the term _event_ metonymically throughout this text to
9 refer to a specific condition, or _rule_, that could lead, when
10 satisfied, to an actual occurring event (a point at a specific position
11 in source code/binary program, logical processor and time capturing
12 some payload) being recorded as trace data. This specific condition is
15 1. A **domain** (kernel, user space, `java.util.logging`, or log4j)
17 2. One or many **instrumentation points** in source code or binary
18 program (tracepoint name, address, symbol name, function name,
19 logger name, amongst other types of probes) to be executed (required).
20 3. A **log level** (each instrumentation point declares its own log
21 level) or log level range to match (optional; only valid for user
23 4. A **custom user expression**, or **filter**, that must evaluate to
24 _true_ when a tracepoint is executed (optional; only valid for user
27 All conditions are specified using arguments passed to the
28 `enable-event` command of the `lttng` tool.
30 Condition 1 is specified using either `--kernel`/`-k` (kernel),
31 `--userspace`/`-u` (user space), `--jul`/`-j`
32 (<abbr title="java.util.logging">JUL</abbr>), or `--log4j`/`-l` (log4j).
33 Exactly one of those four arguments must be specified.
35 Condition 2 is specified using one of:
37 * `--tracepoint`: **tracepoint**
38 * `--probe`: **dynamic probe** (address, symbol name or combination
39 of both in binary program; only valid for kernel domain)
40 * `--function`: **function entry/exit** (address, symbol name or
41 combination of both in binary program; only valid for kernel domain)
42 * `--syscall`: **system call entry/exit** (only valid for kernel
45 When none of the above is specified, `enable-event` defaults to
48 Condition 3 is specified using one of:
50 * `--loglevel`: log level range from 0 to a specific log level
51 * `--loglevel-only`: specific log level
53 See `lttng enable-event --help` for the complete list of log level
56 Condition 4 is specified using the `--filter` option. This filter is
57 a C-like expression, potentially reading real-time values of event
58 fields, that has to evaluate to _true_ for the condition to be satisfied.
59 Event fields are read using plain identifiers while context fields
60 must be prefixed with `$ctx.`. See `lttng enable-event --help` for
63 The aforementioned arguments are combined to create and enable events.
64 Each unique combination of arguments leads to a different
65 _enabled event_. The log level and filter arguments are optional, their
66 default values being respectively all log levels and a filter which
67 always returns _true_.
69 Here are a few examples (you must
70 [create a tracing session](#doc-creating-destroying-tracing-sessions)
74 lttng enable-event -u --tracepoint my_app:hello_world
75 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_WARNING
76 lttng enable-event -u --tracepoint 'my_other_app:*'
77 lttng enable-event -u --tracepoint my_app:foo_bar \
78 --filter 'some_field <= 23 && !other_field'
79 lttng enable-event -k --tracepoint sched_switch
80 lttng enable-event -k --tracepoint gpio_value
81 lttng enable-event -k --function usb_probe_device usb_probe_device
82 lttng enable-event -k --syscall --all
85 The wildcard symbol, `*`, matches _anything_ and may only be used at
86 the end of the string when specifying a _tracepoint_. Make sure to
87 use it between single quotes in your favorite shell to avoid
88 undesired shell expansion.
90 System call events can be enabled individually, too:
93 lttng enable-event -k --syscall open
94 lttng enable-event -k --syscall read
95 lttng enable-event -k --syscall fork,chdir,pipe
98 The complete list of available system call events can be
102 lttng list --kernel --syscall
105 You can see a list of events (enabled or disabled) using
108 lttng list some-session
111 where `some-session` is the name of the desired tracing session.
113 What you're actually doing when enabling events with specific conditions
114 is creating a **whitelist** of traceable events for a given channel.
115 Thus, the following case presents redundancy:
118 lttng enable-event -u --tracepoint my_app:hello_you
119 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG
122 The second command, matching a log level range, is useless since the first
123 command enables all tracepoints matching the same name,
126 Disabling an event is simpler: you only need to provide the event
127 name to the `disable-event` command:
130 lttng disable-event --userspace my_app:hello_you
133 This name has to match a name previously given to `enable-event` (it
134 has to be listed in the output of `lttng list some-session`).
135 The `*` wildcard is supported, as long as you also used it in a
136 previous `enable-event` invocation.
138 Disabling an event does not add it to some blacklist: it simply removes
139 it from its channel's whitelist. This is why you cannot disable an event
140 which wasn't previously enabled.
142 A disabled event doesn't generate any trace data, even if all its
143 specified conditions are met.
145 Events may be enabled and disabled at will, either when LTTng tracers
146 are active or not. Events may be enabled before a user space application