Rename "tracing session" -> "recording session"

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

diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt
index ad83445b5c97ca45af5239271ead76742fff0d06..49f0a7b039e09edce86da308f362b5658091c959 100644 (file)
--- a/doc/man/lttng-add-context.1.txt
+++ b/doc/man/lttng-add-context.1.txt
@@ -1,6 +1,6 @@
 lttng-add-context(1)
 ====================
-:revdate: 3 May 2021
+:revdate: 14 June 2021
 
 
 NAME
@@ -31,25 +31,27 @@ 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 a given channel, or of all the channels of:
+    records of:
 +
 With the option:--session='SESSION' option:::
-    The tracing session named 'SESSION'.
+    The recording 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).
+    The current recording session (see man:lttng-concepts(7) to learn
+    more about the current recording session).
+
+With the option:--channel='CHANNEL':::
+    The channel named 'CHANNEL'.
+
+Without the option:--channel option:::
+    *All* the channels of the selected recording session.
 
 With the option:--list option::
     List the available context field types.
 
-See man:lttng-concepts(7) to learn more about tracing sessions and
+See man:lttng-concepts(7) to learn more about recording sessions and
 channels.
 
-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='TYPE' option to add more than one context
 field to be recorded. 'TYPE' is one of:
 
@@ -89,6 +91,7 @@ The possible values for this part are processor-specific.
 
 * An LTTng application-specific context field name:
 +
+--
 [verse]
 $app.'PROVIDER':__TYPE__
 +
@@ -97,14 +100,20 @@ $app.'PROVIDER':__TYPE__
 
 '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.
+to be recorded to the event records of a given channel once its
+recording 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[]
@@ -136,12 +145,12 @@ 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.
+    recording 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.
+    more channels of the recording session named 'SESSION' instead of
+    the current recording session.
 
 
 Context field type
@@ -164,6 +173,59 @@ 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 recording 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 recording 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 recording 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 recording session.
+====
+[role="term"]
+----
+$ lttng add-context --jul --type='$app.my_server:user_cnt'
+----
+====
+
+
 include::common-footer.txt[]