projects / lttng-tools.git / blame
| Commit | Line | Data |
|---|---|---|
| a942557f SM |
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 | ||
| d0a70fd5 | 39 | [[conditions]] |
| a942557f SM |
40 | Conditions |
| 41 | ~~~~~~~~~~ | |
| 42 | ||
| 43 | Conditions are specified with the `--condition` option, followed by a | |
| 44 | condition name, and possibly some more arguments, depending on the | |
| 45 | specific condition. There must be exactly one condition given in the | |
| 46 | `lttng add-trigger` invocation. | |
| 47 | ||
| 48 | The available conditions are: | |
| 49 | ||
| 50 | Event rule: `on-event [event rule arguments]`:: | |
| 51 | This type of condition is met when the tracer encounters an event | |
| 52 | matching the given even rule. The arguments describing the event | |
| 53 | rule are the same as those describing the event rules of the | |
| 54 | man:lttng-enable-event(1) command, with these exceptions: | |
| 55 | ||
| 56 | - It is not possible to use filter operands that use values from | |
| 57 | the context. | |
| 58 | ||
| d0a70fd5 | 59 | [[actions]] |
| a942557f SM |
60 | Actions |
| 61 | ~~~~~~~ | |
| 62 | ||
| 63 | Actions are specified with the `--action` option, followed by an action | |
| 64 | name, and possibly some more arguments, depending on the specific | |
| 65 | action. There must be at least one action given in the | |
| 66 | `lttng add-trigger` invocation. | |
| 67 | ||
| 68 | The available actions are: | |
| 69 | ||
| 70 | Notify: *notify*:: | |
| 71 | This action causes the LTTng session daemon to send a notification, | |
| 72 | through its notification mechanism (see man:lttng-sessiond(8)). | |
| 73 | Some details about the condition evaluation are sent along with the | |
| 74 | notification. | |
| 75 | ||
| 76 | Start session: *start-session* session-name:: | |
| 77 | This action causes the LTTng session daemon to start tracing for the | |
| 78 | session with the given name. If no session with the given name exist | |
| 79 | at the time the condition is met, nothing is done. | |
| 80 | ||
| 81 | Stop session: *stop-session* session-name:: | |
| 82 | This action causes the LTTng session daemon to stop tracing for the | |
| 83 | session with the given name. If no session with the given name exist | |
| 84 | at the time the condition is met, nothing is done. | |
| 85 | ||
| 86 | Rotate session: *rotate-session* session-name:: | |
| 87 | This action causes the LTTng session daemon to rotate the session | |
| 88 | with the given name. See man:lttng-rotate(1) for more information | |
| 89 | about the session rotation concept. If no session with the given | |
| 90 | name exist at the time the condition is met, nothing is done. | |
| 91 | ||
| 92 | Snapshot session: *snapshot-session* session-name:: | |
| 93 | This action causes the LTTng session daemon to take a snapshot of the | |
| 94 | session with the given name. See man:lttng-snapshot(1) for more | |
| 95 | information about the session snapshot concept. If no session with | |
| 96 | the given name exist at the time the condition is met, nothing is | |
| 97 | done. | |
| 98 | ||
| 99 | OPTIONS | |
| 100 | ------- | |
| 101 | ||
| d0a70fd5 SM |
102 | option:--condition:: |
| 103 | Define the condition for the trigger. See the | |
| 104 | <<conditions,CONDITIONS>> section for more details. | |
| 105 | ||
| 106 | option:--action:: | |
| 107 | Define an action for the trigger. See the <<actions,ACTIONS>> | |
| 108 | section for more details. | |
| 109 | ||
| a942557f SM |
110 | option:--id='ID':: |
| 111 | Set the id of the trigger to 'ID'. If omitted, an id will | |
| 112 | automatically be assigned to the trigger by the session daemon. | |
| 113 | + | |
| 114 | If a trigger with the specified 'ID' already exists, the trigger | |
| 115 | creation will fail. | |
| 116 | ||
| 117 | option:--fire-every 'N':: | |
| 118 | Execute the trigger's actions every 'N' times the condition is met. | |
| 119 | ||
| 120 | option:--fire-once-after 'N':: | |
| 121 | Execute the trigger's actions once after 'N' times the condition is | |
| 122 | met, then never after that. | |
| 123 | ||
| 124 | include::common-cmd-help-options.txt[] | |
| 125 | ||
| 126 | ||
| 127 | include::common-cmd-footer.txt[] | |
| 128 | ||
| 129 | ||
| 130 | SEE ALSO | |
| 131 | -------- | |
| 132 | man:lttng-list-triggers(1), | |
| 133 | man:lttng-remove-trigger(1), | |
| 134 | man:lttng(1) |