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