doc/man/lttng-add-trigger.1.txt

   1 lttng-add-trigger(1)
   2 =====================
   3 :revdate: 27 May 2020
   4
   5
   6 NAME
   7 ----
   8 lttng-add-trigger - Create LTTng triggers
   9
  10
  11 SYNOPSIS
  12 --------
  13
  14 [verse]
  15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
  16       --condition CONDITION-NAME CONDITION-ARGS
  17       --action ACTION-NAME ACTION-ARGS
  18       [--action ACTION-NAME ACTION-ARGS]...
  19
  20
  21 DESCRIPTION
  22 -----------
  23
  24 The `lttng add-trigger` command is used to create triggers.  A
  25 trigger is an association between a *condition* and one or more
  26 *actions*.  When the condition associated to a trigger is met, the
  27 actions associated to that trigger are executed.  The tracing does not
  28 have to be active for the conditions to be met, and triggers are
  29 independent from tracing sessions.
  30
  31 The syntax by which conditions and actions are specified is described
  32 below.
  33
  34 [[conditions]]
  35 Conditions
  36 ~~~~~~~~~~
  37
  38 Conditions are specified with the `--condition` option, followed by a
  39 condition name, and possibly some more arguments, depending on the
  40 specific condition.  There must be exactly one condition given in the
  41 `lttng add-trigger` invocation.
  42
  43 The available conditions are:
  44
  45 Event rule: `on-event [event rule arguments]`::
  46     This type of condition is met when the tracer encounters an event
  47     matching the given even rule.  The arguments describing the event
  48     rule are the same as those describing the event rules of the
  49     man:lttng-enable-event(1) command, with these exceptions:
  50
  51     - It is not possible to use filter operands that use values from
  52       the context.
  53
  54 +
  55 Fields to capture can be specified with the option:--capture option, followed by
  56 a capture expression. Zero or more captures can be configured. See the
  57 <<capture-expr, Capture expression>> section below for more information.
  58
  59 [[actions]]
  60 Actions
  61 ~~~~~~~
  62
  63 Actions are specified with the `--action` option, followed by an action
  64 name, and possibly some more arguments, depending on the specific
  65 action.  There must be at least one action given in the
  66 `lttng add-trigger` invocation.
  67
  68 The available actions are:
  69
  70 Notify: *notify*::
  71     This action causes the LTTng session daemon to send a notification,
  72     through its notification mechanism (see man:lttng-sessiond(8)).
  73     Some details about the condition evaluation are sent along with the
  74     notification.
  75
  76 Start session: *start-session* session-name::
  77     This action causes the LTTng session daemon to start tracing for the
  78     session with the given name.  If no session with the given name exist
  79     at the time the condition is met, nothing is done.
  80
  81 Stop session: *stop-session* session-name::
  82     This action causes the LTTng session daemon to stop tracing for the
  83     session with the given name.  If no session with the given name exist
  84     at the time the condition is met, nothing is done.
  85
  86 Rotate session: *rotate-session* session-name::
  87     This action causes the LTTng session daemon to rotate the session
  88     with the given name.  See  man:lttng-rotate(1) for more information
  89     about the session rotation concept.  If no session with the given
  90     name exist at the time the condition is met, nothing is done.
  91
  92 Snapshot session: *snapshot-session* session-name::
  93     This action causes the LTTng session daemon to take a snapshot of the
  94     session with the given name.  See man:lttng-snapshot(1) for more
  95     information about the session snapshot concept.  If no session with
  96     the given name exist at the time the condition is met, nothing is
  97     done.
  98
  99
 100 [[capture-expr]]
 101 Capture expression
 102 ~~~~~~~~~~~~~~~~~~
 103
 104 A capture expression can be specified with the option:--capture option when
 105 creating a new on-event condition. If the capture expression corresponds with an
 106 event's field when tracing, the runtime dynamic value corresponding to the
 107 capture expression is captured.
 108
 109 NOTE: Make sure to **single-quote** the capture expression when running
 110 the command from a shell, as capture expressions typically include
 111 characters having a special meaning for most shells.
 112
 113 * Supported field types:
 114  - integer,
 115  - unsigned integer,
 116  - floating point value,
 117  - fixed-size array of integers,
 118  - variable-size array of integers (sequence),
 119  - enumeration,
 120  - text string,
 121  - element of any allowing previous type.
 122
 123 * The dynamic value of an event field is captured by using its name as a C
 124   identifier.
 125 +
 126 The square bracket notation is available, like in the C
 127 language, to access array/sequence field.
 128 Only a constant, positive integer number can be used within square
 129 brackets. If the index is out of bounds, the capture expression
 130 evaluates to `unavailable`.
 131 +
 132 An enumeration field's value is an integer.
 133 +
 134 When the capture's field does not exist, the capture expression
 135 evaluates to `unavailable`.
 136 +
 137 Examples: `my_field`, `target_cpu`, `seq[7]`
 138
 139 * The dynamic value of a statically-known context field is captured by
 140   prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of
 141   available contexts.
 142 +
 143 When the expression's statically-known context field does not exist,
 144 the capture expression evaluates to `unavailable`.
 145 +
 146 Examples: `$ctx.prio`, `$ctx.preemptible`,
 147 `$ctx.perf:cpu:stalled-cycles-frontend`.
 148 +
 149 NOTE: The statically-known context field does NOT need to be added using the
 150 man:lttng-add-context(1) command. The statically-known context fields are
 151 always available in the context of triggers.
 152
 153 * The dynamic value of an application-specific context field is captured by
 154   prefixing its name with `$app.` (follows the format used to add such a context
 155   field with the man:lttng-add-context(1) command).
 156 +
 157 When the expression's application-specific context field does not exist,
 158 the capture expression evaluates to `unavailable`.
 159 +
 160 Example: `$app.server:cur_user`.
 161 +
 162 NOTE: The application-specific context field does NOT need to be added using the
 163 man:lttng-add-context(1) command. The application-specific context fields fields
 164 are always available in the context of triggers.
 165
 166
 167 OPTIONS
 168 -------
 169
 170 option:--condition::
 171     Define the condition for the trigger.  See the
 172     <<conditions,CONDITIONS>> section for more details.
 173
 174 option:--action::
 175     Define an action for the trigger.  See the <<actions,ACTIONS>>
 176     section for more details.
 177
 178 option:--id='ID'::
 179     Set the id of the trigger to 'ID'.  If omitted, an id will
 180     automatically be assigned to the trigger by the session daemon.
 181 +
 182 If a trigger with the specified 'ID' already exists, the trigger
 183 creation will fail.
 184
 185 option:--fire-every 'N'::
 186     Execute the trigger's actions every 'N' times the condition is met.
 187
 188 option:--fire-once-after 'N'::
 189     Execute the trigger's actions once after 'N' times the condition is
 190     met, then never after that.
 191
 192 include::common-cmd-help-options.txt[]
 193
 194
 195 include::common-cmd-footer.txt[]
 196
 197
 198 SEE ALSO
 199 --------
 200 man:lttng-list-triggers(1),
 201 man:lttng-remove-trigger(1),
 202 man:lttng(1)