lttng-add-context(1) ==================== :revdate: 5 Februrary 2018 NAME ---- lttng-add-context - Add context fields to an LTTng channel SYNOPSIS -------- Add context fields to a channel: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* (option:--kernel | option:--userspace | option:--jul | option:--log4j) [option:--session='SESSION'] [option:--channel='CHANNEL'] option:--type='TYPE' [option:--type='TYPE']... List the available context fields: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list DESCRIPTION ----------- The `lttng add-context` command adds one or more context fields to a channel. Channels are created with the man: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 option:--session option is omitted, the current tracing session is used. If the option:--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 option:--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 man: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: [verse] $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 option:--list option without other arguments to list the available context field names. See the <> section below for a list of limitations to consider. include::common-cmd-options-head.txt[] Domain ~~~~~~ One of: option:-j, option:--jul:: Add context to channel in the `java.util.logging` (JUL) domain. option:-k, option:--kernel:: Add context to channel in the Linux kernel domain. option:-l, option:--log4j:: Add context to channel in the Apache log4j domain. option:-u, option:--userspace:: Add context to channel in the user space domain. Target ~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: Add context fields to a channel named 'CHANNEL' instead of adding them to all the channels. option:-s 'SESSION', option:--session='SESSION':: Add context fields to a channel in the tracing session named 'SESSION' instead of the current tracing session. Context ~~~~~~~ option:--list:: List the available context fields. Use this option alone. option:-t 'TYPE', option:--type='TYPE':: Add context field named 'TYPE'. This option can be repeated as many times as needed on the command-line. include::common-cmd-help-options.txt[] [[limitations]] 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 man:lttng-start(1)) at least once. include::common-cmd-footer.txt[] SEE ALSO -------- man:lttng(1)