doc/man: use double quotes when referring to internal section

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

lttng-add-context(1)
====================
:revdate: 6 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.
--
+
Only available with the option:--jul and option:--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{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.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.


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[]


[[examples]]
EXAMPLES
--------
.List the available context field types.
====
See the option:--list option.

[role="term"]
----
$ lttng add-context --list
----
====

.Add a single statically-known context field to be recorded to all the Linux kernel channels of the current tracing session.
====
[role="term"]
----
$ lttng add-context --kernel --type=pid
----
====

.Add three statically-known context fields to be recorded to a specific user space channel of a specific tracing session.
====
See the option:--session and option:--channel options.

[role="term"]
----
$ lttng add-context --userspace --session=my-session \
                    --channel=my-channel \
                    --type=vpid --type=procname --type=ip
----
====

.Add a perf counter context field to be recorded to a specific Linux kernel channel of the current tracing session.
====
See the option:--channel option.

[role="term"]
----
$ lttng add-context --kernel --channel=my-channel \
                    --type=perf:cpu:cache-misses
----
====

.Add an LTTng application-specific context field to be recorded to all the JUL channels of the current tracing session.
====
[role="term"]
----
$ lttng add-context --jul --type='$app.my_server:user_cnt'
----
====


include::common-footer.txt[]


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