contents/using-lttng/controlling-tracing/enabling-disabling-events.md

   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 or Java Util Logging) (required).
  16   2. One or many **instrumentation points** in source code or binary
  17      program (tracepoint name, address, symbol name, function name,
  18      logger name, etc.) to be executed (required).
  19   3. A **log level** (each instrumentation point declares its own log
  20      level) or log level range to match (optional; only valid for user
  21      space domain).
  22   4. A **custom user expression**, or **filter**, that must evaluate to
  23      _true_ when a tracepoint is executed (optional; only valid for user
  24      space domain).
  25
  26 All conditions are specified using arguments passed to the
  27 `enable-event` command of the `lttng` tool.
  28
  29 Condition 1 is specified using either `--kernel/-k` (kernel),
  30 `--userspace/-u` (user space) or `--jul/-j`
  31 (<abbr title="Java Util Logging">JUL</abbr>). Exactly one of those
  32 three arguments must be specified.
  33
  34 Condition 2 is specified using one of:
  35
  36   * `--tracepoint`: **tracepoint**
  37   * `--probe`: **dynamic probe** (address, symbol name  or combination
  38     of both in binary program; only valid for kernel domain)
  39   * `--function`: **function entry/exit** (address, symbol name or
  40     combination of both in binary program; only valid for kernel domain)
  41   * `--syscall`: **system call entry/exit** (only valid for kernel
  42     domain)
  43
  44 When none of the above is specified, `enable-event` defaults to
  45 using `--tracepoint`.
  46
  47 Condition 3 is specified using one of:
  48
  49   * `--loglevel`: log level range from 0 to a specific log level
  50   * `--loglevel-only`: specific log level
  51
  52 See `lttng enable-event --help` for the complete list of log level
  53 names.
  54
  55 Condition 4 is specified using the `--filter` option. This filter is
  56 a C-like expression, potentially reading real-time values of event
  57 fields, that has to evaluate to _true_ for the condition to be satisfied.
  58 Event fields are read using plain identifiers while context fields
  59 must be prefixed with `$ctx.`. See `lttng enable-event --help` for
  60 all usage details.
  61
  62 The aforementioned arguments are combined to create and enable events.
  63 Each unique combination of arguments leads to a different
  64 _enabled event_. The log level and filter arguments are optional, their
  65 default values being respectively all log levels and a filter which
  66 always returns _true_.
  67
  68 Here are a few examples (you must
  69 [create a tracing session](#doc-creating-destroying-tracing-sessions)
  70 first):
  71
  72 <pre class="term">
  73 lttng enable-event -u --tracepoint my_app:hello_world
  74 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_WARNING
  75 lttng enable-event -u --tracepoint 'my_other_app:*'
  76 lttng enable-event -u --tracepoint my_app:foo_bar \
  77                    --filter 'some_field <= 23 && !other_field'
  78 lttng enable-event -k --tracepoint sched_switch
  79 lttng enable-event -k --tracepoint gpio_value
  80 lttng enable-event -k --function usb_probe_device usb_probe_device
  81 lttng enable-event -k --syscall --all
  82 </pre>
  83
  84 The wildcard symbol, `*`, matches _anything_ and may only be used at
  85 the end of the string when specifying a _tracepoint_. Make sure to
  86 use it between single quotes in your favorite shell to avoid
  87 undesired shell expansion.
  88
  89 You can see a list of events (enabled or disabled) using
  90
  91 <pre class="term">
  92 lttng list some-session
  93 </pre>
  94
  95 where `some-session` is the name of the desired tracing session.
  96
  97 What you're actually doing when enabling events with specific conditions
  98 is creating a **whitelist** of traceable events for a given channel.
  99 Thus, the following case presents redundancy:
 100
 101 <pre class="term">
 102 lttng enable-event -u --tracepoint my_app:hello_you
 103 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG
 104 </pre>
 105
 106 The second command, matching a log level range, is useless since the first
 107 command enables all tracepoints matching the same name,
 108 `my_app:hello_you`.
 109
 110 Disabling an event is simpler: you only need to provide the event
 111 name to the `disable-event` command:
 112
 113 <pre class="term">
 114 lttng disable-event -u my_app:hello_you
 115 </pre>
 116
 117 This name has to match a name previously given to `enable-event` (it
 118 has to be listed in the output of `lttng list some-session`).
 119 The `*` wildcard is supported, as long as you also used it in a
 120 previous `enable-event` invocation.
 121
 122 Disabling an event does not add it to some blacklist: it simply removes
 123 it from its channel's whitelist. This is why you cannot disable an event
 124 which wasn't previously enabled.
 125
 126 A disabled event will not generate any trace data, even if all its
 127 specified conditions are met.
 128
 129 Events may be enabled and disabled at will, either when LTTng tracers
 130 are active or not. Events may be enabled before a user space application
 131 is even started.