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 or Java Util Logging) (required).
16 2. One or many **instrumentation points** in source code or binary
17 program (tracepoint name, address, symbol name, function name,
18 logger name, etc.) to be executed (required).
19 3. A **log level** (each instrumentation point declares its own log
20 level) or log level range to match (optional; only valid for user
22 4. A **custom user expression**, or **filter**, that must evaluate to
23 _true_ when a tracepoint is executed (optional; only valid for user
26 All conditions are specified using arguments passed to the
27 `enable-event` command of the `lttng` tool.
29 Condition 1 is specified using either `--kernel/-k` (kernel),
30 `--userspace/-u` (user space) or `--jul/-j`
31 (<abbr title="Java Util Logging">JUL</abbr>). Exactly one of those
32 three arguments must be specified.
34 Condition 2 is specified using one of:
36 * `--tracepoint`: **tracepoint**
37 * `--probe`: **dynamic probe** (address, symbol name or combination
38 of both in binary program; only valid for kernel domain)
39 * `--function`: **function entry/exit** (address, symbol name or
40 combination of both in binary program; only valid for kernel domain)
41 * `--syscall`: **system call entry/exit** (only valid for kernel
44 When none of the above is specified, `enable-event` defaults to
47 Condition 3 is specified using one of:
49 * `--loglevel`: log level range from 0 to a specific log level
50 * `--loglevel-only`: specific log level
52 See `lttng enable-event --help` for the complete list of log level
55 Condition 4 is specified using the `--filter` option. This filter is
56 a C-like expression, potentially reading real-time values of event
57 fields, that has to evaluate to _true_ for the condition to be satisfied.
58 Event fields are read using plain identifiers while context fields
59 must be prefixed with `$ctx.`. See `lttng enable-event --help` for
62 The aforementioned arguments are combined to create and enable events.
63 Each unique combination of arguments leads to a different
64 _enabled event_. The log level and filter arguments are optional, their
65 default values being respectively all log levels and a filter which
66 always returns _true_.
68 Here are a few examples (you must
69 [create a tracing session](#doc-creating-destroying-tracing-sessions)
73 lttng enable-event -u --tracepoint my_app:hello_world
74 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_WARNING
75 lttng enable-event -u --tracepoint 'my_other_app:*'
76 lttng enable-event -u --tracepoint my_app:foo_bar \
77 --filter 'some_field <= 23 && !other_field'
78 lttng enable-event -k --tracepoint sched_switch
79 lttng enable-event -k --tracepoint gpio_value
80 lttng enable-event -k --function usb_probe_device usb_probe_device
81 lttng enable-event -k --syscall --all
84 The wildcard symbol, `*`, matches _anything_ and may only be used at
85 the end of the string when specifying a _tracepoint_. Make sure to
86 use it between single quotes in your favorite shell to avoid
87 undesired shell expansion.
89 You can see a list of events (enabled or disabled) using
92 lttng list some-session
95 where `some-session` is the name of the desired tracing session.
97 What you're actually doing when enabling events with specific conditions
98 is creating a **whitelist** of traceable events for a given channel.
99 Thus, the following case presents redundancy:
102 lttng enable-event -u --tracepoint my_app:hello_you
103 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG
106 The second command, matching a log level range, is useless since the first
107 command enables all tracepoints matching the same name,
110 Disabling an event is simpler: you only need to provide the event
111 name to the `disable-event` command:
114 lttng disable-event -u my_app:hello_you
117 This name has to match a name previously given to `enable-event` (it
118 has to be listed in the output of `lttng list some-session`).
119 The `*` wildcard is supported, as long as you also used it in a
120 previous `enable-event` invocation.
122 Disabling an event does not add it to some blacklist: it simply removes
123 it from its channel's whitelist. This is why you cannot disable an event
124 which wasn't previously enabled.
126 A disabled event will not generate any trace data, even if all its
127 specified conditions are met.
129 Events may be enabled and disabled at will, either when LTTng tracers
130 are active or not. Events may be enabled before a user space application