Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: enabling-disabling-events | |
3 | --- | |
4 | ||
5 | Inside a tracing session, individual events may be enabled or disabled | |
6 | so that tracing them may or may not generate trace data. | |
7 | ||
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 | |
13 | composed of: | |
14 | ||
f11aa623 | 15 | 1. A **domain** (kernel, user space, `java.util.logging`, or log4j) |
c23b8cb1 | 16 | (required). |
5e0cbfb0 PP |
17 | 2. One or many **instrumentation points** in source code or binary |
18 | program (tracepoint name, address, symbol name, function name, | |
9f13d176 PP |
19 | logger name, amongst other types of probes) to be executed |
20 | (required). | |
5e0cbfb0 PP |
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 | |
23 | space domain). | |
24 | 4. A **custom user expression**, or **filter**, that must evaluate to | |
9f13d176 | 25 | _true_ when a tracepoint is executed (optional). |
5e0cbfb0 PP |
26 | |
27 | All conditions are specified using arguments passed to the | |
28 | `enable-event` command of the `lttng` tool. | |
29 | ||
c23b8cb1 PP |
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. | |
5e0cbfb0 PP |
34 | |
35 | Condition 2 is specified using one of: | |
36 | ||
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 | |
43 | domain) | |
44 | ||
45 | When none of the above is specified, `enable-event` defaults to | |
46 | using `--tracepoint`. | |
47 | ||
48 | Condition 3 is specified using one of: | |
49 | ||
50 | * `--loglevel`: log level range from 0 to a specific log level | |
51 | * `--loglevel-only`: specific log level | |
52 | ||
53 | See `lttng enable-event --help` for the complete list of log level | |
54 | names. | |
55 | ||
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 | |
61 | all usage details. | |
62 | ||
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_. | |
68 | ||
69 | Here are a few examples (you must | |
70 | [create a tracing session](#doc-creating-destroying-tracing-sessions) | |
71 | first): | |
72 | ||
73 | <pre class="term"> | |
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 | |
9f13d176 PP |
83 | lttng enable-event -k --tracepoint irq_handler_entry \ |
84 | --filter 'irq == 28 || irq == 17' | |
5e0cbfb0 PP |
85 | </pre> |
86 | ||
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. | |
91 | ||
c23b8cb1 PP |
92 | System call events can be enabled individually, too: |
93 | ||
9f13d176 PP |
94 | <pre class="term" style="position: relative"> |
95 | <div class="since">Since 2.6</div>lttng enable-event -k --syscall open | |
c23b8cb1 PP |
96 | lttng enable-event -k --syscall read |
97 | lttng enable-event -k --syscall fork,chdir,pipe | |
98 | </pre> | |
99 | ||
100 | The complete list of available system call events can be | |
101 | obtained using | |
102 | ||
103 | <pre class="term"> | |
104 | lttng list --kernel --syscall | |
105 | </pre> | |
106 | ||
5e0cbfb0 PP |
107 | You can see a list of events (enabled or disabled) using |
108 | ||
109 | <pre class="term"> | |
110 | lttng list some-session | |
111 | </pre> | |
112 | ||
113 | where `some-session` is the name of the desired tracing session. | |
114 | ||
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: | |
118 | ||
119 | <pre class="term"> | |
120 | lttng enable-event -u --tracepoint my_app:hello_you | |
121 | lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG | |
122 | </pre> | |
123 | ||
124 | The second command, matching a log level range, is useless since the first | |
125 | command enables all tracepoints matching the same name, | |
126 | `my_app:hello_you`. | |
127 | ||
128 | Disabling an event is simpler: you only need to provide the event | |
129 | name to the `disable-event` command: | |
130 | ||
131 | <pre class="term"> | |
b80ba306 | 132 | lttng disable-event --userspace my_app:hello_you |
5e0cbfb0 PP |
133 | </pre> |
134 | ||
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. | |
139 | ||
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. | |
143 | ||
47bfcb75 | 144 | A disabled event doesn't generate any trace data, even if all its |
5e0cbfb0 PP |
145 | specified conditions are met. |
146 | ||
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 | |
149 | is even started. |