| 1 | --- |
| 2 | id: event |
| 3 | --- |
| 4 | |
| 5 | An _event_, in LTTng's realm, is a term often used metonymically, |
| 6 | having multiple definitions depending on the context: |
| 7 | |
| 8 | 1. When tracing, an event is a _point in space-time_. Space, in a |
| 9 | tracing context, is the set of all executable positions of a |
| 10 | compiled application by a logical processor. When a program is |
| 11 | executed by a processor and some instrumentation point, or |
| 12 | _probe_, is encountered, an event occurs. This event is accompanied |
| 13 | by some contextual payload (values of specific variables at this |
| 14 | point of execution) which may or may not be recorded. |
| 15 | 2. In the context of a recorded trace file, the term _event_ implies |
| 16 | a _recorded event_. |
| 17 | 3. When configuring a tracing session, _enabled events_ refer to |
| 18 | specific rules which could lead to the transfer of actual |
| 19 | occurring events (1) to recorded events (2). |
| 20 | |
| 21 | The whole [Core concepts](#doc-core-concepts) section focusses on the |
| 22 | third definition. An event is always registered to _one or more_ |
| 23 | channels and may be enabled or disabled at will per channel. A disabled |
| 24 | event will never lead to a recorded event, even if its channel |
| 25 | is enabled. |
| 26 | |
| 27 | An event (3) is enabled with a few conditions that must _all_ be met |
| 28 | when an event (1) happens in order to generate a recorded event (2): |
| 29 | |
| 30 | 1. A _probe_ or group of probes in the traced application must be |
| 31 | executed. |
| 32 | 2. **Optionally**, the probe must have a log level matching a |
| 33 | log level range specified when enabling the event. |
| 34 | 3. **Optionally**, the occurring event must satisfy a custom |
| 35 | expression, or _filter_, specified when enabling the event. |
| 36 | |
| 37 | The following illustration summarizes how tracing sessions, domains, |
| 38 | channels and events are related: |
| 39 | |
| 40 | <div class="img img-90"> |
| 41 | <object data="/images/docs/core-concepts.svg" type="image/svg+xml"> |
| 42 | <img src="/images/docs/core-concepts.svg"> |
| 43 | </object> |
| 44 | </div> |
| 45 | |
| 46 | This diagram also shows how events may be individually enabled/disabled |
| 47 | (green/grey) and how a given event may be registered to more than one |
| 48 | channel. |