.gitignore: add register-some-triggers trigger test utility

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

diff --git a/doc/man/lttng-add-trigger.1.txt b/doc/man/lttng-add-trigger.1.txt
index 17c8bd7065dfc141524809ec10bab865a41305dd..581dd1313932e90b2b2f89d481310f62c93d710a 100644 (file)
--- a/doc/man/lttng-add-trigger.1.txt
+++ b/doc/man/lttng-add-trigger.1.txt
@@ -1,6 +1,6 @@
 lttng-add-trigger(1)
 =====================
 lttng-add-trigger(1)
 =====================

-:revdate: 17 January 2020
+:revdate: 27 May 2020

 
 
 NAME
 
 
 NAME


@@ -13,7 +13,6 @@ SYNOPSIS
 
 [verse]
 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
 
 [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]...
       --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.
 
 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.
 
 The syntax by which conditions and actions are specified is described
 below.
 

+[[conditions]]

 Conditions
 ~~~~~~~~~~
 
 Conditions
 ~~~~~~~~~~
 


@@ -46,15 +42,21 @@ specific condition.  There must be exactly one condition given in the
 
 The available conditions are:
 
 
 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
     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.
 
     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
 ~~~~~~~
 
 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.
 
     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
 -------
 
 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.
 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.