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