// SPDX-FileCopyrightText: 2015-2025 Philippe Proulx <pproulx@efficios.com>
//
// SPDX-License-Identifier: CC-BY-SA-4.0

lttng-add-context(1)
====================
:revdate: 20 March 2026


NAME
----
lttng-add-context - Add context fields to be recorded by LTTng


SYNOPSIS
--------
Add context fields to be recorded to the event records of one or more
event record channels:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context*
      (option:--kernel | option:--userspace | option:--jul | option:--log4j | option:--log4j2)
      [option:--session='SESSION'] [option:--channel='CHANNEL']
      option:--type='TYPE' [option:--type='TYPE']...

List the available context field types:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list


DESCRIPTION
-----------
The `lttng add-context` command can:

Without the option:--list option::
    Add one or more context fields to be recorded by LTTng to the event
    records of:
+
With the option:--session='SESSION' option:::
    The recording session named 'SESSION'.

Without the option:--session option:::
    The current recording session (see man:lttng-concepts(7) to learn
    more about the current recording session).

With the option:--channel='CHANNEL':::
    The event record channel named 'CHANNEL'.

Without the option:--channel option:::
    *All* the event record channels of the selected recording session.

With the option:--list option::
    List the available context field types.

See man:lttng-concepts(7) to learn more about recording sessions and
event record channels.

Repeat the option:--type='TYPE' option to add more than one context
field to be recorded. 'TYPE' is one of:

* A statically-known, or built-in context field name.

* A perf counter name:
+
--
Per-CPU::
    Prefix: `perf:cpu:`
+
Only available with the option:--kernel option.

Per-thread::
    Prefix: `perf:thread:`
+
Only available with the option:--userspace, option:--jul,
option:--log4j, or option:--log4j2 option.
--
+
Add Performance Monitoring Unit (PMU) counter context fields by raw ID
with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option)
or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace,
option:--jul, option:--log4j, or option:--log4j2 option) types, with:
+
--
'N'::
    A hexadecimal event descriptor which follows the man:perf-record(1)
    format: a concatenation of the event number and umask value which
    the manufacturer of the processor provides.
+
The possible values for this part are processor-specific.

'NAME'::
    Custom name to identify the counter.
--

* An LTTng application-specific context field name:
+
--
[verse]
$app.'PROVIDER':__TYPE__
+
'PROVIDER'::
    Provider name.

'TYPE'::
    Context type name.
--
+
Only available with the option:--jul, option:--log4j,
and option:--log4j2 options.

IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the
`add-context` command from a shell, as `$` is a special character for
variable substitution in most shells.

NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context fields
to be recorded to the event records of a given event record channel once
its recording session has been started (see man:lttng-start(1)) at least
once.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.


include::common-lttng-cmd-options-head.txt[]


Tracing domain
~~~~~~~~~~~~~~
One of:

option:-j, option:--jul::
    Add context fields to be recorded to the event records of one or
    more event record channels of the `java.util.logging` (JUL) tracing domain.

option:-k, option:--kernel::
    Add context fields to be recorded to the event records of one or
    more event record channels of the Linux kernel tracing domain.

option:-l, option:--log4j::
    Add context fields to be recorded to the event records of one or
    more event record channels of the Apache log4j{nbsp}1.x tracing domain.

option:--log4j2::
    Add context fields to be recorded to the event records of one or
    more event record channels of the Apache Log4j{nbsp}2 tracing domain.

option:-u, option:--userspace::
    Add context fields to be recorded to the event records of one or
    more event record channels of the user space tracing domain.


Recording target
~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
    Add context fields to be recorded to the event records of an event
    record channel named 'CHANNEL' instead of all the event record
    channels of the selected recording session.

option:-s 'SESSION', option:--session='SESSION'::
    Add context fields to be recorded to the event records of one or
    more event record channels of the recording session named 'SESSION'
    instead of the current recording session.


Context field type
~~~~~~~~~~~~~~~~~~
option:--list::
    List the available context field types.
+
You may :not: use this option with the option:--channel,
option:--session, or option:--type options.

option:-t 'TYPE', option:--type='TYPE'::
    Add a context field having the type 'TYPE' to be recorded.
+
Repeat this option to add more than one context field.


include::common-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


[[examples]]
EXAMPLES
--------
.List the available context field types.
====
See the option:--list option.

[role="term"]
----
$ lttng add-context --list
----
====

.Add a single statically-known context field to be recorded to all the Linux kernel event record channels of the current recording session.
====
[role="term"]
----
$ lttng add-context --kernel --type=pid
----
====

.Add three statically-known context fields to be recorded to a specific user space event record channel of a specific recording session.
====
See the option:--session and option:--channel options.

[role="term"]
----
$ lttng add-context --userspace --session=my-session \
                    --channel=my-channel \
                    --type=vpid --type=procname --type=ip
----
====

.Add a perf counter context field to be recorded to a specific Linux kernel event record channel of the current recording session.
====
See the option:--channel option.

[role="term"]
----
$ lttng add-context --kernel --channel=my-channel \
                    --type=perf:cpu:cache-misses
----
====

.Add an LTTng application-specific context field to be recorded to all the JUL event record channels of the current recording session.
====
[role="term"]
----
$ lttng add-context --jul --type='$app.my_server:user_cnt'
----
====


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-enable-channel(1),
man:lttng-concepts(7)
