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 | ||
| 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) |