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 | ||
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 | |
21 | space domain). | |
22 | 4. A **custom user expression**, or **filter**, that must evaluate to | |
23 | _true_ when a tracepoint is executed (optional; only valid for user | |
24 | space domain). | |
25 | ||
26 | All conditions are specified using arguments passed to the | |
27 | `enable-event` command of the `lttng` tool. | |
28 | ||
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. | |
33 | ||
34 | Condition 2 is specified using one of: | |
35 | ||
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 | |
42 | domain) | |
43 | ||
44 | When none of the above is specified, `enable-event` defaults to | |
45 | using `--tracepoint`. | |
46 | ||
47 | Condition 3 is specified using one of: | |
48 | ||
49 | * `--loglevel`: log level range from 0 to a specific log level | |
50 | * `--loglevel-only`: specific log level | |
51 | ||
52 | See `lttng enable-event --help` for the complete list of log level | |
53 | names. | |
54 | ||
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 | |
60 | all usage details. | |
61 | ||
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_. | |
67 | ||
68 | Here are a few examples (you must | |
69 | [create a tracing session](#doc-creating-destroying-tracing-sessions) | |
70 | first): | |
71 | ||
72 | <pre class="term"> | |
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 | |
82 | </pre> | |
83 | ||
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. | |
88 | ||
89 | You can see a list of events (enabled or disabled) using | |
90 | ||
91 | <pre class="term"> | |
92 | lttng list some-session | |
93 | </pre> | |
94 | ||
95 | where `some-session` is the name of the desired tracing session. | |
96 | ||
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: | |
100 | ||
101 | <pre class="term"> | |
102 | lttng enable-event -u --tracepoint my_app:hello_you | |
103 | lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG | |
104 | </pre> | |
105 | ||
106 | The second command, matching a log level range, is useless since the first | |
107 | command enables all tracepoints matching the same name, | |
108 | `my_app:hello_you`. | |
109 | ||
110 | Disabling an event is simpler: you only need to provide the event | |
111 | name to the `disable-event` command: | |
112 | ||
113 | <pre class="term"> | |
b80ba306 | 114 | lttng disable-event --userspace my_app:hello_you |
5e0cbfb0 PP |
115 | </pre> |
116 | ||
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. | |
121 | ||
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. | |
125 | ||
126 | A disabled event will not generate any trace data, even if all its | |
127 | specified conditions are met. | |
128 | ||
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 | |
131 | is even started. |