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