X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-add-trigger.1.txt;h=581dd1313932e90b2b2f89d481310f62c93d710a;hb=50ad08620ff49e3c27e6eb3fea5151e744ae13ec;hp=17c8bd7065dfc141524809ec10bab865a41305dd;hpb=a942557f174ba5a1b71ae5334ee987643eca691c;p=lttng-tools.git

diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt
index 17c8bd706..581dd1313 100644
--- a/doc/man/lttng-add-trigger.1.txt
+++ b/doc/man/lttng-add-trigger.1.txt
@@ -1,6 +1,6 @@
 lttng-add-trigger(1)
 =====================
-:revdate: 17 January 2020
+:revdate: 27 May 2020
 
 
 NAME
@@ -13,7 +13,6 @@ SYNOPSIS
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
-      [--fire-every N] [--fire-once-after N]
       --condition CONDITION-NAME CONDITION-ARGS
       --action ACTION-NAME ACTION-ARGS
       [--action ACTION-NAME ACTION-ARGS]...
@@ -29,13 +28,10 @@ actions associated to that trigger are executed.  The tracing does not
 have to be active for the conditions to be met, and triggers are
 independent from tracing sessions.
 
-By default, a trigger fires every time its condition is met.  The
-'--fire-every' and '--fire-once-after' options can be used to change
-this mode.
-
 The syntax by which conditions and actions are specified is described
 below.
 
+[[conditions]]
 Conditions
 ~~~~~~~~~~
 
@@ -46,15 +42,21 @@ specific condition.  There must be exactly one condition given in the
 
 The available conditions are:
 
-Event rule: `on-event [event rule arguments]`::
+Event rule: `event-rule-matches [event rule arguments]`::
     This type of condition is met when the tracer encounters an event
-    matching the given even rule.  The arguments describing the event
+    matching the given event rule.  The arguments describing the event
     rule are the same as those describing the event rules of the
     man:lttng-enable-event(1) command, with these exceptions:
 
     - It is not possible to use filter operands that use values from
       the context.
 
++
+Fields to capture can be specified with the option:--capture option, followed by
+a capture expression. Zero or more captures can be configured. See the
+<<capture-expr, Capture expression>> section below for more information.
+
+[[actions]]
 Actions
 ~~~~~~~
 
@@ -94,9 +96,85 @@ Snapshot session: *snapshot-session* session-name::
     the given name exist at the time the condition is met, nothing is
     done.
 
+
+[[capture-expr]]
+Capture expression
+~~~~~~~~~~~~~~~~~~
+
+A capture expression can be specified with the option:--capture option when
+creating a new event-rule-matches condition. If the capture expression
+corresponds with an event's field when tracing, the runtime dynamic value
+corresponding to the capture expression is captured.
+
+NOTE: Make sure to **single-quote** the capture expression when running
+the command from a shell, as capture expressions typically include
+characters having a special meaning for most shells.
+
+* Supported field types:
+ - integer,
+ - unsigned integer,
+ - floating point value,
+ - fixed-size array of integers,
+ - variable-size array of integers (sequence),
+ - enumeration,
+ - text string,
+ - element of any allowing previous type.
+
+* The dynamic value of an event field is captured by using its name as a C
+  identifier.
++
+The square bracket notation is available, like in the C
+language, to access array/sequence field.
+Only a constant, positive integer number can be used within square
+brackets. If the index is out of bounds, the capture expression
+evaluates to `unavailable`.
++
+An enumeration field's value is an integer.
++
+When the capture's field does not exist, the capture expression
+evaluates to `unavailable`.
++
+Examples: `my_field`, `target_cpu`, `seq[7]`
+
+* The dynamic value of a statically-known context field is captured by
+  prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of
+  available contexts.
++
+When the expression's statically-known context field does not exist,
+the capture expression evaluates to `unavailable`.
++
+Examples: `$ctx.prio`, `$ctx.preemptible`,
+`$ctx.perf:cpu:stalled-cycles-frontend`.
++
+NOTE: The statically-known context field does NOT need to be added using the
+man:lttng-add-context(1) command. The statically-known context fields are
+always available in the context of triggers.
+
+* The dynamic value of an application-specific context field is captured by
+  prefixing its name with `$app.` (follows the format used to add such a context
+  field with the man:lttng-add-context(1) command).
++
+When the expression's application-specific context field does not exist,
+the capture expression evaluates to `unavailable`.
++
+Example: `$app.server:cur_user`.
++
+NOTE: The application-specific context field does NOT need to be added using the
+man:lttng-add-context(1) command. The application-specific context fields fields
+are always available in the context of triggers.
+
+
 OPTIONS
 -------
 
+option:--condition::
+    Define the condition for the trigger.  See the
+    <<conditions,CONDITIONS>> section for more details.
+
+option:--action::
+    Define an action for the trigger.  See the <<actions,ACTIONS>>
+    section for more details.
+
 option:--id='ID'::
     Set the id of the trigger to 'ID'.  If omitted, an id will
     automatically be assigned to the trigger by the session daemon.