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
21 3. A **log level** (each instrumentation point declares its own log
22 level) or log level range to match (optional; only valid for user
24 4. A **custom user expression**, or **filter**, that must evaluate to
25 _true_ when a tracepoint is executed (optional).
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
83 lttng enable-event -k --tracepoint irq_handler_entry \
84 --filter 'irq == 28 || irq == 17'
87 The wildcard symbol, `*`, matches _anything_ and may only be used at
88 the end of the string when specifying a _tracepoint_. Make sure to
89 use it between single quotes in your favorite shell to avoid
90 undesired shell expansion.
92 System call events can be enabled individually, too:
94 <pre class="term" style="position: relative">
95 <div class="since">Since 2.6</div>lttng enable-event -k --syscall open
96 lttng enable-event -k --syscall read
97 lttng enable-event -k --syscall fork,chdir,pipe
100 The complete list of available system call events can be
104 lttng list --kernel --syscall
107 You can see a list of events (enabled or disabled) using
110 lttng list some-session
113 where `some-session` is the name of the desired tracing session.
115 What you're actually doing when enabling events with specific conditions
116 is creating a **whitelist** of traceable events for a given channel.
117 Thus, the following case presents redundancy:
120 lttng enable-event -u --tracepoint my_app:hello_you
121 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG
124 The second command, matching a log level range, is useless since the first
125 command enables all tracepoints matching the same name,
128 Disabling an event is simpler: you only need to provide the event
129 name to the `disable-event` command:
132 lttng disable-event --userspace my_app:hello_you
135 This name has to match a name previously given to `enable-event` (it
136 has to be listed in the output of `lttng list some-session`).
137 The `*` wildcard is supported, as long as you also used it in a
138 previous `enable-event` invocation.
140 Disabling an event does not add it to some blacklist: it simply removes
141 it from its channel's whitelist. This is why you cannot disable an event
142 which wasn't previously enabled.
144 A disabled event doesn't generate any trace data, even if all its
145 specified conditions are met.
147 Events may be enabled and disabled at will, either when LTTng tracers
148 are active or not. Events may be enabled before a user space application