8 lttng-add-trigger - Add an LTTng trigger
14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-uid='UID']
15 option:--condition='CONDTYPE' ['CONDARGS']
16 option:--action='ACTTYPE' ['ACTARGS'] [option:--action='ACTTYPE' ['ACTARGS']]...
20 The `lttng add-trigger` command creates and adds an LTTng _trigger_ to
21 the connected session daemon (see man:lttng-sessiond(8)).
23 See man:lttng-concepts(7) to learn more about LTTng triggers.
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.
29 The `add-trigger` command adds a trigger for your Unix user. If your
30 Unix user is `root`, you may add the trigger as another user with the
31 option:--owner-uid option.
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
36 attempts to execute the actions of a firing trigger in this order.
38 See the ``<<examples,EXAMPLES>>'' section below for usage examples.
40 List the triggers of your Unix user, or of all users if your
41 Unix user is `root`, with the man:lttng-list-triggers(1) command.
43 Remove a trigger with the man:lttng-remove-trigger(1) command.
52 option:--condition='CONDTYPE' ['CONDARGS']
54 A condition specifier is the option:--condition option, which specifies
55 the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE',
56 with zero or more arguments 'CONDARGS'.
58 The available condition types are:
60 [[er-matches-cond-spec]]`event-rule-matches`::
64 option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
67 An `event-rule-matches` condition is considered satisfied when the event
68 rule specified with 'ERSPEC' matches an event.
70 See man:lttng-event-rule(7) to learn how to specify an event rule
73 Capture event record and context fields with one or more
74 nloption:--capture options (see the ``<<capture-descr,Capture
75 descriptor>>'' section below to learn more). When an
76 `event-rule-matches` condition with capture descriptors is satisfied,
77 the captured field values are available in the evaluation object of the
78 condition using the liblttng-ctl C{nbsp}API.
80 IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the
81 `add-trigger` command from a shell, as capture descriptors can include
82 characters having a special meaning for most shells.
88 A capture descriptor is a textual expression which describes how to read
89 an event record or context field.
91 The argument of a nloption:--capture option, when using an
92 <<er-matches-cond-spec,``event rule matches'' condition specifier>>
93 (`event-rule-matches`), is a capture descriptor.
95 A capture descriptor expression is one of:
98 An event record field named 'NAME'.
100 The supported event record field types are:
104 * Enumeration (integral value)
105 * Floating point number
106 * Static array of integers
107 * Dynamic array (``sequence'') of integers
111 Examples: `my_field`, `target_cpu`, `ip`.
114 A statically-known context field named 'NAME'.
116 List the available statically-known context field names with
117 man:lttng-add-context(1).
119 Examples: `$ctx.prio`, `$ctx.preemptible`,
120 `$ctx.perf:cpu:stalled-cycles-frontend`.
122 ++$app.++__PROVIDER__++.++__NAME__::
123 An application-specific context field named 'NAME' from the
126 See man:lttng-add-context(1) to learn more about application-specific
129 Example: `$app.server:cur_user`.
131 __EXPR__++[++__INDEX__++]++::
132 The element at index 'INDEX' of the array field (static or dynamic)
133 identified by the expression 'EXPR'.
135 'INDEX' must be a constant, positive integral value.
137 Examples: `ip[3]`, `user_ids[15]`.
139 If, when an event rule matches, a given capture descriptor doesn't
140 identify an existing event or context field, then the captured value is
141 reported as being unavailable. This applies to:
143 * A nonexistent event record field name.
144 * A nonexistent statically-known context field name.
145 * A nonexistent application-specific context field name.
146 * An out-of-bounds array field index.
155 option:--action='ACTTYPE' ['ACTARGS']
157 An action specifier is the option:--action option, which specifies
158 the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero
159 or more arguments 'ACTARGS'.
161 The available action types are:
167 option:--action=**notify** [nloption:--rate-policy='POLICY']
170 Sends a notification through the notification
171 mechanism of the session daemon (see man:lttng-session(8)).
173 The session daemon sends details about the condition evaluation along
174 with the notification.
176 As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program
177 to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers).
179 See below for the nloption:--rate-policy option.
181 Start a recording session::
185 option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
188 Starts the recording session named 'SESSION' like man:lttng-start(1)
191 If no recording session has the name 'SESSION' when LTTng is ready to
192 execute the action, LTTng does nothing.
194 See below for the nloption:--rate-policy option.
196 Stop a recording session::
200 option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
203 Stops the recording session named 'SESSION' like man:lttng-stop(1)
206 If no recording session has the name 'SESSION' when LTTng is ready to
207 execute the action, LTTng does nothing.
209 See below for the nloption:--rate-policy option.
211 Rotate a recording session::
215 option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
218 Archives the current trace chunk of the recording session named
219 'SESSION' like man:lttng-rotate(1) would.
221 If no recording session has the name 'SESSION' when LTTng is ready to
222 execute the action, LTTng does nothing.
224 See below for the nloption:--rate-policy option.
226 Take a recording session snapshot::
230 option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
233 Takes a snapshot of the recording session named 'SESSION' like
234 man:lttng-snapshot(1) would.
236 When the condition of the trigger is satisfied, the recording session
237 named 'SESSION', if any, must be a snapshot-mode recording session
238 (see man:lttng-create(1)).
240 If no recording session has the name 'SESSION' when LTTng is ready to
241 execute the action, LTTng does nothing.
243 See below for the nloption:--rate-policy option.
245 Common action options (as of LTTng{nbsp}{lttng_version}):
247 nloption:--rate-policy='POLICY'::
248 Set the rate policy of the action to 'POLICY' instead of
249 `every:1` (always execute).
251 A trigger which ``fires'' (its condition is satisfied) leads to an
252 execution request for each of its actions, in order. An execution
253 request of a given action{nbsp}__A__ first increments the execution
254 request count{nbsp}__C__ of{nbsp}__A__. An execution request can then
255 become an actual execution when{nbsp}__C__ satisfies the rate policy
261 ++once-after:++__COUNT__::
262 Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'.
264 In other words, execute{nbsp}__A__ a single time after 'COUNT' execution
267 ++every:++__COUNT__::
268 Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'.
270 In other words, execute{nbsp}__A__ every 'COUNT' execution requests.
273 'COUNT' must be an integer greater than{nbsp}0.
275 As of LTTng{nbsp}{lttng_version}, you can use this option with any
276 action type, but new action types in the future may not support it.
283 option:--name='NAME'::
284 Set the unique name of the trigger to add to 'NAME' instead of the
285 `add-trigger` command automatically assigning one.
287 option:--owner-uid='UID'::
288 Add the trigger as the Unix user having the user ID 'UID'.
290 You may only use this option if your Unix user is `root`.
295 option:--condition='CONDTYPE'::
296 Introductory option for a condition specifier of type 'CONDTYPE'.
298 See the ``<<cond-spec,Condition specifier>>'' section above to learn
301 option:--action='ACTTYPE'::
302 Introductory option for an action specifier of type 'ACTTYPE'.
304 See the ``<<action-spec,Action specifier>>'' section above to learn
308 include::common-lttng-cmd-help-options.txt[]
311 include::common-lttng-cmd-after-options.txt[]
317 .Add an ``event rule matches'' trigger of which the action is to send a notification.
319 The `event-rule-matches` trigger condition below specifies an event rule
320 which matches any Linux system call entry event with a name starting
325 $ lttng add-trigger --condition=event-rule-matches \
326 --type=syscall:entry \
327 --name='exec*' --action=notify
331 .Add an ``event rule matches'' trigger of which the action is to stop a recording session and then rotate it.
333 The `event-rule-matches` trigger condition below specifies an event rule
334 which matches any user space tracepoint event with a name starting with
335 `my_app:` and with a log level at least as severe as a warning.
337 The order of the option:--action options below is significant.
341 $ lttng add-trigger --condition=event-rule-matches \
342 --type=user --name='my_app:*' \
343 --log-level=TRACE_WARNING.. \
344 --action=stop-session my-session \
345 --action=rotate-session my-session
348 See man:lttng-concepts(7) to learn more about recording sessions and
352 .Add an ``event rule matches'' trigger with a specific name.
354 The `event-rule-matches` trigger condition below specifies an event rule
355 which matches events which LTTng creates from the `my-logger` Python
358 The added trigger is named `my-trigger`, a unique name for your Unix
361 See the option:--name option.
365 $ lttng add-trigger --name=my-trigger \
366 --condition=event-rule-matches \
367 --type=python --name=my-logger \
368 --action=snapshot-session my-session
372 .Add an ``event rule matches'' trigger as another Unix user.
374 The command line below adds a trigger as the `mireille` Unix user.
376 Your Unix user must be `root` to use the option:--owner-uid option.
378 The condition of the trigger specifies an event rule which matches LTTng
379 kernel tracepoint events with a name which starts with `sched`.
383 # lttng add-trigger --owner-uid=$(id --user mireille) \
384 --condition=event-rule-matches \
385 --type=kernel --name='sched*' \
390 .Add an ``event rule matches'' trigger with a notification action to be executed every 10{nbsp}times.
392 The `event-rule-matches` trigger condition below specifies an event rule
393 which matches all user space tracepoint events.
395 See the nloption:--rate-policy option above.
399 $ lttng add-trigger --condition=event-rule-matches \
400 --type=user --action=notify \
401 --rate-policy=every:10
405 .Add an ``event rule matches'' trigger with a recording session starting action to be executed a single time after 40{nbsp}times.
407 The `event-rule-matches` trigger condition below specifies an event rule
408 which matches any Linux system call event (entry and exit) of which the
409 `fd` event record field is less than{nbsp}3.
411 See the nloption:--rate-policy option above.
415 $ lttng add-trigger --condition=event-rule-matches \
416 --type=syscall --filter='fd < 3' \
417 --action=start-session my-session \
418 --rate-policy=once-after:40
423 include::common-footer.txt[]
429 man:lttng-list-triggers(1),
430 man:lttng-remove-trigger(1),
431 man:lttng-concepts(7)