| 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-id='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-id 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'. |
| 252 | + |
| 253 | A trigger which ``fires'' (its condition is satisfied) leads to an |
| 254 | execution request for each of its actions, in order. An execution |
| 255 | request of a given action{nbsp}__A__ first increments the execution |
| 256 | request count{nbsp}__C__ of{nbsp}__A__. An execution request can then |
| 257 | become an actual execution when{nbsp}__C__ satisfies the rate policy |
| 258 | of{nbsp}__A__. |
| 259 | + |
| 260 | The default action rate policy is `every:1` (always execute{nbsp}__A__). |
| 261 | Use this option to specify another rate policy. |
| 262 | + |
| 263 | 'POLICY' is one of: |
| 264 | + |
| 265 | -- |
| 266 | ++once-after:++__COUNT__:: |
| 267 | Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'. |
| 268 | + |
| 269 | In other words, execute{nbsp}__A__ a single time after 'COUNT' execution |
| 270 | requests. |
| 271 | |
| 272 | ++every:++__COUNT__:: |
| 273 | Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'. |
| 274 | + |
| 275 | In other words, execute{nbsp}__A__ every 'COUNT' execution requests. |
| 276 | -- |
| 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-id='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) |