Commit | Line | Data |
---|---|---|
a942557f SM |
1 | lttng-add-trigger(1) |
2 | ===================== | |
943061bd | 3 | :revdate: 27 May 2020 |
a942557f SM |
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 | ||
943061bd JR |
59 | + |
60 | Fields to capture can be specified with the option:--capture option, followed by | |
61 | a capture expression. Zero or more captures can be configured. See the | |
62 | <<capture-expr, Capture expression>> section below for more information. | |
63 | ||
d0a70fd5 | 64 | [[actions]] |
a942557f SM |
65 | Actions |
66 | ~~~~~~~ | |
67 | ||
68 | Actions are specified with the `--action` option, followed by an action | |
69 | name, and possibly some more arguments, depending on the specific | |
70 | action. There must be at least one action given in the | |
71 | `lttng add-trigger` invocation. | |
72 | ||
73 | The available actions are: | |
74 | ||
75 | Notify: *notify*:: | |
76 | This action causes the LTTng session daemon to send a notification, | |
77 | through its notification mechanism (see man:lttng-sessiond(8)). | |
78 | Some details about the condition evaluation are sent along with the | |
79 | notification. | |
80 | ||
81 | Start session: *start-session* session-name:: | |
82 | This action causes the LTTng session daemon to start 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 | Stop session: *stop-session* session-name:: | |
87 | This action causes the LTTng session daemon to stop tracing for the | |
88 | session with the given name. If no session with the given name exist | |
89 | at the time the condition is met, nothing is done. | |
90 | ||
91 | Rotate session: *rotate-session* session-name:: | |
92 | This action causes the LTTng session daemon to rotate the session | |
93 | with the given name. See man:lttng-rotate(1) for more information | |
94 | about the session rotation concept. If no session with the given | |
95 | name exist at the time the condition is met, nothing is done. | |
96 | ||
97 | Snapshot session: *snapshot-session* session-name:: | |
98 | This action causes the LTTng session daemon to take a snapshot of the | |
99 | session with the given name. See man:lttng-snapshot(1) for more | |
100 | information about the session snapshot concept. If no session with | |
101 | the given name exist at the time the condition is met, nothing is | |
102 | done. | |
103 | ||
943061bd JR |
104 | |
105 | [[capture-expr]] | |
106 | Capture expression | |
107 | ~~~~~~~~~~~~~~~~~~ | |
108 | ||
109 | A capture expression can be specified with the option:--capture option when | |
110 | creating a new on-event condition. If the capture expression corresponds with an | |
111 | event's field when tracing, the runtime dynamic value corresponding to the | |
112 | capture expression is captured. | |
113 | ||
114 | NOTE: Make sure to **single-quote** the capture expression when running | |
115 | the command from a shell, as capture expressions typically include | |
116 | characters having a special meaning for most shells. | |
117 | ||
118 | * Supported field types: | |
119 | - integer, | |
120 | - unsigned integer, | |
121 | - floating point value, | |
122 | - fixed-size array of integers, | |
123 | - variable-size array of integers (sequence), | |
124 | - enumeration, | |
125 | - text string, | |
126 | - element of any allowing previous type. | |
127 | ||
128 | * The dynamic value of an event field is captured by using its name as a C | |
129 | identifier. | |
130 | + | |
131 | The square bracket notation is available, like in the C | |
132 | language, to access array/sequence field. | |
133 | Only a constant, positive integer number can be used within square | |
134 | brackets. If the index is out of bounds, the capture expression | |
135 | evaluates to `unavailable`. | |
136 | + | |
137 | An enumeration field's value is an integer. | |
138 | + | |
139 | When the capture's field does not exist, the capture expression | |
140 | evaluates to `unavailable`. | |
141 | + | |
142 | Examples: `my_field`, `target_cpu`, `seq[7]` | |
143 | ||
144 | * The dynamic value of a statically-known context field is captured by | |
145 | prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of | |
146 | available contexts. | |
147 | + | |
148 | When the expression's statically-known context field does not exist, | |
149 | the capture expression evaluates to `unavailable`. | |
150 | + | |
151 | Examples: `$ctx.prio`, `$ctx.preemptible`, | |
152 | `$ctx.perf:cpu:stalled-cycles-frontend`. | |
153 | + | |
154 | NOTE: The statically-known context field does NOT need to be added using the | |
155 | man:lttng-add-context(1) command. The statically-known context fields are | |
156 | always available in the context of triggers. | |
157 | ||
158 | * The dynamic value of an application-specific context field is captured by | |
159 | prefixing its name with `$app.` (follows the format used to add such a context | |
160 | field with the man:lttng-add-context(1) command). | |
161 | + | |
162 | When the expression's application-specific context field does not exist, | |
163 | the capture expression evaluates to `unavailable`. | |
164 | + | |
165 | Example: `$app.server:cur_user`. | |
166 | + | |
167 | NOTE: The application-specific context field does NOT need to be added using the | |
168 | man:lttng-add-context(1) command. The application-specific context fields fields | |
169 | are always available in the context of triggers. | |
170 | ||
171 | ||
a942557f SM |
172 | OPTIONS |
173 | ------- | |
174 | ||
d0a70fd5 SM |
175 | option:--condition:: |
176 | Define the condition for the trigger. See the | |
177 | <<conditions,CONDITIONS>> section for more details. | |
178 | ||
179 | option:--action:: | |
180 | Define an action for the trigger. See the <<actions,ACTIONS>> | |
181 | section for more details. | |
182 | ||
a942557f SM |
183 | option:--id='ID':: |
184 | Set the id of the trigger to 'ID'. If omitted, an id will | |
185 | automatically be assigned to the trigger by the session daemon. | |
186 | + | |
187 | If a trigger with the specified 'ID' already exists, the trigger | |
188 | creation will fail. | |
189 | ||
190 | option:--fire-every 'N':: | |
191 | Execute the trigger's actions every 'N' times the condition is met. | |
192 | ||
193 | option:--fire-once-after 'N':: | |
194 | Execute the trigger's actions once after 'N' times the condition is | |
195 | met, then never after that. | |
196 | ||
197 | include::common-cmd-help-options.txt[] | |
198 | ||
199 | ||
200 | include::common-cmd-footer.txt[] | |
201 | ||
202 | ||
203 | SEE ALSO | |
204 | -------- | |
205 | man:lttng-list-triggers(1), | |
206 | man:lttng-remove-trigger(1), | |
207 | man:lttng(1) |