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 (required).
  20   3. A **log level** (each instrumentation point declares its own log
  21      level) or log level range to match (optional; only valid for user
  22      space domain).
  23   4. A **custom user expression**, or **filter**, that must evaluate to
  24      _true_ when a tracepoint is executed (optional; only valid for user
  25      space domain).
  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 </pre>
  84
  85 The wildcard symbol, `*`, matches _anything_ and may only be used at
  86 the end of the string when specifying a _tracepoint_. Make sure to
  87 use it between single quotes in your favorite shell to avoid
  88 undesired shell expansion.
  89
  90 System call events can be enabled individually, too:
  91
  92 <pre class="term">
  93 lttng enable-event -k --syscall open
  94 lttng enable-event -k --syscall read
  95 lttng enable-event -k --syscall fork,chdir,pipe
  96 </pre>
  97
  98 The complete list of available system call events can be
  99 obtained using
 100
 101 <pre class="term">
 102 lttng list --kernel --syscall
 103 </pre>
 104
 105 You can see a list of events (enabled or disabled) using
 106
 107 <pre class="term">
 108 lttng list some-session
 109 </pre>
 110
 111 where `some-session` is the name of the desired tracing session.
 112
 113 What you're actually doing when enabling events with specific conditions
 114 is creating a **whitelist** of traceable events for a given channel.
 115 Thus, the following case presents redundancy:
 116
 117 <pre class="term">
 118 lttng enable-event -u --tracepoint my_app:hello_you
 119 lttng enable-event -u --tracepoint my_app:hello_you --loglevel TRACE_DEBUG
 120 </pre>
 121
 122 The second command, matching a log level range, is useless since the first
 123 command enables all tracepoints matching the same name,
 124 `my_app:hello_you`.
 125
 126 Disabling an event is simpler: you only need to provide the event
 127 name to the `disable-event` command:
 128
 129 <pre class="term">
 130 lttng disable-event --userspace my_app:hello_you
 131 </pre>
 132
 133 This name has to match a name previously given to `enable-event` (it
 134 has to be listed in the output of `lttng list some-session`).
 135 The `*` wildcard is supported, as long as you also used it in a
 136 previous `enable-event` invocation.
 137
 138 Disabling an event does not add it to some blacklist: it simply removes
 139 it from its channel's whitelist. This is why you cannot disable an event
 140 which wasn't previously enabled.
 141
 142 A disabled event doesn't generate any trace data, even if all its
 143 specified conditions are met.
 144
 145 Events may be enabled and disabled at will, either when LTTng tracers
 146 are active or not. Events may be enabled before a user space application
 147 is even started.