lttng-add-trigger(1)

1LTTNG-ADD-TRIGGER(1)             LTTng Manual             LTTNG-ADD-TRIGGER(1)
2
3
4

NAME

6       lttng-add-trigger - Add an LTTng trigger
7

SYNOPSIS

9       lttng [GENERAL OPTIONS] add-trigger [--name=NAME] [--owner-uid=UID]
10             --condition=CONDTYPE [CONDARGS]
11             --action=ACTTYPE [ACTARGS] [--action=ACTTYPE [ACTARGS]]...
12

DESCRIPTION

14       The lttng add-trigger command creates and adds an LTTng trigger to the
15       connected session daemon (see lttng-sessiond(8)).
16
17       See lttng-concepts(7) to learn more about LTTng triggers.
18
19       By default, the add-trigger command automatically assigns a name,
20       unique for a given session daemon and Unix user, to the added trigger.
21       Assign a custom name with the --name.
22
23       The add-trigger command adds a trigger for your Unix user. If your Unix
24       user is root, you may add the trigger as another user with the --owner-
25       uid option.
26
27       Specify the condition of the trigger to add with a condition specifier
28       and its actions with one or more action specifiers. The order of the
29       action specifiers is significant: LTTng attempts to execute the actions
30       of a firing trigger in this order.
31
32       See the “EXAMPLES” section below for usage examples.
33
34       List the triggers of your Unix user, or of all users if your Unix user
35       is root, with the lttng-list-triggers(1) command.
36
37       Remove a trigger with the lttng-remove-trigger(1) command.
38
39   Condition specifier
40       Synopsis:
41
42           --condition=CONDTYPE [CONDARGS]
43
44       A condition specifier is the --condition option, which specifies the
45       type of condition CONDTYPE, followed, depending on CONDTYPE, with zero
46       or more arguments CONDARGS.
47
48       The available condition types are:
49
50       event-rule-matches
51           Synopsis:
52
53               --condition=event-rule-matches [--capture=CDESCR]... ERSPEC
54
55           An event-rule-matches condition is considered satisfied when the
56           event rule specified with ERSPEC matches an event.
57
58           See lttng-event-rule(7) to learn how to specify an event rule
59           (ERSPEC part).
60
61           Capture event record and context fields with one or more --capture
62           options (see the “Capture descriptor” section below to learn more).
63           When an event-rule-matches condition with capture descriptors is
64           satisfied, the captured field values are available in the
65           evaluation object of the condition using the liblttng-ctl C API.
66
67           Important
68               Make sure to single-quote CDESCR when you run the add-trigger
69               command from a shell, as capture descriptors can include
70               characters having a special meaning for most shells.
71
72   Capture descriptor
73       A capture descriptor is a textual expression which describes how to
74       read an event record or context field.
75
76       The argument of a --capture option, when using an “event rule matches”
77       condition specifier (event-rule-matches), is a capture descriptor.
78
79       A capture descriptor expression is one of:
80
81       NAME
82           An event record field named NAME.
83
84           The supported event record field types are:
85
86           •   Integer
87
88           •   Enumeration (integral value)
89
90           •   Floating point number
91
92           •   Static array of integers
93
94           •   Dynamic array (“sequence”) of integers
95
96           •   Text string
97
98           Examples: my_field, target_cpu, ip.
99
100       $ctx.NAME
101           A statically-known context field named NAME.
102
103           List the available statically-known context field names with lttng-
104           add-context(1).
105
106           Examples: $ctx.prio, $ctx.preemptible, $ctx.perf:cpu:stalled-
107           cycles-frontend.
108
109       $app.PROVIDER.NAME
110           An application-specific context field named NAME from the provider
111           PROVIDER.
112
113           See lttng-add-context(1) to learn more about application-specific
114           context fields.
115
116           Example: $app.server:cur_user.
117
118       EXPR[INDEX]
119           The element at index INDEX of the array field (static or dynamic)
120           identified by the expression EXPR.
121
122           INDEX must be a constant, positive integral value.
123
124           Examples: ip[3], user_ids[15].
125
126       If, when an event rule matches, a given capture descriptor doesn’t
127       identify an existing event or context field, then the captured value is
128       reported as being unavailable. This applies to:
129
130       •   A nonexistent event record field name.
131
132       •   A nonexistent statically-known context field name.
133
134       •   A nonexistent application-specific context field name.
135
136       •   An out-of-bounds array field index.
137
138   Action specifier
139       Synopsis:
140
141           --action=ACTTYPE [ACTARGS]
142
143       An action specifier is the --action option, which specifies the type of
144       action ACTTYPE, followed, depending on ACTTYPE, with zero or more
145       arguments ACTARGS.
146
147       The available action types are:
148
149       Notify
150           Synopsis:
151
152               --action=notify [--rate-policy=POLICY]
153
154           Sends a notification through the notification mechanism of the
155           session daemon (see lttng-session(8)).
156
157           The session daemon sends details about the condition evaluation
158           along with the notification.
159
160           As of LTTng 2.13.4, you can write a C/C++ program to receive LTTng
161           notifications (see the liblttng-ctl C headers).
162
163           See below for the --rate-policy option.
164
165       Start a recording session
166           Synopsis:
167
168               --action=start-session SESSION [--rate-policy=POLICY]
169
170           Starts the recording session named SESSION like lttng-start(1)
171           would.
172
173           If no recording session has the name SESSION when LTTng is ready to
174           execute the action, LTTng does nothing.
175
176           See below for the --rate-policy option.
177
178       Stop a recording session
179           Synopsis:
180
181               --action=stop-session SESSION [--rate-policy=POLICY]
182
183           Stops the recording session named SESSION like lttng-stop(1) would.
184
185           If no recording session has the name SESSION when LTTng is ready to
186           execute the action, LTTng does nothing.
187
188           See below for the --rate-policy option.
189
190       Rotate a recording session
191           Synopsis:
192
193               --action=rotate-session SESSION [--rate-policy=POLICY]
194
195           Archives the current trace chunk of the recording session named
196           SESSION like lttng-rotate(1) would.
197
198           If no recording session has the name SESSION when LTTng is ready to
199           execute the action, LTTng does nothing.
200
201           See below for the --rate-policy option.
202
203       Take a recording session snapshot
204           Synopsis:
205
206               --action=snapshot-session SESSION [--rate-policy=POLICY]
207
208           Takes a snapshot of the recording session named SESSION like lttng-
209           snapshot(1) would.
210
211           When the condition of the trigger is satisfied, the recording
212           session named SESSION, if any, must be a snapshot-mode recording
213           session (see lttng-create(1)).
214
215           If no recording session has the name SESSION when LTTng is ready to
216           execute the action, LTTng does nothing.
217
218           See below for the --rate-policy option.
219
220       Common action options (as of LTTng 2.13.4):
221
222       --rate-policy=POLICY
223           Set the rate policy of the action to POLICY instead of every:1
224           (always execute).
225
226           A trigger which “fires” (its condition is satisfied) leads to an
227           execution request for each of its actions, in order. An execution
228           request of a given action A first increments the execution request
229           count C of A. An execution request can then become an actual
230           execution when C satisfies the rate policy of A.
231
232           POLICY is one of:
233
234           once-after:COUNT
235               Only execute A when C is equal to COUNT.
236
237               In other words, execute A a single time after COUNT execution
238               requests.
239
240           every:COUNT
241               Only execute A when C is a multiple of COUNT.
242
243               In other words, execute A every COUNT execution requests.
244
245           COUNT must be an integer greater than 0.
246
247           As of LTTng 2.13.4, you can use this option with any action type,
248           but new action types in the future may not support it.
249

OPTIONS

251   Identification
252       --name=NAME
253           Set the unique name of the trigger to add to NAME instead of the
254           add-trigger command automatically assigning one.
255
256       --owner-uid=UID
257           Add the trigger as the Unix user having the user ID UID.
258
259           You may only use this option if your Unix user is root.
260
261   Specifier
262       --condition=CONDTYPE
263           Introductory option for a condition specifier of type CONDTYPE.
264
265           See the “Condition specifier” section above to learn more.
266
267       --action=ACTTYPE
268           Introductory option for an action specifier of type ACTTYPE.
269
270           See the “Action specifier” section above to learn more.
271
272   Program information
273       -h, --help
274           Show help.
275
276           This option attempts to launch /usr/bin/man to view this manual
277           page. Override the manual pager path with the LTTNG_MAN_BIN_PATH
278           environment variable.
279
280       --list-options
281           List available command options and quit.
282

EXIT STATUS

284       0
285           Success
286
287       1
288           Command error
289
290       2
291           Undefined command
292
293       3
294           Fatal error
295
296       4
297           Command warning (something went wrong during the command)
298

ENVIRONMENT

300       LTTNG_ABORT_ON_ERROR
301           Set to 1 to abort the process after the first error is encountered.
302
303       LTTNG_HOME
304           Path to the LTTng home directory.
305
306           Defaults to $HOME.
307
308           Useful when the Unix user running the commands has a non-writable
309           home directory.
310
311       LTTNG_MAN_BIN_PATH
312           Absolute path to the manual pager to use to read the LTTng
313           command-line help (with lttng-help(1) or with the --help option)
314           instead of /usr/bin/man.
315
316       LTTNG_SESSION_CONFIG_XSD_PATH
317           Path to the directory containing the session.xsd recording session
318           configuration XML schema.
319
320       LTTNG_SESSIOND_PATH
321           Absolute path to the LTTng session daemon binary (see lttng-
322           sessiond(8)) to spawn from the lttng-create(1) command.
323
324           The --sessiond-path general option overrides this environment
325           variable.
326

FILES

328       $LTTNG_HOME/.lttngrc
329           Unix user’s LTTng runtime configuration.
330
331           This is where LTTng stores the name of the Unix user’s current
332           recording session between executions of lttng(1).  lttng-create(1)
333           and lttng-set-session(1) set the current recording session.
334
335       $LTTNG_HOME/lttng-traces
336           Default output directory of LTTng traces in local and snapshot
337           modes.
338
339           Override this path with the --output option of the lttng-create(1)
340           command.
341
342       $LTTNG_HOME/.lttng
343           Unix user’s LTTng runtime and configuration directory.
344
345       $LTTNG_HOME/.lttng/sessions
346           Default directory containing the Unix user’s saved recording
347           session configurations (see lttng-save(1) and lttng-load(1)).
348
349       /usr/local/etc/lttng/sessions
350           Directory containing the system-wide saved recording session
351           configurations (see lttng-save(1) and lttng-load(1)).
352
353       Note
354           $LTTNG_HOME defaults to the value of the HOME environment variable.
355

EXAMPLES

357       Example 1. Add an “event rule matches” trigger of which the action is
358       to send a notification.
359
360           The event-rule-matches trigger condition below specifies an event
361           rule which matches any Linux system call entry event with a name
362           starting with exec.
363
364               $ lttng add-trigger --condition=event-rule-matches \
365                                   --type=syscall:entry \
366                                   --name='exec*' --action=notify
367
368       Example 2. Add an “event rule matches” trigger of which the action is
369       to stop a recording session and then rotate it.
370
371           The event-rule-matches trigger condition below specifies an event
372           rule which matches any user space tracepoint event with a name
373           starting with my_app: and with a log level at least as severe as a
374           warning.
375
376           The order of the --action options below is significant.
377
378               $ lttng add-trigger --condition=event-rule-matches \
379                                   --type=user --name='my_app:*' \
380                                   --log-level=TRACE_WARNING.. \
381                                   --action=stop-session my-session \
382                                   --action=rotate-session my-session
383
384           See lttng-concepts(7) to learn more about recording sessions and
385           rotations.
386
387       Example 3. Add an “event rule matches” trigger with a specific name.
388
389           The event-rule-matches trigger condition below specifies an event
390           rule which matches events which LTTng creates from the my-logger
391           Python logger.
392
393           The added trigger is named my-trigger, a unique name for your Unix
394           user.
395
396           See the --name option.
397
398               $ lttng add-trigger --name=my-trigger \
399                                   --condition=event-rule-matches \
400                                   --type=python --name=my-logger \
401                                   --action=snapshot-session my-session
402
403       Example 4. Add an “event rule matches” trigger as another Unix user.
404
405           The command line below adds a trigger as the mireille Unix user.
406
407           Your Unix user must be root to use the --owner-uid option.
408
409           The condition of the trigger specifies an event rule which matches
410           LTTng kernel tracepoint events with a name which starts with sched.
411
412               # lttng add-trigger --owner-uid=$(id --user mireille) \
413                                   --condition=event-rule-matches \
414                                   --type=kernel --name='sched*' \
415                                   --action=notify
416
417       Example 5. Add an “event rule matches” trigger with a notification
418       action to be executed every 10 times.
419
420           The event-rule-matches trigger condition below specifies an event
421           rule which matches all user space tracepoint events.
422
423           See the --rate-policy option above.
424
425               $ lttng add-trigger --condition=event-rule-matches \
426                                   --type=user --action=notify \
427                                   --rate-policy=every:10
428
429       Example 6. Add an “event rule matches” trigger with a recording session
430       starting action to be executed a single time after 40 times.
431
432           The event-rule-matches trigger condition below specifies an event
433           rule which matches any Linux system call event (entry and exit) of
434           which the fd event record field is less than 3.
435
436           See the --rate-policy option above.
437
438               $ lttng add-trigger --condition=event-rule-matches \
439                                   --type=syscall --filter='fd < 3' \
440                                   --action=start-session my-session \
441                                   --rate-policy=once-after:40
442

RESOURCES

444       •   LTTng project website <https://lttng.org>
445
446       •   LTTng documentation <https://lttng.org/docs>
447
448       •   LTTng bug tracker <https://bugs.lttng.org>
449
450       •   Git repositories <https://git.lttng.org>
451
452       •   GitHub organization <https://github.com/lttng>
453
454       •   Continuous integration <https://ci.lttng.org/>
455
456       •   Mailing list <https://lists.lttng.org/> for support and
457           development: lttng-dev@lists.lttng.org
458
459       •   IRC channel <irc://irc.oftc.net/lttng>: #lttng on irc.oftc.net
460

COPYRIGHT

462       This program is part of the LTTng-tools project.
463
464       LTTng-tools is distributed under the GNU General Public License
465       version 2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>.
466       See the LICENSE <https://github.com/lttng/lttng-
467       tools/blob/master/LICENSE> file for details.
468

THANKS

470       Special thanks to Michel Dagenais and the DORSAL laboratory
471       <http://www.dorsal.polymtl.ca/> at École Polytechnique de Montréal for
472       the LTTng journey.
473
474       Also thanks to the Ericsson teams working on tracing which helped us
475       greatly with detailed bug reports and unusual test cases.
476