lttng-add-context(1): use a description list to explain `--channel`

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

lttng-add-context(1)
====================
:revdate: 3 May 2021


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:

[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 can:

Without the option:--list option::
    Add one or more context fields to be recorded by LTTng to the event
    records of:
+
With the option:--session='SESSION' option:::
    The tracing session named 'SESSION'.

Without the option:--session option:::
    The current tracing session (see man:lttng-concepts(7) to learn more
    about the current tracing session).

With the option:--channel='CHANNEL':::
    The channel named 'CHANNEL'.

Without the option:--channel option:::
    *All* the channels of the selected tracing session.

With the option:--list option::
    List the available context field types.

See man:lttng-concepts(7) to learn more about tracing sessions and
channels.

Repeat the option:--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 option:--kernel option.

Per-thread::
    Prefix: `perf:thread:`
+
Only available with the option:--userspace, option:--jul, or
option:--log4j option.
--
+
Add Performance Monitoring Unit (PMU) counter context fields by raw ID
with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option)
or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace,
option:--jul, or option:--log4j option) 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 part are processor-specific.

'NAME'::
    Custom name to identify the counter.
--

* An LTTng application-specific context field name:
+
[verse]
$app.'PROVIDER':__TYPE__
+
'PROVIDER'::
    Provider name.

'TYPE'::
    Context type name.

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{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-lttng-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-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-enable-channel(1),
man:lttng-concepts(7)