# lttng-add-context

## NAME



           lttng-add-context - Add context fields to an LTTng channel
    


## SYNOPSIS



           Add context fields to a channel:
    
           **lttng**[_GENERAL OPTIONS_] **add-context**
                 (**--kernel** | **--userspace** | **--jul** | **--log4j**)
                 [**--session** =_SESSION_] [**--channel** =_CHANNEL_]
                 **--type** =_TYPE_ [**--type** =_TYPE_]...
    
           List the available context fields:
    
           **lttng**[_GENERAL OPTIONS_] **add-context --list**
    


## DESCRIPTION



           The **lttng add-context** command adds one or more context fields to a
           channel.
    
           Channels are created with the lttng-enable-channel(1) command.
    
           When context fields are added to a channel, all the events emitted
           within this channel contain the dynamic values of those context
           fields.
    
           If the **--session** option is omitted, the current tracing session is
           used. If the **--channel** option is omitted, the context fields are
           added to all the selected tracing session’s channels.
    
           Many context fields can be added to a channel at once by repeating
           the **--type** option.
    
           perf counters are available as per-CPU (**perf:cpu:** prefix) as well
           as per-thread (**perf:thread:** prefix) counters. Currently, per-CPU
           counters can only be used in the Linux kernel tracing domain,
           while per-thread counters can only be used in the user space
           tracing domain.
    
           It is also possible to enable PMU counters by raw ID using the
           **perf:cpu:raw:rN:NAME**(Linux kernel tracing domain) or
           **perf:thread:raw:rN:NAME**(user space tracing domain), with:
    
           **N**
               A hexadecimal event descriptor which is the same format as
               used by perf-record(1): a concatenation of the event number
               and umask value provided by the processor’s manufacturer. The
               possible values for this field are processor-specific.
    
           **NAME**
               Custom name to easily recognize the counter.
    
           Application-specific context fields can be added to a channel
           using the following syntax:
    
               $app._PROVIDER_ :_TYPE_
    
           with:
    
           _PROVIDER_
               Provider name.
    
           _TYPE_
               Context type name.
    
               **Note**
    
               Make sure to **single-quote** the type when running the command
               from a shell, as **$** is a special character for variable
               substitution in most shells.
    
           Use the **--list** option without other arguments to list the
           available context field names.
    
           See the _LIMITATIONS_ section below for a list of limitations to
           consider.
    


## OPTIONS



           General options are described in lttng(1).
    
       **Domain**
           One of:
    
           **-j** , **--jul**
               Add context to channel in the **java.util.logging**(JUL) domain.
    
           **-k** , **--kernel**
               Add context to channel in the Linux kernel domain.
    
           **-l** , **--log4j**
               Add context to channel in the Apache log4j domain.
    
           **-u** , **--userspace**
               Add context to channel in the user space domain.
    
       **Target**
           **-c** _CHANNEL_ , **--channel** =_CHANNEL_
               Add context fields to a channel named _CHANNEL_ instead of
               adding them to all the channels.
    
           **-s** _SESSION_ , **--session** =_SESSION_
               Add context fields to a channel in the tracing session named
               _SESSION_ instead of the current tracing session.
    
       **Context**
           **--list**
               List the available context fields. Use this option alone.
    
           **-t** _TYPE_ , **--type** =_TYPE_
               Add context field named _TYPE_. This option can be repeated as
               many times as needed on the command-line.
    
       **Program information**
           **-h** , **--help**
               Show command help.
    
               This option, like lttng-help(1), attempts to launch
               **/usr/bin/man** to view the command’s man page. The path to the
               man pager can be overridden by the **LTTNG_MAN_BIN_PATH**
               environment variable.
    
           **--list-options**
               List available command options.
    


## LIMITATIONS



           As of this version of LTTng, it is not possible to add context
           fields to a channel once its tracing session has been started (see
           lttng-start(1)) at least once.
    


## ENVIRONMENT VARIABLES



           **LTTNG_ABORT_ON_ERROR**
               Set to 1 to abort the process after the first error is
               encountered.
    
           **LTTNG_HOME**
               Overrides the **$HOME** environment variable. Useful when the user
               running the commands has a non-writable home directory.
    
           **LTTNG_MAN_BIN_PATH**
               Absolute path to the man pager to use for viewing help
               information about LTTng commands (using lttng-help(1) or **lttng**
               **COMMAND --help**).
    
           **LTTNG_SESSION_CONFIG_XSD_PATH**
               Path in which the **session.xsd** session configuration XML schema
               may be found.
    
           **LTTNG_SESSIOND_PATH**
               Full session daemon binary path.
    
               The **--sessiond-path** option has precedence over this
               environment variable.
    
           Note that the lttng-create(1) command can spawn an LTTng session
           daemon automatically if none is running. See lttng-sessiond(8) for
           the environment variables influencing the execution of the session
           daemon.
    


## FILES



           **$LTTNG_HOME/.lttngrc**
               User LTTng runtime configuration.
    
               This is where the per-user current tracing session is stored
               between executions of lttng(1). The current tracing session
               can be set with lttng-set-session(1). See lttng-create(1) for
               more information about tracing sessions.
    
           **$LTTNG_HOME/lttng-traces**
               Default output directory of LTTng traces. This can be
               overridden with the **--output** option of the lttng-create(1)
               command.
    
           **$LTTNG_HOME/.lttng**
               User LTTng runtime and configuration directory.
    
           **$LTTNG_HOME/.lttng/sessions**
               Default location of saved user tracing sessions (see
               lttng-save(1) and lttng-load(1)).
    
           **/usr/local/etc/lttng/sessions**
               System-wide location of saved tracing sessions (see
               lttng-save(1) and lttng-load(1)).
    
               **Note**
    
               **$LTTNG_HOME** defaults to **$HOME** when not explicitly set.
    


## EXIT STATUS



           **0**
               Success
    
           **1**
               Command error
    
           **2**
               Undefined command
    
           **3**
               Fatal error
    
           **4**
               Command warning (something went wrong during the command)
    


## BUGS



           If you encounter any issue or usability problem, please report it
           on the LTTng bug tracker <https://bugs.lttng.org/projects/lttng-
           tools>.
    


## RESOURCES



           •   LTTng project website <https://lttng.org>
    
           •   LTTng documentation <https://lttng.org/docs>
    
           •   Git repositories <http://git.lttng.org>
    
           •   GitHub organization <http://github.com/lttng>
    
           •   Continuous integration <http://ci.lttng.org/>
    
           •   Mailing list <http://lists.lttng.org> for support and
               development: **lttng-dev@lists.lttng.org**
    
           •   IRC channel <irc://irc.oftc.net/lttng>: **#lttng** on **irc.oftc.net**
    


## THANKS



           Special thanks to Michel Dagenais and the DORSAL laboratory
           <http://www.dorsal.polymtl.ca/> 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.
    


* * *