3 :revdate: 23 April 2021
8 lttng-add-trigger - Add an LTTng trigger
14 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [option:--name='NAME'] [option:--owner-id='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 session daemon (see man:lttng-sessiond(8)).
23 A trigger is an association between a _condition_ and one or more
24 _actions_. When the condition of a trigger{nbsp}__T__ is satisfied,
25 LTTng requests to execute the actions of{nbsp}__T__. Depending on the
26 rate policy of an action, an execution request can become an actual
29 A trigger doesn't belong to a specific tracing session: it's global to
30 the session daemon. Within the session daemon, and for a given Unix
31 user, a trigger has a unique name. By default, the `add-trigger` command
32 automatically assigns a name to the added trigger. Use the option:--name
33 option to assign a specific name instead.
35 The `add-trigger` command adds a trigger for your Unix user. If your
36 Unix user is `root`, you can add the trigger as another user with the
37 option:--owner-id option.
39 Specify the condition of the trigger to add with a <<cond-spec,condition
40 specifier>> and its actions with one or more <<action-spec,action
41 specifiers>>. The order of the action specifiers is significant: LTTng
42 attempts to execute the actions of a trigger in order.
44 List the available triggers for your Unix user (or for all users if your
45 Unix user is `root`) with the man:lttng-list-triggers(1) command.
47 Remove an existing trigger with the man:lttng-remove-trigger(1) command.
56 option:--condition='CONDTYPE' ['CONDARGS']
58 A condition specifier is the option:--condition option, which specifies
59 the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE',
60 with zero or more arguments 'CONDARGS'.
62 The available condition types are:
64 [[er-matches-cond-spec]]`event-rule-matches`::
68 option:--condition=event-rule-matches [nloption:--capture='CDESCR']... 'ERSPEC'
71 An `event-rule-matches` condition is considered satisfied when the event
72 rule specified with 'ERSPEC' matches an event.
74 See man:lttng-event-rule(7) to learn how to specify an event rule
77 Capture event record and context fields with one or more
78 nloption:--capture options (see the <<capture-descr,Capture descriptor>>
79 section below to learn more). When an `event-rule-matches` condition
80 with capture descriptors is satisfied, the captured field values are
81 available in the evaluation object of the condition using the
82 liblttng-ctl C{nbsp}API.
84 IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the
85 `add-trigger` command from a shell, as capture descriptors can include
86 characters having a special meaning for most shells.
92 A capture descriptor is a textual expression which describes how to read
93 an event record or context field.
95 The argument of a nloption:--capture option, when using an
96 <<er-matches-cond-spec,``event rule matches'' condition specifier>>
97 (`event-rule-matches`), is a capture descriptor.
99 A capture descriptor expression is one of:
102 An event record field named 'NAME'.
104 The supported event record field types are:
108 * Enumeration (integral value)
109 * Floating point number
110 * Static array of integers
111 * Dynamic array (``sequence'') of integers
115 Examples: `my_field`, `target_cpu`, `ip`.
118 A statically-known context field named 'NAME'.
120 List the available statically-known context field names with
121 man:lttng-add-context(1).
123 Examples: `$ctx.prio`, `$ctx.preemptible`,
124 `$ctx.perf:cpu:stalled-cycles-frontend`.
126 ++$app.++__PROVIDER__++.++__NAME__::
127 An application-specific context field named 'NAME' from the
130 See man:lttng-add-context(1) to learn more about application-specific
133 Example: `$app.server:cur_user`.
135 __EXPR__++[++__INDEX__++]++::
136 The element at index 'INDEX' of the array field (static or dynamic)
137 identified by the expression 'EXPR'.
139 'INDEX' must be a constant, positive integral value.
141 Examples: `ip[3]`, `user_ids[15]`.
143 If, when an event rule matches, a given capture descriptor doesn't
144 identify an existing event or context field, then the captured value is
145 reported as being unavailable. This applies to:
147 * A nonexistent event record field name.
148 * A nonexistent statically-known context field name.
149 * A nonexistent application-specific context field name.
150 * An out-of-bounds array field index.
159 option:--action='ACTTYPE' ['ACTARGS']
161 An action specifier is the option:--action option, which specifies
162 the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero
163 or more arguments 'ACTARGS'.
165 The available action types are:
171 option:--action=notify [nloption:--rate-policy='POLICY']
174 Sends a notification through the notification
175 mechanism of the session daemon (see man:lttng-session(8)).
177 The session daemon sends details about the condition evaluation along
178 with the notification.
180 As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program
181 to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers).
183 See below for the nloption:--rate-policy option.
185 Start a tracing session::
189 option:--action=start-session 'SESSION' [nloption:--rate-policy='POLICY']
192 Starts the tracing session named 'SESSION' like man:lttng-start(1)
195 If no tracing session has the name 'SESSION' when LTTng is ready to
196 execute the action, LTTng does nothing.
198 See below for the nloption:--rate-policy option.
200 Stop a tracing session::
204 option:--action=stop-session 'SESSION' [nloption:--rate-policy='POLICY']
207 Stops the tracing session named 'SESSION' like man:lttng-stop(1) would.
209 If no tracing session has the name 'SESSION' when LTTng is ready to
210 execute the action, LTTng does nothing.
212 See below for the nloption:--rate-policy option.
214 Rotate a tracing session::
218 option:--action=rotate-session 'SESSION' [nloption:--rate-policy='POLICY']
221 Archives the current trace chunk of the tracing session named 'SESSION'
222 like man:lttng-rotate(1) would.
224 If no tracing session has the name 'SESSION' when LTTng is ready to
225 execute the action, LTTng does nothing.
227 See below for the nloption:--rate-policy option.
229 Take a tracing session snapshot::
233 option:--action=snapshot-session 'SESSION' [nloption:--rate-policy='POLICY']
236 Takes a snapshot of the tracing session named 'SESSION' like
237 man:lttng-snapshot(1) would.
239 When the condition of the trigger is satisfied, the tracing session
240 named 'SESSION', if any, must be a snapshot-mode tracing session
241 (see man:lttng-create(1)).
243 If no tracing session has the name 'SESSION' when LTTng is ready to
244 execute the action, LTTng does nothing.
246 See below for the nloption:--rate-policy option.
248 Common action options (as of LTTng{nbsp}{lttng_version}):
250 nloption:--rate-policy='POLICY'::
251 Set the rate policy of the action to 'POLICY'.
253 A trigger which ``fires'' (its condition is satisfied) leads to an
254 execution request for each of its actions, in order. An execution
255 request of a given action{nbsp}__A__ first increments the execution
256 request count{nbsp}__C__ of{nbsp}__A__. An execution request can then
257 become an actual execution when{nbsp}__C__ satisfies the rate policy
260 The default action rate policy is `every:1` (always execute{nbsp}__A__).
261 Use this option to specify another rate policy.
266 ++once-after:++__COUNT__::
267 Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'.
269 In other words, execute{nbsp}__A__ a single time after 'COUNT' execution
272 ++every:++__COUNT__::
273 Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'.
275 In other words, execute{nbsp}__A__ every 'COUNT' execution requests.
278 As of LTTng{nbsp}{lttng_version}, you can use this option with any
279 action type, but new action types in the future may not support it.
286 option:--name='NAME'::
287 Set the unique name of the trigger to add to 'NAME' instead of the
288 `add-trigger` command automatically assigning one.
290 option:--owner-id='UID'::
291 Add the trigger as the Unix user having the user ID 'UID'.
293 You may only use this option if your Unix user is `root`.
298 option:--condition='CONDTYPE'::
299 Introductory option for a condition specifier of type 'CONDTYPE'.
301 See the <<cond-spec,Condition specifier>> section above to learn more.
303 option:--action='ACTTYPE'::
304 Introductory option for an action specifier of type 'ACTTYPE'.
306 See the <<action-spec,Action specifier>> section above to learn more.
309 include::common-cmd-help-options.txt[]
312 include::common-cmd-footer.txt[]
318 man:lttng-list-triggers(1),
319 man:lttng-remove-trigger(1)