lttng-add-context.1 - Online Linux Manual Page

LTTNG−ADD−CONTEXT - Online Linux Manual PageSection : 1
Updated : 5 Februrary 2018
Source : LTTng 2.12.2
Note : LTTng Manual

NAMElttng-add-context − Add context fields to an LTTng channel

SYNOPSISAdd 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

DESCRIPTIONThe 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:TYPEwith: PROVIDER Provider name. TYPE Context type name. .it 1 an-trap
¶Note ¶.br 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.

OPTIONSGeneral options are described in lttng(1).

DomainOne 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.

LIMITATIONSAs 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 VARIABLESLTTNG_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)). .it 1 an-trap
¶Note ¶.br $LTTNG_HOME defaults to $HOME when not explicitly set.

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

BUGSIf 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

COPYRIGHTSThis program is part of the LTTng−tools project. LTTng−tools is distributed under the GNU General Public License version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>. See the LICENSE <https://github.com/lttng/lttng-tools/blob/master/LICENSE> file for details.

THANKSSpecial thanks to Michel Dagenais and the DORSAL laboratory <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montré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.