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

   1 lttng-add-trigger(1)
   2 ====================
   3 :revdate: 3 May 2021
   4
   5
   6 NAME
   7 ----
   8 lttng-add-trigger - Add an LTTng trigger
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-uid='UID']
  15       option:--condition='CONDTYPE' ['CONDARGS']
  16       option:--action='ACTTYPE' ['ACTARGS'] [option:--action='ACTTYPE' ['ACTARGS']]...
  17
  18 DESCRIPTION
  19 -----------
  20 The `lttng add-trigger` command creates and adds an LTTng _trigger_ to
  21 the connected session daemon (see man:lttng-sessiond(8)).
  22
  23 See man:lttng-concepts(7) to learn more about LTTng triggers.
  24
  25 By default, the `add-trigger` command automatically assigns a name,
  26 unique for a given session daemon and Unix user, to the added trigger.
  27 Assign a custom name with the option:--name.
  28
  29 The `add-trigger` command adds a trigger for your Unix user. If your
  30 Unix user is `root`, you may add the trigger as another user with the
  31 option:--owner-uid option.
  32
  33 Specify the condition of the trigger to add with a <<cond-spec,condition
  34 specifier>> and its actions with one or more <<action-spec,action
  35 specifiers>>. The order of the action specifiers is significant: LTTng
  36 attempts to execute the actions of a firing trigger in this order.
  37
  38 List the triggers of your Unix user, or of all users if your
  39 Unix user is `root`, with the man:lttng-list-triggers(1) command.
  40
  41 Remove a trigger with the man:lttng-remove-trigger(1) command.
  42
  43
  44 [[cond-spec]]
  45 Condition specifier
  46 ~~~~~~~~~~~~~~~~~~~
  47 Synopsis:
  48
  49 [verse]
  50 option:--condition='CONDTYPE' ['CONDARGS']
  51
  52 A condition specifier is the option:--condition option, which specifies
  53 the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE',
  54 with zero or more arguments 'CONDARGS'.
  55
  56 The available condition types are:
  57
  58 [[er-matches-cond-spec]]`event-rule-matches`::
  59     Synopsis:
  60 +
  61 [verse]
  62 option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
  63 {nbsp}
  64 +
  65 An `event-rule-matches` condition is considered satisfied when the event
  66 rule specified with 'ERSPEC' matches an event.
  67 +
  68 See man:lttng-event-rule(7) to learn how to specify an event rule
  69 ('ERSPEC' part).
  70 +
  71 Capture event record and context fields with one or more
  72 nloption:--capture options (see the <<capture-descr,Capture descriptor>>
  73 section below to learn more). When an `event-rule-matches` condition
  74 with capture descriptors is satisfied, the captured field values are
  75 available in the evaluation object of the condition using the
  76 liblttng-ctl C{nbsp}API.
  77 +
  78 IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the
  79 `add-trigger` command from a shell, as capture descriptors can include
  80 characters having a special meaning for most shells.
  81
  82
  83 [[capture-descr]]
  84 Capture descriptor
  85 ~~~~~~~~~~~~~~~~~~
  86 A capture descriptor is a textual expression which describes how to read
  87 an event record or context field.
  88
  89 The argument of a nloption:--capture option, when using an
  90 <<er-matches-cond-spec,``event rule matches'' condition specifier>>
  91 (`event-rule-matches`), is a capture descriptor.
  92
  93 A capture descriptor expression is one of:
  94
  95 'NAME'::
  96     An event record field named 'NAME'.
  97 +
  98 The supported event record field types are:
  99 +
 100 --
 101 * Integer
 102 * Enumeration (integral value)
 103 * Floating point number
 104 * Static array of integers
 105 * Dynamic array (``sequence'') of integers
 106 * Text string
 107 --
 108 +
 109 Examples: `my_field`, `target_cpu`, `ip`.
 110
 111 ++$ctx.++__NAME__::
 112     A statically-known context field named 'NAME'.
 113 +
 114 List the available statically-known context field names with
 115 man:lttng-add-context(1).
 116 +
 117 Examples: `$ctx.prio`, `$ctx.preemptible`,
 118 `$ctx.perf:cpu:stalled-cycles-frontend`.
 119
 120 ++$app.++__PROVIDER__++.++__NAME__::
 121     An application-specific context field named 'NAME' from the
 122     provider 'PROVIDER'.
 123 +
 124 See man:lttng-add-context(1) to learn more about application-specific
 125 context fields.
 126 +
 127 Example: `$app.server:cur_user`.
 128
 129 __EXPR__++[++__INDEX__++]++::
 130     The element at index 'INDEX' of the array field (static or dynamic)
 131     identified by the expression 'EXPR'.
 132 +
 133 'INDEX' must be a constant, positive integral value.
 134 +
 135 Examples: `ip[3]`, `user_ids[15]`.
 136
 137 If, when an event rule matches, a given capture descriptor doesn't
 138 identify an existing event or context field, then the captured value is
 139 reported as being unavailable. This applies to:
 140
 141 * A nonexistent event record field name.
 142 * A nonexistent statically-known context field name.
 143 * A nonexistent application-specific context field name.
 144 * An out-of-bounds array field index.
 145
 146
 147 [[action-spec]]
 148 Action specifier
 149 ~~~~~~~~~~~~~~~~
 150 Synopsis:
 151
 152 [verse]
 153 option:--action='ACTTYPE' ['ACTARGS']
 154
 155 An action specifier is the option:--action option, which specifies
 156 the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero
 157 or more arguments 'ACTARGS'.
 158
 159 The available action types are:
 160
 161 Notify::
 162     Synopsis:
 163 +
 164 [verse]
 165 option:--action=**notify** [nloption:--rate-policy='POLICY']
 166 {nbsp}
 167 +
 168 Sends a notification through the notification
 169 mechanism of the session daemon (see man:lttng-session(8)).
 170 +
 171 The session daemon sends details about the condition evaluation along
 172 with the notification.
 173 +
 174 As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program
 175 to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers).
 176 +
 177 See below for the nloption:--rate-policy option.
 178
 179 Start a tracing session::
 180     Synopsis:
 181 +
 182 [verse]
 183 option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
 184 {nbsp}
 185 +
 186 Starts the tracing session named 'SESSION' like man:lttng-start(1)
 187 would.
 188 +
 189 If no tracing session has the name 'SESSION' when LTTng is ready to
 190 execute the action, LTTng does nothing.
 191 +
 192 See below for the nloption:--rate-policy option.
 193
 194 Stop a tracing session::
 195     Synopsis:
 196 +
 197 [verse]
 198 option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
 199 {nbsp}
 200 +
 201 Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
 202 +
 203 If no tracing session has the name 'SESSION' when LTTng is ready to
 204 execute the action, LTTng does nothing.
 205 +
 206 See below for the nloption:--rate-policy option.
 207
 208 Rotate a tracing session::
 209     Synopsis:
 210 +
 211 [verse]
 212 option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
 213 {nbsp}
 214 +
 215 Archives the current trace chunk of the tracing session named 'SESSION'
 216 like man:lttng-rotate(1) would.
 217 +
 218 If no tracing session has the name 'SESSION' when LTTng is ready to
 219 execute the action, LTTng does nothing.
 220 +
 221 See below for the nloption:--rate-policy option.
 222
 223 Take a tracing session snapshot::
 224     Synopsis:
 225 +
 226 [verse]
 227 option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
 228 {nbsp}
 229 +
 230 Takes a snapshot of the tracing session named 'SESSION' like
 231 man:lttng-snapshot(1) would.
 232 +
 233 When the condition of the trigger is satisfied, the tracing session
 234 named 'SESSION', if any, must be a snapshot-mode tracing session
 235 (see man:lttng-create(1)).
 236 +
 237 If no tracing session has the name 'SESSION' when LTTng is ready to
 238 execute the action, LTTng does nothing.
 239 +
 240 See below for the nloption:--rate-policy option.
 241
 242 Common action options (as of LTTng{nbsp}{lttng_version}):
 243
 244 nloption:--rate-policy='POLICY'::
 245     Set the rate policy of the action to 'POLICY' instead of
 246     `every:1` (always execute).
 247 +
 248 A trigger which ``fires'' (its condition is satisfied) leads to an
 249 execution request for each of its actions, in order. An execution
 250 request of a given action{nbsp}__A__ first increments the execution
 251 request count{nbsp}__C__ of{nbsp}__A__. An execution request can then
 252 become an actual execution when{nbsp}__C__ satisfies the rate policy
 253 of{nbsp}__A__.
 254 +
 255 'POLICY' is one of:
 256 +
 257 --
 258 ++once-after:++__COUNT__::
 259     Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'.
 260 +
 261 In other words, execute{nbsp}__A__ a single time after 'COUNT' execution
 262 requests.
 263
 264 ++every:++__COUNT__::
 265     Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'.
 266 +
 267 In other words, execute{nbsp}__A__ every 'COUNT' execution requests.
 268 --
 269 +
 270 'COUNT' must be an integer greater than{nbsp}0.
 271 +
 272 As of LTTng{nbsp}{lttng_version}, you can use this option with any
 273 action type, but new action types in the future may not support it.
 274
 275
 276 OPTIONS
 277 -------
 278 Identification
 279 ~~~~~~~~~~~~~~
 280 option:--name='NAME'::
 281     Set the unique name of the trigger to add to 'NAME' instead of the
 282     `add-trigger` command automatically assigning one.
 283
 284 option:--owner-uid='UID'::
 285     Add the trigger as the Unix user having the user ID 'UID'.
 286 +
 287 You may only use this option if your Unix user is `root`.
 288
 289
 290 Specifier
 291 ~~~~~~~~~
 292 option:--condition='CONDTYPE'::
 293     Introductory option for a condition specifier of type 'CONDTYPE'.
 294 +
 295 See the <<cond-spec,Condition specifier>> section above to learn more.
 296
 297 option:--action='ACTTYPE'::
 298     Introductory option for an action specifier of type 'ACTTYPE'.
 299 +
 300 See the <<action-spec,Action specifier>> section above to learn more.
 301
 302
 303 include::common-cmd-help-options.txt[]
 304
 305
 306 include::common-cmd-footer.txt[]
 307
 308
 309 SEE ALSO
 310 --------
 311 man:lttng(1),
 312 man:lttng-list-triggers(1),
 313 man:lttng-remove-trigger(1),
 314 man:lttng-concepts(7)