scope-exit: Clarify scope_exit noexcept requirement
[lttng-tools.git] / doc / man / lttng-add-trigger.1.txt
CommitLineData
a942557f 1lttng-add-trigger(1)
484b2a0c 2====================
e9711845 3:revdate: 14 June 2021
a942557f
SM
4
5
6NAME
7----
484b2a0c 8lttng-add-trigger - Add an LTTng trigger
a942557f
SM
9
10
11SYNOPSIS
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
18DESCRIPTION
19-----------
484b2a0c 20The `lttng add-trigger` command creates and adds an LTTng _trigger_ to
26f0c779 21the connected session daemon (see man:lttng-sessiond(8)).
484b2a0c 22
26f0c779 23See man:lttng-concepts(7) to learn more about LTTng triggers.
a942557f 24
26f0c779
PP
25By default, the `add-trigger` command automatically assigns a name,
26unique for a given session daemon and Unix user, to the added trigger.
27Assign a custom name with the option:--name.
a942557f 28
484b2a0c 29The `add-trigger` command adds a trigger for your Unix user. If your
26f0c779 30Unix user is `root`, you may add the trigger as another user with the
d938377c 31option:--owner-uid option.
a942557f 32
484b2a0c
PP
33Specify the condition of the trigger to add with a <<cond-spec,condition
34specifier>> and its actions with one or more <<action-spec,action
35specifiers>>. The order of the action specifiers is significant: LTTng
26f0c779 36attempts to execute the actions of a firing trigger in this order.
a942557f 37
da39b67c 38See the ``<<examples,EXAMPLES>>'' section below for usage examples.
d65a3957 39
26f0c779
PP
40List the triggers of your Unix user, or of all users if your
41Unix user is `root`, with the man:lttng-list-triggers(1) command.
a942557f 42
26f0c779 43Remove a trigger with the man:lttng-remove-trigger(1) command.
a942557f 44
a942557f 45
484b2a0c
PP
46[[cond-spec]]
47Condition specifier
48~~~~~~~~~~~~~~~~~~~
49Synopsis:
50
51[verse]
52option:--condition='CONDTYPE' ['CONDARGS']
a942557f 53
484b2a0c
PP
54A condition specifier is the option:--condition option, which specifies
55the type of condition 'CONDTYPE', followed, depending on 'CONDTYPE',
56with zero or more arguments 'CONDARGS'.
57
58The available condition types are:
59
60[[er-matches-cond-spec]]`event-rule-matches`::
61 Synopsis:
62+
63[verse]
26f0c779 64option:--condition=**event-rule-matches** [nloption:--capture='CDESCR']... 'ERSPEC'
484b2a0c 65{nbsp}
943061bd 66+
484b2a0c
PP
67An `event-rule-matches` condition is considered satisfied when the event
68rule specified with 'ERSPEC' matches an event.
69+
70See man:lttng-event-rule(7) to learn how to specify an event rule
71('ERSPEC' part).
72+
73Capture event record and context fields with one or more
da39b67c
PP
74nloption:--capture options (see the ``<<capture-descr,Capture
75descriptor>>'' section below to learn more). When an
76`event-rule-matches` condition with capture descriptors is satisfied,
77the captured field values are available in the evaluation object of the
78condition using the liblttng-ctl C{nbsp}API.
484b2a0c
PP
79+
80IMPORTANT: Make sure to **single-quote** 'CDESCR' when you run the
81`add-trigger` command from a shell, as capture descriptors can include
82characters having a special meaning for most shells.
943061bd 83
a942557f 84
484b2a0c
PP
85[[capture-descr]]
86Capture descriptor
87~~~~~~~~~~~~~~~~~~
88A capture descriptor is a textual expression which describes how to read
89an event record or context field.
a942557f 90
484b2a0c
PP
91The 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.
a942557f 94
484b2a0c 95A capture descriptor expression is one of:
a942557f 96
484b2a0c
PP
97'NAME'::
98 An event record field named 'NAME'.
99+
100The supported event record field types are:
101+
102--
103* Integer
104* Enumeration (integral value)
105* Floating point number
106* Static array of integers
107* Dynamic array (``sequence'') of integers
108* Text string
109--
110+
111Examples: `my_field`, `target_cpu`, `ip`.
a942557f 112
484b2a0c
PP
113++$ctx.++__NAME__::
114 A statically-known context field named 'NAME'.
115+
116List the available statically-known context field names with
117man:lttng-add-context(1).
118+
119Examples: `$ctx.prio`, `$ctx.preemptible`,
120`$ctx.perf:cpu:stalled-cycles-frontend`.
121
122++$app.++__PROVIDER__++.++__NAME__::
123 An application-specific context field named 'NAME' from the
124 provider 'PROVIDER'.
125+
126See man:lttng-add-context(1) to learn more about application-specific
127context fields.
128+
129Example: `$app.server:cur_user`.
a942557f 130
484b2a0c
PP
131__EXPR__++[++__INDEX__++]++::
132 The element at index 'INDEX' of the array field (static or dynamic)
133 identified by the expression 'EXPR'.
134+
135'INDEX' must be a constant, positive integral value.
136+
137Examples: `ip[3]`, `user_ids[15]`.
a942557f 138
484b2a0c
PP
139If, when an event rule matches, a given capture descriptor doesn't
140identify an existing event or context field, then the captured value is
141reported as being unavailable. This applies to:
a942557f 142
484b2a0c
PP
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.
943061bd 147
943061bd 148
484b2a0c
PP
149[[action-spec]]
150Action specifier
151~~~~~~~~~~~~~~~~
152Synopsis:
943061bd 153
484b2a0c
PP
154[verse]
155option:--action='ACTTYPE' ['ACTARGS']
156
157An action specifier is the option:--action option, which specifies
158the type of action 'ACTTYPE', followed, depending on 'ACTTYPE', with zero
159or more arguments 'ACTARGS'.
160
161The available action types are:
162
163Notify::
164 Synopsis:
165+
166[verse]
26f0c779 167option:--action=**notify** [nloption:--rate-policy='POLICY']
484b2a0c
PP
168{nbsp}
169+
170Sends a notification through the notification
a968a9e0 171mechanism of the session daemon (see man:lttng-sessiond(8)).
484b2a0c
PP
172+
173The session daemon sends details about the condition evaluation along
174with the notification.
175+
176As of LTTng{nbsp}{lttng_version}, you can write a C/pass:[C++] program
177to receive LTTng notifications (see the liblttng-ctl C{nbsp}headers).
178+
179See below for the nloption:--rate-policy option.
943061bd 180
e9711845 181Start a recording session::
484b2a0c
PP
182 Synopsis:
183+
184[verse]
26f0c779 185option:--action=**start-session** 'SESSION' [nloption:--rate-policy='POLICY']
484b2a0c
PP
186{nbsp}
187+
e9711845 188Starts the recording session named 'SESSION' like man:lttng-start(1)
484b2a0c
PP
189would.
190+
e9711845 191If no recording session has the name 'SESSION' when LTTng is ready to
484b2a0c
PP
192execute the action, LTTng does nothing.
193+
194See below for the nloption:--rate-policy option.
943061bd 195
e9711845 196Stop a recording session::
484b2a0c 197 Synopsis:
943061bd 198+
484b2a0c 199[verse]
26f0c779 200option:--action=**stop-session** 'SESSION' [nloption:--rate-policy='POLICY']
484b2a0c 201{nbsp}
943061bd 202+
e9711845
PP
203Stops the recording session named 'SESSION' like man:lttng-stop(1)
204would.
943061bd 205+
e9711845 206If no recording session has the name 'SESSION' when LTTng is ready to
484b2a0c 207execute the action, LTTng does nothing.
943061bd 208+
484b2a0c 209See below for the nloption:--rate-policy option.
943061bd 210
e9711845 211Rotate a recording session::
484b2a0c
PP
212 Synopsis:
213+
214[verse]
26f0c779 215option:--action=**rotate-session** 'SESSION' [nloption:--rate-policy='POLICY']
484b2a0c 216{nbsp}
943061bd 217+
e9711845
PP
218Archives the current trace chunk of the recording session named
219'SESSION' like man:lttng-rotate(1) would.
943061bd 220+
e9711845 221If no recording session has the name 'SESSION' when LTTng is ready to
484b2a0c 222execute the action, LTTng does nothing.
943061bd 223+
484b2a0c 224See below for the nloption:--rate-policy option.
943061bd 225
e9711845 226Take a recording session snapshot::
484b2a0c 227 Synopsis:
943061bd 228+
484b2a0c 229[verse]
26f0c779 230option:--action=**snapshot-session** 'SESSION' [nloption:--rate-policy='POLICY']
484b2a0c 231{nbsp}
943061bd 232+
e9711845 233Takes a snapshot of the recording session named 'SESSION' like
484b2a0c
PP
234man:lttng-snapshot(1) would.
235+
e9711845
PP
236When the condition of the trigger is satisfied, the recording session
237named 'SESSION', if any, must be a snapshot-mode recording session
484b2a0c
PP
238(see man:lttng-create(1)).
239+
e9711845 240If no recording session has the name 'SESSION' when LTTng is ready to
484b2a0c
PP
241execute the action, LTTng does nothing.
242+
243See below for the nloption:--rate-policy option.
244
245Common action options (as of LTTng{nbsp}{lttng_version}):
246
247nloption:--rate-policy='POLICY'::
72d8cc10
PP
248 Set the rate policy of the action to 'POLICY' instead of
249 `every:1` (always execute).
484b2a0c
PP
250+
251A trigger which ``fires'' (its condition is satisfied) leads to an
252execution request for each of its actions, in order. An execution
253request of a given action{nbsp}__A__ first increments the execution
254request count{nbsp}__C__ of{nbsp}__A__. An execution request can then
255become an actual execution when{nbsp}__C__ satisfies the rate policy
256of{nbsp}__A__.
257+
484b2a0c
PP
258'POLICY' is one of:
259+
260--
261++once-after:++__COUNT__::
262 Only execute{nbsp}__A__ when{nbsp}__C__ is equal to 'COUNT'.
263+
264In other words, execute{nbsp}__A__ a single time after 'COUNT' execution
265requests.
266
267++every:++__COUNT__::
268 Only execute{nbsp}__A__ when{nbsp}__C__ is a multiple of 'COUNT'.
269+
270In other words, execute{nbsp}__A__ every 'COUNT' execution requests.
271--
272+
72d8cc10
PP
273'COUNT' must be an integer greater than{nbsp}0.
274+
484b2a0c
PP
275As of LTTng{nbsp}{lttng_version}, you can use this option with any
276action type, but new action types in the future may not support it.
943061bd
JR
277
278
a942557f
SM
279OPTIONS
280-------
484b2a0c
PP
281Identification
282~~~~~~~~~~~~~~
283option:--name='NAME'::
284 Set the unique name of the trigger to add to 'NAME' instead of the
285 `add-trigger` command automatically assigning one.
286
d938377c 287option:--owner-uid='UID'::
484b2a0c
PP
288 Add the trigger as the Unix user having the user ID 'UID'.
289+
290You may only use this option if your Unix user is `root`.
a942557f 291
d0a70fd5 292
484b2a0c
PP
293Specifier
294~~~~~~~~~
295option:--condition='CONDTYPE'::
296 Introductory option for a condition specifier of type 'CONDTYPE'.
a942557f 297+
da39b67c
PP
298See the ``<<cond-spec,Condition specifier>>'' section above to learn
299more.
a942557f 300
484b2a0c
PP
301option:--action='ACTTYPE'::
302 Introductory option for an action specifier of type 'ACTTYPE'.
303+
da39b67c
PP
304See the ``<<action-spec,Action specifier>>'' section above to learn
305more.
a942557f 306
a942557f 307
f5511eea 308include::common-lttng-cmd-help-options.txt[]
a942557f
SM
309
310
f5511eea
PP
311include::common-lttng-cmd-after-options.txt[]
312
313
473c70ca
PP
314[[examples]]
315EXAMPLES
316--------
317.Add an ``event rule matches'' trigger of which the action is to send a notification.
318====
319The `event-rule-matches` trigger condition below specifies an event rule
320which matches any Linux system call entry event with a name starting
321with `exec`.
322
323[role="term"]
324----
325$ lttng add-trigger --condition=event-rule-matches \
a55e08e0 326 --type=syscall:entry \
473c70ca
PP
327 --name='exec*' --action=notify
328----
329====
330
e9711845 331.Add an ``event rule matches'' trigger of which the action is to stop a recording session and then rotate it.
473c70ca
PP
332====
333The `event-rule-matches` trigger condition below specifies an event rule
334which 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.
336
337The order of the option:--action options below is significant.
338
339[role="term"]
340----
341$ lttng add-trigger --condition=event-rule-matches \
a55e08e0 342 --type=user --name='my_app:*' \
473c70ca
PP
343 --log-level=TRACE_WARNING.. \
344 --action=stop-session my-session \
345 --action=rotate-session my-session
346----
347
e9711845 348See man:lttng-concepts(7) to learn more about recording sessions and
473c70ca
PP
349rotations.
350====
351
352.Add an ``event rule matches'' trigger with a specific name.
353====
354The `event-rule-matches` trigger condition below specifies an event rule
355which matches events which LTTng creates from the `my-logger` Python
356logger.
357
358The added trigger is named `my-trigger`, a unique name for your Unix
359user.
360
361See the option:--name option.
362
363[role="term"]
364----
365$ lttng add-trigger --name=my-trigger \
366 --condition=event-rule-matches \
a55e08e0 367 --type=python --name=my-logger \
473c70ca
PP
368 --action=snapshot-session my-session
369----
370====
371
372.Add an ``event rule matches'' trigger as another Unix user.
373====
374The command line below adds a trigger as the `mireille` Unix user.
375
376Your Unix user must be `root` to use the option:--owner-uid option.
377
378The condition of the trigger specifies an event rule which matches LTTng
379kernel tracepoint events with a name which starts with `sched`.
380
381[role="term"]
382----
383# lttng add-trigger --owner-uid=$(id --user mireille) \
384 --condition=event-rule-matches \
a55e08e0 385 --type=kernel --name='sched*' \
473c70ca
PP
386 --action=notify
387----
388====
389
390.Add an ``event rule matches'' trigger with a notification action to be executed every 10{nbsp}times.
391====
392The `event-rule-matches` trigger condition below specifies an event rule
393which matches all user space tracepoint events.
394
395See the nloption:--rate-policy option above.
396
397[role="term"]
398----
399$ lttng add-trigger --condition=event-rule-matches \
a55e08e0 400 --type=user --action=notify \
473c70ca
PP
401 --rate-policy=every:10
402----
403====
404
e9711845 405.Add an ``event rule matches'' trigger with a recording session starting action to be executed a single time after 40{nbsp}times.
473c70ca
PP
406====
407The `event-rule-matches` trigger condition below specifies an event rule
408which matches any Linux system call event (entry and exit) of which the
409`fd` event record field is less than{nbsp}3.
410
411See the nloption:--rate-policy option above.
412
413[role="term"]
414----
415$ lttng add-trigger --condition=event-rule-matches \
a55e08e0 416 --type=syscall --filter='fd < 3' \
473c70ca
PP
417 --action=start-session my-session \
418 --rate-policy=once-after:40
419----
420====
421
422
f5511eea 423include::common-footer.txt[]
a942557f
SM
424
425
426SEE ALSO
427--------
484b2a0c 428man:lttng(1),
a942557f 429man:lttng-list-triggers(1),
af1c4164
PP
430man:lttng-remove-trigger(1),
431man:lttng-concepts(7)
This page took 0.058494 seconds and 5 git commands to generate.