| 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-lttng-cmd-help-options.txt[] |
| 304 | |
| 305 | |
| 306 | include::common-lttng-cmd-after-options.txt[] |
| 307 | |
| 308 | |
| 309 | include::common-footer.txt[] |
| 310 | |
| 311 | |
| 312 | SEE ALSO |
| 313 | -------- |
| 314 | man:lttng(1), |
| 315 | man:lttng-list-triggers(1), |
| 316 | man:lttng-remove-trigger(1), |
| 317 | man:lttng-concepts(7) |