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

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