lttng-add-context(1)

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) 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) 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:rN:NAME (--kernel option) or perf:thread:raw:rN:NAME (--userspace, --jul, or --log4j option) types, with:

N

A hexadecimal event descriptor which follows the perf-record(1) 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)) at least once.

See the “EXAMPLES” section below for usage examples.

OPTIONS

See lttng(1) 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) 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)) to spawn from the lttng-create(1) 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-create(1) and lttng-set-session(1) 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) 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) and lttng-load(1)).

/etc/lttng/sessions

Directory containing the system-wide saved recording session configurations (see lttng-save(1) and lttng-load(1)).

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 <https://lttng.org>

• LTTng documentation <https://lttng.org/docs>

• LTTng bug tracker <https://bugs.lttng.org>

• Git repositories <https://git.lttng.org>

• GitHub organization <https://github.com/lttng>

• Continuous integration <https://ci.lttng.org/>

• Mailing list <https://lists.lttng.org/> for support and development: [email protected]

• IRC channel <irc://irc.oftc.net/lttng>: #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 <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.