| 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, `java.util.logging`, or log4j) |
| 16 | (required). |
| 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 |
| 22 | space domain). |
| 23 | 4. A **custom user expression**, or **filter**, that must evaluate to |
| 24 | _true_ when a tracepoint is executed (optional; only valid for user |
| 25 | space domain). |
| 26 | |
| 27 | All conditions are specified using arguments passed to the |
| 28 | `enable-event` command of the `lttng` tool. |
| 29 | |
| 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. |
| 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 |
| 83 | </pre> |
| 84 | |
| 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. |
| 89 | |
| 90 | System call events can be enabled individually, too: |
| 91 | |
| 92 | <pre class="term"> |
| 93 | lttng enable-event -k --syscall open |
| 94 | lttng enable-event -k --syscall read |
| 95 | lttng enable-event -k --syscall fork,chdir,pipe |
| 96 | </pre> |
| 97 | |
| 98 | The complete list of available system call events can be |
| 99 | obtained using |
| 100 | |
| 101 | <pre class="term"> |
| 102 | lttng list --kernel --syscall |
| 103 | </pre> |
| 104 | |
| 105 | You can see a list of events (enabled or disabled) using |
| 106 | |
| 107 | <pre class="term"> |
| 108 | lttng list some-session |
| 109 | </pre> |
| 110 | |
| 111 | where `some-session` is the name of the desired tracing session. |
| 112 | |
| 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: |
| 116 | |
| 117 | <pre class="term"> |
| 118 | lttng enable-event -u --tracepoint my_app:hello_you |
| 119 | lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG |
| 120 | </pre> |
| 121 | |
| 122 | The second command, matching a log level range, is useless since the first |
| 123 | command enables all tracepoints matching the same name, |
| 124 | `my_app:hello_you`. |
| 125 | |
| 126 | Disabling an event is simpler: you only need to provide the event |
| 127 | name to the `disable-event` command: |
| 128 | |
| 129 | <pre class="term"> |
| 130 | lttng disable-event --userspace my_app:hello_you |
| 131 | </pre> |
| 132 | |
| 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. |
| 137 | |
| 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. |
| 141 | |
| 142 | A disabled event doesn't generate any trace data, even if all its |
| 143 | specified conditions are met. |
| 144 | |
| 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 |
| 147 | is even started. |