Commit | Line | Data |
---|---|---|
a942557f | 1 | lttng-add-trigger(1) |
484b2a0c | 2 | ==================== |
26f0c779 | 3 | :revdate: 3 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 | |
a942557f | 43 | |
484b2a0c PP |
44 | [[cond-spec]] |
45 | Condition specifier | |
46 | ~~~~~~~~~~~~~~~~~~~ | |
47 | Synopsis: | |
48 | ||
49 | [verse] | |
50 | option:--condition='CONDTYPE' ['CONDARGS'] | |
a942557f | 51 | |
484b2a0c PP |
52 | A condition specifier is the option:--condition option, which specifies |
53 | the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE', | |
54 | with zero or more arguments 'CONDARGS'. | |
55 | ||
56 | The available condition types are: | |
57 | ||
58 | [[er-matches-cond-spec]]`event-rule-matches`:: | |
59 | Synopsis: | |
60 | + | |
61 | [verse] | |
26f0c779 | 62 | option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC' |
484b2a0c | 63 | {nbsp} |
943061bd | 64 | + |
484b2a0c PP |
65 | An `event-rule-matches` condition is considered satisfied when the event |
66 | rule specified with 'ERSPEC' matches an event. | |
67 | + | |
68 | See man:lttng-event-rule(7) to learn how to specify an event rule | |
69 | ('ERSPEC' part). | |
70 | + | |
71 | Capture event record and context fields with one or more | |
72 | nloption:--capture options (see the <<capture-descr,Capture descriptor>> | |
73 | section below to learn more). When an `event-rule-matches` condition | |
74 | with capture descriptors is satisfied, the captured field values are | |
75 | available in the evaluation object of the condition using the | |
76 | liblttng-ctl C{nbsp}API. | |
77 | + | |
78 | IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the | |
79 | `add-trigger` command from a shell, as capture descriptors can include | |
80 | characters having a special meaning for most shells. | |
943061bd | 81 | |
a942557f | 82 | |
484b2a0c PP |
83 | [[capture-descr]] |
84 | Capture descriptor | |
85 | ~~~~~~~~~~~~~~~~~~ | |
86 | A capture descriptor is a textual expression which describes how to read | |
87 | an event record or context field. | |
a942557f | 88 | |
484b2a0c PP |
89 | The argument of a nloption:--capture option, when using an |
90 | <<er-matches-cond-spec,``event rule matches'' condition specifier>> | |
91 | (`event-rule-matches`), is a capture descriptor. | |
a942557f | 92 | |
484b2a0c | 93 | A capture descriptor expression is one of: |
a942557f | 94 | |
484b2a0c PP |
95 | 'NAME':: |
96 | An event record field named 'NAME'. | |
97 | + | |
98 | The supported event record field types are: | |
99 | + | |
100 | -- | |
101 | * Integer | |
102 | * Enumeration (integral value) | |
103 | * Floating point number | |
104 | * Static array of integers | |
105 | * Dynamic array (``sequence'') of integers | |
106 | * Text string | |
107 | -- | |
108 | + | |
109 | Examples: `my_field`, `target_cpu`, `ip`. | |
a942557f | 110 | |
484b2a0c PP |
111 | ++$ctx.++__NAME__:: |
112 | A statically-known context field named 'NAME'. | |
113 | + | |
114 | List the available statically-known context field names with | |
115 | man:lttng-add-context(1). | |
116 | + | |
117 | Examples: `$ctx.prio`, `$ctx.preemptible`, | |
118 | `$ctx.perf:cpu:stalled-cycles-frontend`. | |
119 | ||
120 | ++$app.++__PROVIDER__++.++__NAME__:: | |
121 | An application-specific context field named 'NAME' from the | |
122 | provider 'PROVIDER'. | |
123 | + | |
124 | See man:lttng-add-context(1) to learn more about application-specific | |
125 | context fields. | |
126 | + | |
127 | Example: `$app.server:cur_user`. | |
a942557f | 128 | |
484b2a0c PP |
129 | __EXPR__++[++__INDEX__++]++:: |
130 | The element at index 'INDEX' of the array field (static or dynamic) | |
131 | identified by the expression 'EXPR'. | |
132 | + | |
133 | 'INDEX' must be a constant, positive integral value. | |
134 | + | |
135 | Examples: `ip[3]`, `user_ids[15]`. | |
a942557f | 136 | |
484b2a0c PP |
137 | If, when an event rule matches, a given capture descriptor doesn't |
138 | identify an existing event or context field, then the captured value is | |
139 | reported as being unavailable. This applies to: | |
a942557f | 140 | |
484b2a0c PP |
141 | * A nonexistent event record field name. |
142 | * A nonexistent statically-known context field name. | |
143 | * A nonexistent application-specific context field name. | |
144 | * An out-of-bounds array field index. | |
943061bd | 145 | |
943061bd | 146 | |
484b2a0c PP |
147 | [[action-spec]] |
148 | Action specifier | |
149 | ~~~~~~~~~~~~~~~~ | |
150 | Synopsis: | |
943061bd | 151 | |
484b2a0c PP |
152 | [verse] |
153 | option:--action='ACTTYPE' ['ACTARGS'] | |
154 | ||
155 | An action specifier is the option:--action option, which specifies | |
156 | the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero | |
157 | or more arguments 'ACTARGS'. | |
158 | ||
159 | The available action types are: | |
160 | ||
161 | Notify:: | |
162 | Synopsis: | |
163 | + | |
164 | [verse] | |
26f0c779 | 165 | option:--action=**notify** [nloption:--rate-policy='POLICY'] |
484b2a0c PP |
166 | {nbsp} |
167 | + | |
168 | Sends a notification through the notification | |
169 | mechanism of the session daemon (see man:lttng-session(8)). | |
170 | + | |
171 | The session daemon sends details about the condition evaluation along | |
172 | with the notification. | |
173 | + | |
174 | As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program | |
175 | to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers). | |
176 | + | |
177 | See below for the nloption:--rate-policy option. | |
943061bd | 178 | |
484b2a0c PP |
179 | Start a tracing session:: |
180 | Synopsis: | |
181 | + | |
182 | [verse] | |
26f0c779 | 183 | option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c PP |
184 | {nbsp} |
185 | + | |
186 | Starts the tracing session named 'SESSION' like man:lttng-start(1) | |
187 | would. | |
188 | + | |
189 | If no tracing session has the name 'SESSION' when LTTng is ready to | |
190 | execute the action, LTTng does nothing. | |
191 | + | |
192 | See below for the nloption:--rate-policy option. | |
943061bd | 193 | |
484b2a0c PP |
194 | Stop a tracing session:: |
195 | Synopsis: | |
943061bd | 196 | + |
484b2a0c | 197 | [verse] |
26f0c779 | 198 | option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c | 199 | {nbsp} |
943061bd | 200 | + |
484b2a0c | 201 | Stops the tracing session named 'SESSION' like man:lttng-stop(1) would. |
943061bd | 202 | + |
484b2a0c PP |
203 | If no tracing session has the name 'SESSION' when LTTng is ready to |
204 | execute the action, LTTng does nothing. | |
943061bd | 205 | + |
484b2a0c | 206 | See below for the nloption:--rate-policy option. |
943061bd | 207 | |
484b2a0c PP |
208 | Rotate a tracing session:: |
209 | Synopsis: | |
210 | + | |
211 | [verse] | |
26f0c779 | 212 | option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c | 213 | {nbsp} |
943061bd | 214 | + |
484b2a0c PP |
215 | Archives the current trace chunk of the tracing session named 'SESSION' |
216 | like man:lttng-rotate(1) would. | |
943061bd | 217 | + |
484b2a0c PP |
218 | If no tracing session has the name 'SESSION' when LTTng is ready to |
219 | execute the action, LTTng does nothing. | |
943061bd | 220 | + |
484b2a0c | 221 | See below for the nloption:--rate-policy option. |
943061bd | 222 | |
484b2a0c PP |
223 | Take a tracing session snapshot:: |
224 | Synopsis: | |
943061bd | 225 | + |
484b2a0c | 226 | [verse] |
26f0c779 | 227 | option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY'] |
484b2a0c | 228 | {nbsp} |
943061bd | 229 | + |
484b2a0c PP |
230 | Takes a snapshot of the tracing session named 'SESSION' like |
231 | man:lttng-snapshot(1) would. | |
232 | + | |
233 | When the condition of the trigger is satisfied, the tracing session | |
234 | named 'SESSION', if any, must be a snapshot-mode tracing session | |
235 | (see man:lttng-create(1)). | |
236 | + | |
237 | If no tracing session has the name 'SESSION' when LTTng is ready to | |
238 | execute the action, LTTng does nothing. | |
239 | + | |
240 | See below for the nloption:--rate-policy option. | |
241 | ||
242 | Common action options (as of LTTng{nbsp}{lttng_version}): | |
243 | ||
244 | nloption:--rate-policy='POLICY':: | |
72d8cc10 PP |
245 | Set the rate policy of the action to 'POLICY' instead of |
246 | `every:1` (always execute). | |
484b2a0c PP |
247 | + |
248 | A trigger which ``fires'' (its condition is satisfied) leads to an | |
249 | execution request for each of its actions, in order. An execution | |
250 | request of a given action{nbsp}__A__ first increments the execution | |
251 | request count{nbsp}__C__ of{nbsp}__A__. An execution request can then | |
252 | become an actual execution when{nbsp}__C__ satisfies the rate policy | |
253 | of{nbsp}__A__. | |
254 | + | |
484b2a0c PP |
255 | 'POLICY' is one of: |
256 | + | |
257 | -- | |
258 | ++once-after:++__COUNT__:: | |
259 | Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'. | |
260 | + | |
261 | In other words, execute{nbsp}__A__ a single time after 'COUNT' execution | |
262 | requests. | |
263 | ||
264 | ++every:++__COUNT__:: | |
265 | Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'. | |
266 | + | |
267 | In other words, execute{nbsp}__A__ every 'COUNT' execution requests. | |
268 | -- | |
269 | + | |
72d8cc10 PP |
270 | 'COUNT' must be an integer greater than{nbsp}0. |
271 | + | |
484b2a0c PP |
272 | As of LTTng{nbsp}{lttng_version}, you can use this option with any |
273 | action type, but new action types in the future may not support it. | |
943061bd JR |
274 | |
275 | ||
a942557f SM |
276 | OPTIONS |
277 | ------- | |
484b2a0c PP |
278 | Identification |
279 | ~~~~~~~~~~~~~~ | |
280 | option:--name='NAME':: | |
281 | Set the unique name of the trigger to add to 'NAME' instead of the | |
282 | `add-trigger` command automatically assigning one. | |
283 | ||
d938377c | 284 | option:--owner-uid='UID':: |
484b2a0c PP |
285 | Add the trigger as the Unix user having the user ID 'UID'. |
286 | + | |
287 | You may only use this option if your Unix user is `root`. | |
a942557f | 288 | |
d0a70fd5 | 289 | |
484b2a0c PP |
290 | Specifier |
291 | ~~~~~~~~~ | |
292 | option:--condition='CONDTYPE':: | |
293 | Introductory option for a condition specifier of type 'CONDTYPE'. | |
a942557f | 294 | + |
484b2a0c | 295 | See the <<cond-spec,Condition specifier>> section above to learn more. |
a942557f | 296 | |
484b2a0c PP |
297 | option:--action='ACTTYPE':: |
298 | Introductory option for an action specifier of type 'ACTTYPE'. | |
299 | + | |
300 | See the <<action-spec,Action specifier>> section above to learn more. | |
a942557f | 301 | |
a942557f SM |
302 | |
303 | include::common-cmd-help-options.txt[] | |
304 | ||
305 | ||
306 | include::common-cmd-footer.txt[] | |
307 | ||
308 | ||
309 | SEE ALSO | |
310 | -------- | |
484b2a0c | 311 | man:lttng(1), |
26f0c779 | 312 | man:lttng-concepts(7), |
a942557f | 313 | man:lttng-list-triggers(1), |
484b2a0c | 314 | man:lttng-remove-trigger(1) |