contents/understanding-lttng/core-concepts/event.md

   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 focuses 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 never leads to a recorded event, even if its channel is enabled.
  25
  26 An event (3) is enabled with a few conditions that must _all_ be met
  27 when an event (1) happens in order to generate a recorded event (2):
  28
  29   1. A _probe_ or group of probes in the traced application must be
  30      executed.
  31   2. **Optionally**, the probe must have a log level matching a
  32      log level range specified when enabling the event.
  33   3. **Optionally**, the occurring event must satisfy a custom
  34      expression, or _filter_, specified when enabling the event.
  35
  36 The following illustration summarizes how tracing sessions, domains,
  37 channels and events are related:
  38
  39 <div class="img img-90">
  40 <object data="/images/docs26/core-concepts.svg" type="image/svg+xml">
  41   <img src="/images/docs26/core-concepts.svg">
  42 </object>
  43 </div>
  44
  45 This diagram also shows how events may be individually enabled/disabled
  46 (green/grey) and how a given event may be registered to more than one
  47 channel.