Ubuntu Manpage: lttng-add-context - Add context fields to an LTTng channel

Provided by: lttng-tools_2.11.2-1build1_amd64

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

       /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

COPYRIGHTS

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

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.