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

   1 lttng-add-trigger(1)
   2 ====================
   3 :revdate: 18 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 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
  39
  40 List the triggers of your Unix user, or of all users if your
  41 Unix user is `root`, with the man:lttng-list-triggers(1) command.
  42
  43 Remove a trigger with the man:lttng-remove-trigger(1) command.
  44
  45
  46 [[cond-spec]]
  47 Condition specifier
  48 ~~~~~~~~~~~~~~~~~~~
  49 Synopsis:
  50
  51 [verse]
  52 option:--condition='CONDTYPE' ['CONDARGS']
  53
  54 A condition specifier is the option:--condition option, which specifies
  55 the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE',
  56 with zero or more arguments 'CONDARGS'.
  57
  58 The available condition types are:
  59
  60 [[er-matches-cond-spec]]`event-rule-matches`::
  61     Synopsis:
  62 +
  63 [verse]
  64 option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
  65 {nbsp}
  66 +
  67 An `event-rule-matches` condition is considered satisfied when the event
  68 rule specified with 'ERSPEC' matches an event.
  69 +
  70 See man:lttng-event-rule(7) to learn how to specify an event rule
  71 ('ERSPEC' part).
  72 +
  73 Capture event record and context fields with one or more
  74 nloption:--capture options (see the ``<<capture-descr,Capture
  75 descriptor>>'' section below to learn more). When an
  76 `event-rule-matches` condition with capture descriptors is satisfied,
  77 the captured field values are available in the evaluation object of the
  78 condition using the liblttng-ctl C{nbsp}API.
  79 +
  80 IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the
  81 `add-trigger` command from a shell, as capture descriptors can include
  82 characters having a special meaning for most shells.
  83
  84
  85 [[capture-descr]]
  86 Capture descriptor
  87 ~~~~~~~~~~~~~~~~~~
  88 A capture descriptor is a textual expression which describes how to read
  89 an event record or context field.
  90
  91 The argument of a nloption:--capture option, when using an
  92 <<er-matches-cond-spec,``event rule matches'' condition specifier>>
  93 (`event-rule-matches`), is a capture descriptor.
  94
  95 A capture descriptor expression is one of:
  96
  97 'NAME'::
  98     An event record field named 'NAME'.
  99 +
 100 The supported event record field types are:
 101 +
 102 --
 103 * Integer
 104 * Enumeration (integral value)
 105 * Floating point number
 106 * Static array of integers
 107 * Dynamic array (``sequence'') of integers
 108 * Text string
 109 --
 110 +
 111 Examples: `my_field`, `target_cpu`, `ip`.
 112
 113 ++$ctx.++__NAME__::
 114     A statically-known context field named 'NAME'.
 115 +
 116 List the available statically-known context field names with
 117 man:lttng-add-context(1).
 118 +
 119 Examples: `$ctx.prio`, `$ctx.preemptible`,
 120 `$ctx.perf:cpu:stalled-cycles-frontend`.
 121
 122 ++$app.++__PROVIDER__++.++__NAME__::
 123     An application-specific context field named 'NAME' from the
 124     provider 'PROVIDER'.
 125 +
 126 See man:lttng-add-context(1) to learn more about application-specific
 127 context fields.
 128 +
 129 Example: `$app.server:cur_user`.
 130
 131 __EXPR__++[++__INDEX__++]++::
 132     The element at index 'INDEX' of the array field (static or dynamic)
 133     identified by the expression 'EXPR'.
 134 +
 135 'INDEX' must be a constant, positive integral value.
 136 +
 137 Examples: `ip[3]`, `user_ids[15]`.
 138
 139 If, when an event rule matches, a given capture descriptor doesn't
 140 identify an existing event or context field, then the captured value is
 141 reported as being unavailable. This applies to:
 142
 143 * A nonexistent event record field name.
 144 * A nonexistent statically-known context field name.
 145 * A nonexistent application-specific context field name.
 146 * An out-of-bounds array field index.
 147
 148
 149 [[action-spec]]
 150 Action specifier
 151 ~~~~~~~~~~~~~~~~
 152 Synopsis:
 153
 154 [verse]
 155 option:--action='ACTTYPE' ['ACTARGS']
 156
 157 An action specifier is the option:--action option, which specifies
 158 the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero
 159 or more arguments 'ACTARGS'.
 160
 161 The available action types are:
 162
 163 Notify::
 164     Synopsis:
 165 +
 166 [verse]
 167 option:--action=**notify** [nloption:--rate-policy='POLICY']
 168 {nbsp}
 169 +
 170 Sends a notification through the notification
 171 mechanism of the session daemon (see man:lttng-session(8)).
 172 +
 173 The session daemon sends details about the condition evaluation along
 174 with the notification.
 175 +
 176 As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program
 177 to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers).
 178 +
 179 See below for the nloption:--rate-policy option.
 180
 181 Start a tracing session::
 182     Synopsis:
 183 +
 184 [verse]
 185 option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
 186 {nbsp}
 187 +
 188 Starts the tracing session named 'SESSION' like man:lttng-start(1)
 189 would.
 190 +
 191 If no tracing session has the name 'SESSION' when LTTng is ready to
 192 execute the action, LTTng does nothing.
 193 +
 194 See below for the nloption:--rate-policy option.
 195
 196 Stop a tracing session::
 197     Synopsis:
 198 +
 199 [verse]
 200 option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
 201 {nbsp}
 202 +
 203 Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
 204 +
 205 If no tracing session has the name 'SESSION' when LTTng is ready to
 206 execute the action, LTTng does nothing.
 207 +
 208 See below for the nloption:--rate-policy option.
 209
 210 Rotate a tracing session::
 211     Synopsis:
 212 +
 213 [verse]
 214 option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
 215 {nbsp}
 216 +
 217 Archives the current trace chunk of the tracing session named 'SESSION'
 218 like man:lttng-rotate(1) would.
 219 +
 220 If no tracing session has the name 'SESSION' when LTTng is ready to
 221 execute the action, LTTng does nothing.
 222 +
 223 See below for the nloption:--rate-policy option.
 224
 225 Take a tracing session snapshot::
 226     Synopsis:
 227 +
 228 [verse]
 229 option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
 230 {nbsp}
 231 +
 232 Takes a snapshot of the tracing session named 'SESSION' like
 233 man:lttng-snapshot(1) would.
 234 +
 235 When the condition of the trigger is satisfied, the tracing session
 236 named 'SESSION', if any, must be a snapshot-mode tracing session
 237 (see man:lttng-create(1)).
 238 +
 239 If no tracing session has the name 'SESSION' when LTTng is ready to
 240 execute the action, LTTng does nothing.
 241 +
 242 See below for the nloption:--rate-policy option.
 243
 244 Common action options (as of LTTng{nbsp}{lttng_version}):
 245
 246 nloption:--rate-policy='POLICY'::
 247     Set the rate policy of the action to 'POLICY' instead of
 248     `every:1` (always execute).
 249 +
 250 A trigger which ``fires'' (its condition is satisfied) leads to an
 251 execution request for each of its actions, in order. An execution
 252 request of a given action{nbsp}__A__ first increments the execution
 253 request count{nbsp}__C__ of{nbsp}__A__. An execution request can then
 254 become an actual execution when{nbsp}__C__ satisfies the rate policy
 255 of{nbsp}__A__.
 256 +
 257 'POLICY' is one of:
 258 +
 259 --
 260 ++once-after:++__COUNT__::
 261     Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'.
 262 +
 263 In other words, execute{nbsp}__A__ a single time after 'COUNT' execution
 264 requests.
 265
 266 ++every:++__COUNT__::
 267     Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'.
 268 +
 269 In other words, execute{nbsp}__A__ every 'COUNT' execution requests.
 270 --
 271 +
 272 'COUNT' must be an integer greater than{nbsp}0.
 273 +
 274 As of LTTng{nbsp}{lttng_version}, you can use this option with any
 275 action type, but new action types in the future may not support it.
 276
 277
 278 OPTIONS
 279 -------
 280 Identification
 281 ~~~~~~~~~~~~~~
 282 option:--name='NAME'::
 283     Set the unique name of the trigger to add to 'NAME' instead of the
 284     `add-trigger` command automatically assigning one.
 285
 286 option:--owner-uid='UID'::
 287     Add the trigger as the Unix user having the user ID 'UID'.
 288 +
 289 You may only use this option if your Unix user is `root`.
 290
 291
 292 Specifier
 293 ~~~~~~~~~
 294 option:--condition='CONDTYPE'::
 295     Introductory option for a condition specifier of type 'CONDTYPE'.
 296 +
 297 See the ``<<cond-spec,Condition specifier>>'' section above to learn
 298 more.
 299
 300 option:--action='ACTTYPE'::
 301     Introductory option for an action specifier of type 'ACTTYPE'.
 302 +
 303 See the ``<<action-spec,Action specifier>>'' section above to learn
 304 more.
 305
 306
 307 include::common-lttng-cmd-help-options.txt[]
 308
 309
 310 include::common-lttng-cmd-after-options.txt[]
 311
 312
 313 [[examples]]
 314 EXAMPLES
 315 --------
 316 .Add an ``event rule matches'' trigger of which the action is to send a notification.
 317 ====
 318 The `event-rule-matches` trigger condition below specifies an event rule
 319 which matches any Linux system call entry event with a name starting
 320 with `exec`.
 321
 322 [role="term"]
 323 ----
 324 $ lttng add-trigger --condition=event-rule-matches \
 325                     --type=syscall:entry \
 326                     --name='exec*' --action=notify
 327 ----
 328 ====
 329
 330 .Add an ``event rule matches'' trigger of which the action is to stop a tracing session and then rotate it.
 331 ====
 332 The `event-rule-matches` trigger condition below specifies an event rule
 333 which matches any user space tracepoint event with a name starting with
 334 `my_app:` and with a log level at least as severe as a warning.
 335
 336 The order of the option:--action options below is significant.
 337
 338 [role="term"]
 339 ----
 340 $ lttng add-trigger --condition=event-rule-matches \
 341                     --type=user --name='my_app:*' \
 342                     --log-level=TRACE_WARNING.. \
 343                     --action=stop-session my-session \
 344                     --action=rotate-session my-session
 345 ----
 346
 347 See man:lttng-concepts(7) to learn more about tracing sessions and
 348 rotations.
 349 ====
 350
 351 .Add an ``event rule matches'' trigger with a specific name.
 352 ====
 353 The `event-rule-matches` trigger condition below specifies an event rule
 354 which matches events which LTTng creates from the `my-logger` Python
 355 logger.
 356
 357 The added trigger is named `my-trigger`, a unique name for your Unix
 358 user.
 359
 360 See the option:--name option.
 361
 362 [role="term"]
 363 ----
 364 $ lttng add-trigger --name=my-trigger \
 365                     --condition=event-rule-matches \
 366                     --type=python --name=my-logger \
 367                     --action=snapshot-session my-session
 368 ----
 369 ====
 370
 371 .Add an ``event rule matches'' trigger as another Unix user.
 372 ====
 373 The command line below adds a trigger as the `mireille` Unix user.
 374
 375 Your Unix user must be `root` to use the option:--owner-uid option.
 376
 377 The condition of the trigger specifies an event rule which matches LTTng
 378 kernel tracepoint events with a name which starts with `sched`.
 379
 380 [role="term"]
 381 ----
 382 # lttng add-trigger --owner-uid=$(id --user mireille) \
 383                     --condition=event-rule-matches \
 384                     --type=kernel --name='sched*' \
 385                     --action=notify
 386 ----
 387 ====
 388
 389 .Add an ``event rule matches'' trigger with a notification action to be executed every 10{nbsp}times.
 390 ====
 391 The `event-rule-matches` trigger condition below specifies an event rule
 392 which matches all user space tracepoint events.
 393
 394 See the nloption:--rate-policy option above.
 395
 396 [role="term"]
 397 ----
 398 $ lttng add-trigger --condition=event-rule-matches \
 399                     --type=user --action=notify \
 400                     --rate-policy=every:10
 401 ----
 402 ====
 403
 404 .Add an ``event rule matches'' trigger with a tracing session starting action to be executed a single time after 40{nbsp}times.
 405 ====
 406 The `event-rule-matches` trigger condition below specifies an event rule
 407 which matches any Linux system call event (entry and exit) of which the
 408 `fd` event record field is less than{nbsp}3.
 409
 410 See the nloption:--rate-policy option above.
 411
 412 [role="term"]
 413 ----
 414 $ lttng add-trigger --condition=event-rule-matches \
 415                     --type=syscall --filter='fd < 3' \
 416                     --action=start-session my-session \
 417                     --rate-policy=once-after:40
 418 ----
 419 ====
 420
 421
 422 include::common-footer.txt[]
 423
 424
 425 SEE ALSO
 426 --------
 427 man:lttng(1),
 428 man:lttng-list-triggers(1),
 429 man:lttng-remove-trigger(1),
 430 man:lttng-concepts(7)