--- name: "lttng-add-context" section: "1" platform: "linux" package: "lttng-tools" version: "2.13.15-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/lttng-add-context" --- # lttng-add-context(1) Add context fields to be recorded by LTTng ## 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 channels: ``` lttng [GENERAL OPTIONS] add-context (--kernel | --userspace | --jul | --log4j) [--session=SESSION] [--channel=CHANNEL] --type=TYPE [--type=TYPE]... ``` List the available context field types: ``` lttng [GENERAL OPTIONS] add-context --list ``` ## DESCRIPTION The **lttng add-context** command can: Without the **--list** option Add one or more context fields to be recorded by LTTng to the event records of: With the **--session**=*SESSION* option The recording session named *SESSION*. Without the **--session** option The current recording session (see [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn more about the current recording session). With the **--channel**=*CHANNEL* The channel named *CHANNEL*. Without the **--channel** option **All** the channels of the selected recording session. With the **--list** option List the available context field types. See [**lttng-concepts**(7)](/lttng-concepts/7.md) to learn more about recording sessions and channels. Repeat the **--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 named. • A perf counter name: Per-CPU Prefix: **perf:cpu:** Only available with the **--kernel** option. Per-thread Prefix: **perf:thread:** Only available with the **--userspace**, **--jul**, or **--log4j** option. Add Performance Monitoring Unit (PMU) counter context fields by raw ID with the **perf:cpu:raw:r***N***:***NAME* (**--kernel** option) or **perf:thread:raw:r***N***:***NAME* (**--userspace**, **--jul**, or **--log4j** option) types, with: *N* A hexadecimal event descriptor which follows the [**perf-record**(1)](/perf-record/1.md) 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: ``` $app.PROVIDER:TYPE ``` \+ *PROVIDER*:: Provider name. *TYPE* Context type name. Only available with the **--jul** and **--log4j** 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 2.13.15, you may NOT add context fields to be recorded to the event records of a given channel once its recording session has been started (see [**lttng-start**(1)](/lttng-start/1.md)) at least once. See the “EXAMPLES” section below for usage examples. ## OPTIONS See [**lttng**(1)](/lttng/1.md) for *GENERAL OPTIONS*. ### Tracing domain One of: - **-j**, **--jul** Add context fields to be recorded to the event records of one or more channels of the **java.util.logging** (JUL) tracing domain. - **-k**, **--kernel** Add context fields to be recorded to the event records of one or more channels of the Linux kernel tracing domain. - **-l**, **--log4j** Add context fields to be recorded to the event records of one or more channels of the Apache log4j tracing domain. - **-u**, **--userspace** Add context fields to be recorded to the event records of one or more channels of the user space tracing domain. ### Recording target - **-c** *CHANNEL*, **--channel**=*CHANNEL* Add context fields to be recorded to the event records of a channel named *CHANNEL* instead of all the channels of the selected recording session. - **-s** *SESSION*, **--session**=*SESSION* Add context fields to be recorded to the event records of one or more channels of the recording session named *SESSION* instead of the current recording session. ### Context field type - **--list** List the available context field types. You may NOT use this option with the **--channel**, **--session**, or **--type** options. - **-t** *TYPE*, **--type**=*TYPE* Add a context field having the type *TYPE* to be recorded. Repeat this option to add more than one context field. ### Program information - **-h**, **--help** Show help. This option attempts to launch **/usr/bin/man** to view this manual page. Override the manual pager path with the **LTTNG\_MAN\_BIN\_PATH** environment variable. - **--list-options** List available command options and quit. ## EXIT STATUS **0** Success **1** Command error **2** Undefined command **3** Fatal error **4** Command warning (something went wrong during the command) ## ENVIRONMENT **LTTNG\_ABORT\_ON\_ERROR** Set to **1** to abort the process after the first error is encountered. **LTTNG\_HOME** Path to the LTTng home directory. Defaults to **$HOME**. Useful when the Unix user running the commands has a non-writable home directory. **LTTNG\_MAN\_BIN\_PATH** Absolute path to the manual pager to use to read the LTTng command-line help (with [**lttng-help**(1)](/lttng-help/1.md) or with the **--help** option) instead of **/usr/bin/man**. **LTTNG\_SESSION\_CONFIG\_XSD\_PATH** Path to the directory containing the **session.xsd** recording session configuration XML schema. **LTTNG\_SESSIOND\_PATH** Absolute path to the LTTng session daemon binary (see [**lttng-sessiond**(8)](/lttng-sessiond/8.md)) to spawn from the [**lttng-create**(1)](/lttng-create/1.md) command. The **--sessiond-path** general option overrides this environment variable. ## FILES **$LTTNG\_HOME/.lttngrc** Unix user’s LTTng runtime configuration. This is where LTTng stores the name of the Unix user’s current recording session between executions of [**lttng**(1)](/lttng/1.md). [**lttng-create**(1)](/lttng-create/1.md) and [**lttng-set-session**(1)](/lttng-set-session/1.md) set the current recording session. **$LTTNG\_HOME/lttng-traces** Default output directory of LTTng traces in local and snapshot modes. Override this path with the **--output** option of the [**lttng-create**(1)](/lttng-create/1.md) command. **$LTTNG\_HOME/.lttng** Unix user’s LTTng runtime and configuration directory. **$LTTNG\_HOME/.lttng/sessions** Default directory containing the Unix user’s saved recording session configurations (see [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)). **/etc/lttng/sessions** Directory containing the system-wide saved recording session configurations (see [**lttng-save**(1)](/lttng-save/1.md) and [**lttng-load**(1)](/lttng-load/1.md)). **Note**\ **$LTTNG\_HOME** defaults to the value of the **HOME** environment variable. ## EXAMPLES **Example 1. List the available context field types.** See the **--list** option. ``` $ lttng add-context --list ``` **Example 2. Add a single statically-known context field to be recorded to all the Linux kernel channels of the current recording session.** ``` $ lttng add-context --kernel --type=pid ``` **Example 3. Add three statically-known context fields to be recorded to a specific user space channel of a specific recording session.** See the **--session** and **--channel** options. ``` $ lttng add-context --userspace --session=my-session \ --channel=my-channel \ --type=vpid --type=procname --type=ip ``` **Example 4. Add a perf counter context field to be recorded to a specific Linux kernel channel of the current recording session.** See the **--channel** option. ``` $ lttng add-context --kernel --channel=my-channel \ --type=perf:cpu:cache-misses ``` **Example 5. Add an LTTng application-specific context field to be recorded to all the JUL channels of the current recording session.** ``` $ lttng add-context --jul --type='$app.my_server:user_cnt' ``` ## RESOURCES • LTTng project website \ • LTTng documentation \ • LTTng bug tracker \ • Git repositories \ • GitHub organization \ • Continuous integration \ • Mailing list \ for support and development: **lttng-dev@lists.lttng.org** • IRC channel \: **#lttng** on **irc.oftc.net** ## COPYRIGHT This program is part of the LTTng-tools project. LTTng-tools is distributed under the GNU General Public License version 2 \. See the **LICENSE** \ file for details. ## THANKS Special thanks to Michel Dagenais and the DORSAL laboratory \ at École Polytechnique de Montréal for the LTTng journey. Also thanks to the Ericsson teams working on tracing which helped us greatly with detailed bug reports and unusual test cases. ## SEE ALSO [**lttng**(1)](/lttng/1.md), [**lttng-enable-channel**(1)](/lttng-enable-channel/1.md), [**lttng-concepts**(7)](/lttng-concepts/7.md)