| 1 | lttng-add-trigger(1) |
| 2 | ===================== |
| 3 | :revdate: 17 January 2020 |
| 4 | |
| 5 | |
| 6 | NAME |
| 7 | ---- |
| 8 | lttng-add-trigger - Create LTTng triggers |
| 9 | |
| 10 | |
| 11 | SYNOPSIS |
| 12 | -------- |
| 13 | |
| 14 | [verse] |
| 15 | *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID] |
| 16 | [--fire-every N] [--fire-once-after N] |
| 17 | --condition CONDITION-NAME CONDITION-ARGS |
| 18 | --action ACTION-NAME ACTION-ARGS |
| 19 | [--action ACTION-NAME ACTION-ARGS]... |
| 20 | |
| 21 | |
| 22 | DESCRIPTION |
| 23 | ----------- |
| 24 | |
| 25 | The `lttng add-trigger` command is used to create triggers. A |
| 26 | trigger is an association between a *condition* and one or more |
| 27 | *actions*. When the condition associated to a trigger is met, the |
| 28 | actions associated to that trigger are executed. The tracing does not |
| 29 | have to be active for the conditions to be met, and triggers are |
| 30 | independent from tracing sessions. |
| 31 | |
| 32 | By default, a trigger fires every time its condition is met. The |
| 33 | '--fire-every' and '--fire-once-after' options can be used to change |
| 34 | this mode. |
| 35 | |
| 36 | The syntax by which conditions and actions are specified is described |
| 37 | below. |
| 38 | |
| 39 | Conditions |
| 40 | ~~~~~~~~~~ |
| 41 | |
| 42 | Conditions are specified with the `--condition` option, followed by a |
| 43 | condition name, and possibly some more arguments, depending on the |
| 44 | specific condition. There must be exactly one condition given in the |
| 45 | `lttng add-trigger` invocation. |
| 46 | |
| 47 | The available conditions are: |
| 48 | |
| 49 | Event rule: `on-event [event rule arguments]`:: |
| 50 | This type of condition is met when the tracer encounters an event |
| 51 | matching the given even rule. The arguments describing the event |
| 52 | rule are the same as those describing the event rules of the |
| 53 | man:lttng-enable-event(1) command, with these exceptions: |
| 54 | |
| 55 | - It is not possible to use filter operands that use values from |
| 56 | the context. |
| 57 | |
| 58 | Actions |
| 59 | ~~~~~~~ |
| 60 | |
| 61 | Actions are specified with the `--action` option, followed by an action |
| 62 | name, and possibly some more arguments, depending on the specific |
| 63 | action. There must be at least one action given in the |
| 64 | `lttng add-trigger` invocation. |
| 65 | |
| 66 | The available actions are: |
| 67 | |
| 68 | Notify: *notify*:: |
| 69 | This action causes the LTTng session daemon to send a notification, |
| 70 | through its notification mechanism (see man:lttng-sessiond(8)). |
| 71 | Some details about the condition evaluation are sent along with the |
| 72 | notification. |
| 73 | |
| 74 | Start session: *start-session* session-name:: |
| 75 | This action causes the LTTng session daemon to start tracing for the |
| 76 | session with the given name. If no session with the given name exist |
| 77 | at the time the condition is met, nothing is done. |
| 78 | |
| 79 | Stop session: *stop-session* session-name:: |
| 80 | This action causes the LTTng session daemon to stop tracing for the |
| 81 | session with the given name. If no session with the given name exist |
| 82 | at the time the condition is met, nothing is done. |
| 83 | |
| 84 | Rotate session: *rotate-session* session-name:: |
| 85 | This action causes the LTTng session daemon to rotate the session |
| 86 | with the given name. See man:lttng-rotate(1) for more information |
| 87 | about the session rotation concept. If no session with the given |
| 88 | name exist at the time the condition is met, nothing is done. |
| 89 | |
| 90 | Snapshot session: *snapshot-session* session-name:: |
| 91 | This action causes the LTTng session daemon to take a snapshot of the |
| 92 | session with the given name. See man:lttng-snapshot(1) for more |
| 93 | information about the session snapshot concept. If no session with |
| 94 | the given name exist at the time the condition is met, nothing is |
| 95 | done. |
| 96 | |
| 97 | OPTIONS |
| 98 | ------- |
| 99 | |
| 100 | option:--id='ID':: |
| 101 | Set the id of the trigger to 'ID'. If omitted, an id will |
| 102 | automatically be assigned to the trigger by the session daemon. |
| 103 | + |
| 104 | If a trigger with the specified 'ID' already exists, the trigger |
| 105 | creation will fail. |
| 106 | |
| 107 | option:--fire-every 'N':: |
| 108 | Execute the trigger's actions every 'N' times the condition is met. |
| 109 | |
| 110 | option:--fire-once-after 'N':: |
| 111 | Execute the trigger's actions once after 'N' times the condition is |
| 112 | met, then never after that. |
| 113 | |
| 114 | include::common-cmd-help-options.txt[] |
| 115 | |
| 116 | |
| 117 | include::common-cmd-footer.txt[] |
| 118 | |
| 119 | |
| 120 | SEE ALSO |
| 121 | -------- |
| 122 | man:lttng-list-triggers(1), |
| 123 | man:lttng-remove-trigger(1), |
| 124 | man:lttng(1) |