contents/using-lttng/controlling-tracing/adding-context.md

   1 ---
   2 id: adding-context
   3 ---
   4
   5 If you read all the sections of
   6 [Controlling tracing](#doc-controlling-tracing) so far, you should be
   7 able to create tracing sessions, create and enable channels and events
   8 within them and start/stop the LTTng tracers. Event fields recorded in
   9 trace files provide important information about occurring events, but
  10 sometimes external context may help you solve a problem faster. This
  11 section discusses how to add context information to events of a
  12 specific channel using the `lttng` tool.
  13
  14 There are various available context values which can accompany events
  15 recorded by LTTng, for example:
  16
  17   * **process information**:
  18     * identifier (PID)
  19     * name
  20     * priority
  21     * scheduling priority (niceness)
  22     * thread identifier (TID)
  23   * the **hostname** of the system on which the event occurred
  24   * plenty of **performance counters** using perf, for example:
  25     * CPU cycles, stalled cycles, idle cycles, and the other cycle types
  26     * cache misses
  27     * branch instructions, misses, loads
  28     * CPU faults
  29
  30 The full list is available in the output of `lttng add-context --help`.
  31 Some of them are reserved for a specific domain (kernel or
  32 user space) while others are available for both.
  33
  34 To add context information to one or all channels of a given tracing
  35 session, use the `add-context` command:
  36
  37 <pre class="term">
  38 lttng add-context --userspace --type vpid --type perf:thread:cpu-cycles
  39 </pre>
  40
  41 The above example adds the virtual process identifier and per-thread
  42 CPU cycles count values to all recorded user space domain events of the
  43 current tracing session. Use the `--channel` option to select a specific
  44 channel:
  45
  46 <pre class="term">
  47 lttng add-context --kernel --channel my-channel --type tid
  48 </pre>
  49
  50 adds the thread identifier value to all recorded kernel domain events
  51 in the channel `my-channel` of the current tracing session.
  52
  53 Beware that context information cannot be removed from channels once
  54 it's added for a given tracing session.