add-trigger: rename --fire-* to --rate-policy=*:value
[lttng-tools.git] / doc / man / lttng-add-trigger.1.txt
1 lttng-add-trigger(1)
2 =====================
3 :revdate: 27 May 2020
4
5
6 NAME
7 ----
8 lttng-add-trigger - Create LTTng triggers
9
10
11 SYNOPSIS
12 --------
13
14 [verse]
15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-trigger* [--id ID]
16 --condition CONDITION-NAME CONDITION-ARGS
17 --action ACTION-NAME ACTION-ARGS
18 [--action ACTION-NAME ACTION-ARGS]...
19
20
21 DESCRIPTION
22 -----------
23
24 The `lttng add-trigger` command is used to create triggers. A
25 trigger is an association between a *condition* and one or more
26 *actions*. When the condition associated to a trigger is met, the
27 actions associated to that trigger are executed. The tracing does not
28 have to be active for the conditions to be met, and triggers are
29 independent from tracing sessions.
30
31 The syntax by which conditions and actions are specified is described
32 below.
33
34 [[conditions]]
35 Conditions
36 ~~~~~~~~~~
37
38 Conditions are specified with the `--condition` option, followed by a
39 condition name, and possibly some more arguments, depending on the
40 specific condition. There must be exactly one condition given in the
41 `lttng add-trigger` invocation.
42
43 The available conditions are:
44
45 Event rule: `on-event [event rule arguments]`::
46 This type of condition is met when the tracer encounters an event
47 matching the given even rule. The arguments describing the event
48 rule are the same as those describing the event rules of the
49 man:lttng-enable-event(1) command, with these exceptions:
50
51 - It is not possible to use filter operands that use values from
52 the context.
53
54 +
55 Fields to capture can be specified with the option:--capture option, followed by
56 a capture expression. Zero or more captures can be configured. See the
57 <<capture-expr, Capture expression>> section below for more information.
58
59 [[actions]]
60 Actions
61 ~~~~~~~
62
63 Actions are specified with the `--action` option, followed by an action
64 name, and possibly some more arguments, depending on the specific
65 action. There must be at least one action given in the
66 `lttng add-trigger` invocation.
67
68 The available actions are:
69
70 Notify: *notify*::
71 This action causes the LTTng session daemon to send a notification,
72 through its notification mechanism (see man:lttng-sessiond(8)).
73 Some details about the condition evaluation are sent along with the
74 notification.
75
76 Start session: *start-session* session-name::
77 This action causes the LTTng session daemon to start tracing for the
78 session with the given name. If no session with the given name exist
79 at the time the condition is met, nothing is done.
80
81 Stop session: *stop-session* session-name::
82 This action causes the LTTng session daemon to stop tracing for the
83 session with the given name. If no session with the given name exist
84 at the time the condition is met, nothing is done.
85
86 Rotate session: *rotate-session* session-name::
87 This action causes the LTTng session daemon to rotate the session
88 with the given name. See man:lttng-rotate(1) for more information
89 about the session rotation concept. If no session with the given
90 name exist at the time the condition is met, nothing is done.
91
92 Snapshot session: *snapshot-session* session-name::
93 This action causes the LTTng session daemon to take a snapshot of the
94 session with the given name. See man:lttng-snapshot(1) for more
95 information about the session snapshot concept. If no session with
96 the given name exist at the time the condition is met, nothing is
97 done.
98
99
100 [[capture-expr]]
101 Capture expression
102 ~~~~~~~~~~~~~~~~~~
103
104 A capture expression can be specified with the option:--capture option when
105 creating a new on-event condition. If the capture expression corresponds with an
106 event's field when tracing, the runtime dynamic value corresponding to the
107 capture expression is captured.
108
109 NOTE: Make sure to **single-quote** the capture expression when running
110 the command from a shell, as capture expressions typically include
111 characters having a special meaning for most shells.
112
113 * Supported field types:
114 - integer,
115 - unsigned integer,
116 - floating point value,
117 - fixed-size array of integers,
118 - variable-size array of integers (sequence),
119 - enumeration,
120 - text string,
121 - element of any allowing previous type.
122
123 * The dynamic value of an event field is captured by using its name as a C
124 identifier.
125 +
126 The square bracket notation is available, like in the C
127 language, to access array/sequence field.
128 Only a constant, positive integer number can be used within square
129 brackets. If the index is out of bounds, the capture expression
130 evaluates to `unavailable`.
131 +
132 An enumeration field's value is an integer.
133 +
134 When the capture's field does not exist, the capture expression
135 evaluates to `unavailable`.
136 +
137 Examples: `my_field`, `target_cpu`, `seq[7]`
138
139 * The dynamic value of a statically-known context field is captured by
140 prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of
141 available contexts.
142 +
143 When the expression's statically-known context field does not exist,
144 the capture expression evaluates to `unavailable`.
145 +
146 Examples: `$ctx.prio`, `$ctx.preemptible`,
147 `$ctx.perf:cpu:stalled-cycles-frontend`.
148 +
149 NOTE: The statically-known context field does NOT need to be added using the
150 man:lttng-add-context(1) command. The statically-known context fields are
151 always available in the context of triggers.
152
153 * The dynamic value of an application-specific context field is captured by
154 prefixing its name with `$app.` (follows the format used to add such a context
155 field with the man:lttng-add-context(1) command).
156 +
157 When the expression's application-specific context field does not exist,
158 the capture expression evaluates to `unavailable`.
159 +
160 Example: `$app.server:cur_user`.
161 +
162 NOTE: The application-specific context field does NOT need to be added using the
163 man:lttng-add-context(1) command. The application-specific context fields fields
164 are always available in the context of triggers.
165
166
167 OPTIONS
168 -------
169
170 option:--condition::
171 Define the condition for the trigger. See the
172 <<conditions,CONDITIONS>> section for more details.
173
174 option:--action::
175 Define an action for the trigger. See the <<actions,ACTIONS>>
176 section for more details.
177
178 option:--id='ID'::
179 Set the id of the trigger to 'ID'. If omitted, an id will
180 automatically be assigned to the trigger by the session daemon.
181 +
182 If a trigger with the specified 'ID' already exists, the trigger
183 creation will fail.
184
185 option:--fire-every 'N'::
186 Execute the trigger's actions every 'N' times the condition is met.
187
188 option:--fire-once-after 'N'::
189 Execute the trigger's actions once after 'N' times the condition is
190 met, then never after that.
191
192 include::common-cmd-help-options.txt[]
193
194
195 include::common-cmd-footer.txt[]
196
197
198 SEE ALSO
199 --------
200 man:lttng-list-triggers(1),
201 man:lttng-remove-trigger(1),
202 man:lttng(1)
This page took 0.047431 seconds and 4 git commands to generate.