Docs: Add lttng-add-trigger man page
[lttng-tools.git] / doc / man / lttng-add-trigger.1.txt
CommitLineData
a942557f
SM
1lttng-add-trigger(1)
2=====================
3:revdate: 17 January 2020
4
5
6NAME
7----
8lttng-add-trigger - Create LTTng triggers
9
10
11SYNOPSIS
12--------
13
14[verse]
15*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
16 [--fire-every N] [--fire-once-after N]
17 --condition CONDITION-NAME CONDITION-ARGS
18 --action ACTION-NAME ACTION-ARGS
19 [--action ACTION-NAME ACTION-ARGS]...
20
21
22DESCRIPTION
23-----------
24
25The `lttng add-trigger` command is used to create triggers. A
26trigger is an association between a *condition* and one or more
27*actions*. When the condition associated to a trigger is met, the
28actions associated to that trigger are executed. The tracing does not
29have to be active for the conditions to be met, and triggers are
30independent from tracing sessions.
31
32By default, a trigger fires every time its condition is met. The
33'--fire-every' and '--fire-once-after' options can be used to change
34this mode.
35
36The syntax by which conditions and actions are specified is described
37below.
38
39Conditions
40~~~~~~~~~~
41
42Conditions are specified with the `--condition` option, followed by a
43condition name, and possibly some more arguments, depending on the
44specific condition. There must be exactly one condition given in the
45`lttng add-trigger` invocation.
46
47The available conditions are:
48
49Event rule: `on-event [event rule arguments]`::
50 This type of condition is met when the tracer encounters an event
51 matching the given even rule. The arguments describing the event
52 rule are the same as those describing the event rules of the
53 man:lttng-enable-event(1) command, with these exceptions:
54
55 - It is not possible to use filter operands that use values from
56 the context.
57
58Actions
59~~~~~~~
60
61Actions are specified with the `--action` option, followed by an action
62name, and possibly some more arguments, depending on the specific
63action. There must be at least one action given in the
64`lttng add-trigger` invocation.
65
66The available actions are:
67
68Notify: *notify*::
69 This action causes the LTTng session daemon to send a notification,
70 through its notification mechanism (see man:lttng-sessiond(8)).
71 Some details about the condition evaluation are sent along with the
72 notification.
73
74Start session: *start-session* session-name::
75 This action causes the LTTng session daemon to start tracing for the
76 session with the given name. If no session with the given name exist
77 at the time the condition is met, nothing is done.
78
79Stop session: *stop-session* session-name::
80 This action causes the LTTng session daemon to stop tracing for the
81 session with the given name. If no session with the given name exist
82 at the time the condition is met, nothing is done.
83
84Rotate session: *rotate-session* session-name::
85 This action causes the LTTng session daemon to rotate the session
86 with the given name. See man:lttng-rotate(1) for more information
87 about the session rotation concept. If no session with the given
88 name exist at the time the condition is met, nothing is done.
89
90Snapshot session: *snapshot-session* session-name::
91 This action causes the LTTng session daemon to take a snapshot of the
92 session with the given name. See man:lttng-snapshot(1) for more
93 information about the session snapshot concept. If no session with
94 the given name exist at the time the condition is met, nothing is
95 done.
96
97OPTIONS
98-------
99
100option:--id='ID'::
101 Set the id of the trigger to 'ID'. If omitted, an id will
102 automatically be assigned to the trigger by the session daemon.
103+
104If a trigger with the specified 'ID' already exists, the trigger
105creation will fail.
106
107option:--fire-every 'N'::
108 Execute the trigger's actions every 'N' times the condition is met.
109
110option:--fire-once-after 'N'::
111 Execute the trigger's actions once after 'N' times the condition is
112 met, then never after that.
113
114include::common-cmd-help-options.txt[]
115
116
117include::common-cmd-footer.txt[]
118
119
120SEE ALSO
121--------
122man:lttng-list-triggers(1),
123man:lttng-remove-trigger(1),
124man:lttng(1)
This page took 0.038042 seconds and 4 git commands to generate.