Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
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 | ||
0c9c0c96 | 21 | The whole [Core concepts](#doc-core-concepts) section focuses on the |
5e0cbfb0 PP |
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. |