Commit | Line | Data |
---|---|---|
a942557f | 1 | lttng-add-trigger(1) |
484b2a0c | 2 | ==================== |
473c70ca | 3 | :revdate: 6 May 2021 |
a942557f SM |
4 | |
5 | ||
6 | NAME | |
7 | ---- | |
484b2a0c | 8 | lttng-add-trigger - Add an LTTng trigger |
a942557f SM |
9 | |
10 | ||
11 | SYNOPSIS | |
12 | -------- | |
a942557f | 13 | [verse] |
d938377c | 14 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-uid='UID'] |
484b2a0c PP |
15 | option:--condition='CONDTYPE' ['CONDARGS'] |
16 | option:--action='ACTTYPE' ['ACTARGS'] [option:--action='ACTTYPE' ['ACTARGS']]... | |
a942557f SM |
17 | |
18 | DESCRIPTION | |
19 | ----------- | |
484b2a0c | 20 | The `lttng add-trigger` command creates and adds an LTTng _trigger_ to |
26f0c779 | 21 | the connected session daemon (see man:lttng-sessiond(8)). |
484b2a0c | 22 | |
26f0c779 | 23 | See man:lttng-concepts(7) to learn more about LTTng triggers. |
a942557f | 24 | |
26f0c779 PP |
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. | |
a942557f | 28 | |
484b2a0c | 29 | The `add-trigger` command adds a trigger for your Unix user. If your |
26f0c779 | 30 | Unix user is `root`, you may add the trigger as another user with the |
d938377c | 31 | option:--owner-uid option. |
a942557f | 32 | |
484b2a0c PP |
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 | |
26f0c779 | 36 | attempts to execute the actions of a firing trigger in this order. |
a942557f | 37 | |
26f0c779 PP |
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. | |
a942557f | 40 | |
26f0c779 | 41 | Remove a trigger with the man:lttng-remove-trigger(1) command. |
a942557f | 42 | |
473c70ca PP |
43 | See the <<examples,EXAMPLES>> section below for usage examples. |
44 | ||
a942557f | 45 | |
484b2a0c PP |
46 | [[cond-spec]] |
47 | Condition specifier | |
48 | ~~~~~~~~~~~~~~~~~~~ | |
49 | Synopsis: | |
50 | ||
51 | [verse] | |
52 | option:--condition='CONDTYPE' ['CONDARGS'] | |
a942557f | 53 | |
484b2a0c PP |
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] | |
26f0c779 | 64 | option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC' |
484b2a0c | 65 | {nbsp} |
943061bd | 66 | + |
484b2a0c PP |
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 descriptor>> | |
75 | section below to learn more). When an `event-rule-matches` condition | |
76 | with capture descriptors is satisfied, the captured field values are | |
77 | available in the evaluation object of the condition using the | |
78 | 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. | |
943061bd | 83 | |
a942557f | 84 | |
484b2a0c PP |
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. | |
a942557f | 90 | |
484b2a0c PP |
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. | |
a942557f | 94 | |
484b2a0c | 95 | A capture descriptor expression is one of: |
a942557f | 96 | |
484b2a0c PP |
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`. | |
a942557f | 112 | |
484b2a0c PP |
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`. | |
a942557f | 130 | |
484b2a0c PP |
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]`. | |
a942557f | 138 | |
484b2a0c PP |
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: | |
a942557f | 142 | |
484b2a0c PP |
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. | |
943061bd | 147 | |
943061bd | 148 | |
484b2a0c PP |
149 | [[action-spec]] |
150 | Action specifier | |
151 | ~~~~~~~~~~~~~~~~ | |
152 | Synopsis: | |
943061bd | 153 | |
484b2a0c PP |
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] | |
26f0c779 | 167 | option:--action=**notify** [nloption:--rate-policy='POLICY'] |
484b2a0c PP |
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. | |
943061bd | 180 | |
484b2a0c PP |
181 | Start a tracing session:: |
182 | Synopsis: | |
183 | + | |
184 | [verse] | |
26f0c779 | 185 | option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c PP |
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. | |
943061bd | 195 | |
484b2a0c PP |
196 | Stop a tracing session:: |
197 | Synopsis: | |
943061bd | 198 | + |
484b2a0c | 199 | [verse] |
26f0c779 | 200 | option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c | 201 | {nbsp} |
943061bd | 202 | + |
484b2a0c | 203 | Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. |
943061bd | 204 | + |
484b2a0c PP |
205 | If no tracing session has the name 'SESSION' when LTTng is ready to |
206 | execute the action, LTTng does nothing. | |
943061bd | 207 | + |
484b2a0c | 208 | See below for the nloption:--rate-policy option. |
943061bd | 209 | |
484b2a0c PP |
210 | Rotate a tracing session:: |
211 | Synopsis: | |
212 | + | |
213 | [verse] | |
26f0c779 | 214 | option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c | 215 | {nbsp} |
943061bd | 216 | + |
484b2a0c PP |
217 | Archives the current trace chunk of the tracing session named 'SESSION' |
218 | like man:lttng-rotate(1) would. | |
943061bd | 219 | + |
484b2a0c PP |
220 | If no tracing session has the name 'SESSION' when LTTng is ready to |
221 | execute the action, LTTng does nothing. | |
943061bd | 222 | + |
484b2a0c | 223 | See below for the nloption:--rate-policy option. |
943061bd | 224 | |
484b2a0c PP |
225 | Take a tracing session snapshot:: |
226 | Synopsis: | |
943061bd | 227 | + |
484b2a0c | 228 | [verse] |
26f0c779 | 229 | option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c | 230 | {nbsp} |
943061bd | 231 | + |
484b2a0c PP |
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':: | |
72d8cc10 PP |
247 | Set the rate policy of the action to 'POLICY' instead of |
248 | `every:1` (always execute). | |
484b2a0c PP |
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 | + | |
484b2a0c PP |
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 | + | |
72d8cc10 PP |
272 | 'COUNT' must be an integer greater than{nbsp}0. |
273 | + | |
484b2a0c PP |
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. | |
943061bd JR |
276 | |
277 | ||
a942557f SM |
278 | OPTIONS |
279 | ------- | |
484b2a0c PP |
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 | ||
d938377c | 286 | option:--owner-uid='UID':: |
484b2a0c PP |
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`. | |
a942557f | 290 | |
d0a70fd5 | 291 | |
484b2a0c PP |
292 | Specifier |
293 | ~~~~~~~~~ | |
294 | option:--condition='CONDTYPE':: | |
295 | Introductory option for a condition specifier of type 'CONDTYPE'. | |
a942557f | 296 | + |
484b2a0c | 297 | See the <<cond-spec,Condition specifier>> section above to learn more. |
a942557f | 298 | |
484b2a0c PP |
299 | option:--action='ACTTYPE':: |
300 | Introductory option for an action specifier of type 'ACTTYPE'. | |
301 | + | |
302 | See the <<action-spec,Action specifier>> section above to learn more. | |
a942557f | 303 | |
a942557f | 304 | |
f5511eea | 305 | include::common-lttng-cmd-help-options.txt[] |
a942557f SM |
306 | |
307 | ||
f5511eea PP |
308 | include::common-lttng-cmd-after-options.txt[] |
309 | ||
310 | ||
473c70ca PP |
311 | [[examples]] |
312 | EXAMPLES | |
313 | -------- | |
314 | .Add an ``event rule matches'' trigger of which the action is to send a notification. | |
315 | ==== | |
316 | The `event-rule-matches` trigger condition below specifies an event rule | |
317 | which matches any Linux system call entry event with a name starting | |
318 | with `exec`. | |
319 | ||
320 | [role="term"] | |
321 | ---- | |
322 | $ lttng add-trigger --condition=event-rule-matches \ | |
323 | --domain=kernel --type=syscall:entry \ | |
324 | --name='exec*' --action=notify | |
325 | ---- | |
326 | ==== | |
327 | ||
328 | .Add an ``event rule matches'' trigger of which the action is to stop a tracing session and then rotate it. | |
329 | ==== | |
330 | The `event-rule-matches` trigger condition below specifies an event rule | |
331 | which matches any user space tracepoint event with a name starting with | |
332 | `my_app:` and with a log level at least as severe as a warning. | |
333 | ||
334 | The order of the option:--action options below is significant. | |
335 | ||
336 | [role="term"] | |
337 | ---- | |
338 | $ lttng add-trigger --condition=event-rule-matches \ | |
339 | --domain=user --name='my_app:*' \ | |
340 | --log-level=TRACE_WARNING.. \ | |
341 | --action=stop-session my-session \ | |
342 | --action=rotate-session my-session | |
343 | ---- | |
344 | ||
345 | See man:lttng-concepts(7) to learn more about tracing sessions and | |
346 | rotations. | |
347 | ==== | |
348 | ||
349 | .Add an ``event rule matches'' trigger with a specific name. | |
350 | ==== | |
351 | The `event-rule-matches` trigger condition below specifies an event rule | |
352 | which matches events which LTTng creates from the `my-logger` Python | |
353 | logger. | |
354 | ||
355 | The added trigger is named `my-trigger`, a unique name for your Unix | |
356 | user. | |
357 | ||
358 | See the option:--name option. | |
359 | ||
360 | [role="term"] | |
361 | ---- | |
362 | $ lttng add-trigger --name=my-trigger \ | |
363 | --condition=event-rule-matches \ | |
364 | --domain=python --name=my-logger \ | |
365 | --action=snapshot-session my-session | |
366 | ---- | |
367 | ==== | |
368 | ||
369 | .Add an ``event rule matches'' trigger as another Unix user. | |
370 | ==== | |
371 | The command line below adds a trigger as the `mireille` Unix user. | |
372 | ||
373 | Your Unix user must be `root` to use the option:--owner-uid option. | |
374 | ||
375 | The condition of the trigger specifies an event rule which matches LTTng | |
376 | kernel tracepoint events with a name which starts with `sched`. | |
377 | ||
378 | [role="term"] | |
379 | ---- | |
380 | # lttng add-trigger --owner-uid=$(id --user mireille) \ | |
381 | --condition=event-rule-matches \ | |
382 | --domain=kernel --name='sched*' \ | |
383 | --action=notify | |
384 | ---- | |
385 | ==== | |
386 | ||
387 | .Add an ``event rule matches'' trigger with a notification action to be executed every 10{nbsp}times. | |
388 | ==== | |
389 | The `event-rule-matches` trigger condition below specifies an event rule | |
390 | which matches all user space tracepoint events. | |
391 | ||
392 | See the nloption:--rate-policy option above. | |
393 | ||
394 | [role="term"] | |
395 | ---- | |
396 | $ lttng add-trigger --condition=event-rule-matches \ | |
397 | --domain=user --action=notify \ | |
398 | --rate-policy=every:10 | |
399 | ---- | |
400 | ==== | |
401 | ||
402 | .Add an ``event rule matches'' trigger with a tracing session starting action to be executed a single time after 40{nbsp}times. | |
403 | ==== | |
404 | The `event-rule-matches` trigger condition below specifies an event rule | |
405 | which matches any Linux system call event (entry and exit) of which the | |
406 | `fd` event record field is less than{nbsp}3. | |
407 | ||
408 | See the nloption:--rate-policy option above. | |
409 | ||
410 | [role="term"] | |
411 | ---- | |
412 | $ lttng add-trigger --condition=event-rule-matches \ | |
413 | --domain=kernel --type=syscall \ | |
414 | --filter='fd < 3' \ | |
415 | --action=start-session my-session \ | |
416 | --rate-policy=once-after:40 | |
417 | ---- | |
418 | ==== | |
419 | ||
420 | ||
f5511eea | 421 | include::common-footer.txt[] |
a942557f SM |
422 | |
423 | ||
424 | SEE ALSO | |
425 | -------- | |
484b2a0c | 426 | man:lttng(1), |
a942557f | 427 | man:lttng-list-triggers(1), |
af1c4164 PP |
428 | man:lttng-remove-trigger(1), |
429 | man:lttng-concepts(7) |