| 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: |
| 25 | * CPU cycles, stalled cycles, idle cycles, etc. |
| 26 | * cache misses |
| 27 | * branch instructions, misses, loads, etc. |
| 28 | * CPU faults |
| 29 | * etc. |
| 30 | |
| 31 | The full list is available in the output of `lttng add-context --help`. |
| 32 | Some of them are reserved for a specific domain (kernel or |
| 33 | user space) while others are available for both. |
| 34 | |
| 35 | To add context information to one or all channels of a given tracing |
| 36 | session, use the `add-context` command: |
| 37 | |
| 38 | <pre class="term"> |
| 39 | lttng add-context --userspace --type vpid --type perf:thread:cpu-cycles |
| 40 | </pre> |
| 41 | |
| 42 | The above example adds the virtual process identifier and per-thread |
| 43 | CPU cycles count values to all recorded user space domain events of the |
| 44 | current tracing session. Use the `--channel` option to select a specific |
| 45 | channel: |
| 46 | |
| 47 | <pre class="term"> |
| 48 | lttng add-context --kernel --channel my-channel --type tid |
| 49 | </pre> |
| 50 | |
| 51 | adds the thread identifier value to all recorded kernel domain events |
| 52 | in the channel `my-channel` of the current tracing session. |
| 53 | |
| 54 | Beware that context information cannot be removed from channels once |
| 55 | it's added for a given tracing session. |