Commit | Line | Data |
---|---|---|
a942557f SM |
1 | lttng-add-trigger(1) |
2 | ===================== | |
c3e68e71 | 3 | :revdate: 27 May 2020 |
a942557f SM |
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 | ||
d0a70fd5 | 39 | [[conditions]] |
a942557f SM |
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 | ||
c3e68e71 JR |
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 | ||
d0a70fd5 | 64 | [[actions]] |
a942557f SM |
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 | ||
c3e68e71 JR |
81 | Increment value: *incr-value* -s sess-name -m map-name --key KEY_FORMAT:: |
82 | This action causes the tracer to increment the value of a counter | |
83 | in a map. If the map is absent or disabled when the condition is met, | |
84 | nothing is done. | |
85 | ||
a942557f SM |
86 | Start session: *start-session* session-name:: |
87 | This action causes the LTTng session daemon to start 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 | Stop session: *stop-session* session-name:: | |
92 | This action causes the LTTng session daemon to stop tracing for the | |
93 | session with the given name. If no session with the given name exist | |
94 | at the time the condition is met, nothing is done. | |
95 | ||
96 | Rotate session: *rotate-session* session-name:: | |
97 | This action causes the LTTng session daemon to rotate the session | |
98 | with the given name. See man:lttng-rotate(1) for more information | |
99 | about the session rotation concept. If no session with the given | |
100 | name exist at the time the condition is met, nothing is done. | |
101 | ||
102 | Snapshot session: *snapshot-session* session-name:: | |
103 | This action causes the LTTng session daemon to take a snapshot of the | |
104 | session with the given name. See man:lttng-snapshot(1) for more | |
105 | information about the session snapshot concept. If no session with | |
106 | the given name exist at the time the condition is met, nothing is | |
107 | done. | |
108 | ||
c3e68e71 JR |
109 | |
110 | [[capture-expr]] | |
111 | Capture expression | |
112 | ~~~~~~~~~~~~~~~~~~ | |
113 | ||
114 | A capture expression can be specified with the option:--capture option when | |
115 | creating a new on-event condition. If the capture expression corresponds with an | |
116 | event's field when tracing, the runtime dynamic value corresponding to the | |
117 | capture expression is captured. | |
118 | ||
119 | NOTE: Make sure to **single-quote** the capture expression when running | |
120 | the command from a shell, as capture expressions typically include | |
121 | characters having a special meaning for most shells. | |
122 | ||
123 | * Supported field types: | |
124 | - integer, | |
125 | - unsigned integer, | |
126 | - floating point value, | |
127 | - fixed-size array of integers, | |
128 | - variable-size array of integers (sequence), | |
129 | - enumeration, | |
130 | - text string, | |
131 | - element of any allowing previous type. | |
132 | ||
133 | * The dynamic value of an event field is captured by using its name as a C | |
134 | identifier. | |
135 | + | |
136 | The square bracket notation is available, like in the C | |
137 | language, to access array/sequence field. | |
138 | Only a constant, positive integer number can be used within square | |
139 | brackets. If the index is out of bounds, the capture expression | |
140 | evaluates to `unavailable`. | |
141 | + | |
142 | An enumeration field's value is an integer. | |
143 | + | |
144 | When the capture's field does not exist, the capture expression | |
145 | evaluates to `unavailable`. | |
146 | + | |
147 | Examples: `my_field`, `target_cpu`, `seq[7]` | |
148 | ||
149 | * The dynamic value of a statically-known context field is captured by | |
150 | prefixing its name with `$ctx.`. See man:lttng-add-context(1) to get a list of | |
151 | available contexts. | |
152 | + | |
153 | When the expression's statically-known context field does not exist, | |
154 | the capture expression evaluates to `unavailable`. | |
155 | + | |
156 | Examples: `$ctx.prio`, `$ctx.preemptible`, | |
157 | `$ctx.perf:cpu:stalled-cycles-frontend`. | |
158 | + | |
159 | NOTE: The statically-known context field does NOT need to be added using the | |
160 | man:lttng-add-context(1) command. The statically-known context fields are | |
161 | always available in the context of triggers. | |
162 | ||
163 | * The dynamic value of an application-specific context field is captured by | |
164 | prefixing its name with `$app.` (follows the format used to add such a context | |
165 | field with the man:lttng-add-context(1) command). | |
166 | + | |
167 | When the expression's application-specific context field does not exist, | |
168 | the capture expression evaluates to `unavailable`. | |
169 | + | |
170 | Example: `$app.server:cur_user`. | |
171 | + | |
172 | NOTE: The application-specific context field does NOT need to be added using the | |
173 | man:lttng-add-context(1) command. The application-specific context fields fields | |
174 | are always available in the context of triggers. | |
175 | ||
176 | ||
a942557f SM |
177 | OPTIONS |
178 | ------- | |
179 | ||
d0a70fd5 SM |
180 | option:--condition:: |
181 | Define the condition for the trigger. See the | |
182 | <<conditions,CONDITIONS>> section for more details. | |
183 | ||
184 | option:--action:: | |
185 | Define an action for the trigger. See the <<actions,ACTIONS>> | |
186 | section for more details. | |
187 | ||
a942557f SM |
188 | option:--id='ID':: |
189 | Set the id of the trigger to 'ID'. If omitted, an id will | |
190 | automatically be assigned to the trigger by the session daemon. | |
191 | + | |
192 | If a trigger with the specified 'ID' already exists, the trigger | |
193 | creation will fail. | |
194 | ||
195 | option:--fire-every 'N':: | |
196 | Execute the trigger's actions every 'N' times the condition is met. | |
197 | ||
198 | option:--fire-once-after 'N':: | |
199 | Execute the trigger's actions once after 'N' times the condition is | |
200 | met, then never after that. | |
201 | ||
202 | include::common-cmd-help-options.txt[] | |
203 | ||
204 | ||
205 | include::common-cmd-footer.txt[] | |
206 | ||
207 | ||
208 | SEE ALSO | |
209 | -------- | |
210 | man:lttng-list-triggers(1), | |
211 | man:lttng-remove-trigger(1), | |
212 | man:lttng(1) |