Update some manual pages for LTTng-tools 2.13

[lttng-tools.git] / doc / man / lttng-add-context.1.txt

lttng-add-context(1)
====================
:revdate: 8 April 2021


NAME
----
lttng-add-context - Add context fields to be recorded by LTTng


SYNOPSIS
--------
Add context fields to be recorded to the LTTng event records of
one or more channels:

[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 field types:

[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* option:--list


DESCRIPTION
-----------
The `lttng add-context` command adds one or more context fields to be
recorded to the event records of a given channel, or of all the channels
of a selected tracing session, by LTTng.

See man:lttng-enable-channel(1) to learn more about LTTng channels.

When you use the `add-context` command to add context fields for a given
channel, all the event records which LTTng writes to a sub-buffer of
that channel contain the dynamic values of those context fields.

Without the option:--session option, the `add-context` command selects
the current tracing session (see man:lttng-create(1) and
man:lttng-set-session(1) to learn more about the current tracing
session).

Without the option:--channel option, LTTng adds context fields to be
recorded to the event records of *all* the channels of the selected
tracing session.

Repeat the option:--type option to add more than one context field to be
recorded.

perf counter context fields are available:

Per-CPU::
    Prefix: `perf:cpu:`.
+
Only available for Linux kernel (option:--kernel option) channels.

Per-thread::
    Prefix: `perf:thread:`.
+
Only available for user application/library (option:--userspace,
option:--jul, and option:--log4j options) channels.

Add PMU counter context fields by raw ID with the
++perf:cpu:raw:r++__N__++:++__NAME__ (Linux kernel tracing domain) or
++perf:thread:raw:r++__N__++:++__NAME__ (user space tracing domain)
types, with:

'N'::
    A hexadecimal event descriptor which follows the man: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 field are processor-specific.

'NAME'::
    Custom name to easily recognize the counter.

Add an application-specific context field with the following syntax:

[verse]
$app.'PROVIDER':__TYPE__

'PROVIDER'::
    Provider name.

'TYPE'::
    Context type name.

NOTE: Make sure to **single-quote** the argument of the option:--type
option when you run the `add-context` command from a shell, as `$` is a
special character for variable substitution in most shells.

List the available context field types with the option:--list option and
without other arguments.

NOTE: As of LTTng{nbsp}{lttng_version}, you may :not: add context
fields to be recorded to the event records of a given channel once its
tracing session has been started (see man:lttng-start(1)) at least once.


include::common-cmd-options-head.txt[]


Tracing domain
~~~~~~~~~~~~~~
One of:

option:-j, option:--jul::
    Add context fields to be recorded to the event records of one or
    more channels of the `java.util.logging` (JUL) tracing domain.

option:-k, option:--kernel::
    Add context fields to be recorded to the event records of one or
    more channels of the Linux kernel tracing domain.

option:-l, option:--log4j::
    Add context fields to be recorded to the event records of one or
    more channels of the Apache log4j tracing domain.

option:-u, option:--userspace::
    Add context fields to be recorded to the event records of one or
    more channels of the user space tracing domain.


Recording target
~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--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
    tracing session.

option:-s 'SESSION', option:--session='SESSION'::
    Add context fields to be recorded to the event records of one or
    more channels of the tracing session named 'SESSION' instead of the
    current tracing session.


Context field type
~~~~~~~~~~~~~~~~~~
option:--list::
    List the available context field types.
+
You may :not: use this option with the option:--channel,
option:--session, or option:--type options.

option:-t 'TYPE', option:--type='TYPE'::
    Add a context field having the type 'TYPE' to be recorded.
+
Repeat this option to add more than one context field.


include::common-cmd-help-options.txt[]


include::common-cmd-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-enable-channel(1),
man:lttng-set-session(1)