[lttng-docs.git] / contents / using-lttng / controlling-tracing / adding-context.md

---
id: adding-context
---

If you read all the sections of
[Controlling tracing](#doc-controlling-tracing) so far, you should be
able to create tracing sessions, create and enable channels and events
within them and start/stop the LTTng tracers. Event fields recorded in
trace files provide important information about occurring events, but
sometimes external context may help you solve a problem faster. This
section discusses how to add context information to events of a
specific channel using the `lttng` tool.

There are various available context values which can accompany events
recorded by LTTng, for example:

  * **process information**:
    * identifier (PID)
    * name
    * priority
    * scheduling priority (niceness)
    * thread identifier (TID)
  * the **hostname** of the system on which the event occurred
  * plenty of **performance counters** using perf, for example:
    * CPU cycles, stalled cycles, idle cycles, and the other cycle types
    * cache misses
    * branch instructions, misses, loads
    * CPU faults

The full list is available in the output of `lttng add-context --help`.
Some of them are reserved for a specific domain (kernel or
user space) while others are available for both.

To add context information to one or all channels of a given tracing
session, use the `add-context` command:

<pre class="term">
lttng add-context --userspace --type vpid --type perf:thread:cpu-cycles
</pre>

The above example adds the virtual process identifier and per-thread
CPU cycles count values to all recorded user space domain events of the
current tracing session. Use the `--channel` option to select a specific
channel:

<pre class="term">
lttng add-context --kernel --channel my-channel --type tid
</pre>

adds the thread identifier value to all recorded kernel domain events
in the channel `my-channel` of the current tracing session.

Beware that context information cannot be removed from channels once
it's added for a given tracing session.
Commit	Line	Data
5e0cbfb0 PP	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
ba3b1994 PP	24	* plenty of performance counters using perf, for example:
ba3b1994 PP	25	* CPU cycles, stalled cycles, idle cycles, and the other cycle types
5e0cbfb0	26	* cache misses
ba3b1994	27	* branch instructions, misses, loads
5e0cbfb0	28	* CPU faults
5e0cbfb0 PP	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.