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 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.