Commit | Line | Data |
---|---|---|
a942557f SM |
1 | lttng-add-trigger(1) |
2 | ===================== | |
943061bd | 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] | |
a942557f SM |
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 | ||
a942557f SM |
31 | The syntax by which conditions and actions are specified is described |
32 | below. | |
33 | ||
d0a70fd5 | 34 | [[conditions]] |
a942557f SM |
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 | ||
665db063 | 45 | Event rule: `event-rule-matches [event rule arguments]`:: |
a942557f | 46 | This type of condition is met when the tracer encounters an event |
665db063 | 47 | matching the given event rule. The arguments describing the event |
a942557f SM |
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 | ||
943061bd JR |
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 | ||
d0a70fd5 | 59 | [[actions]] |
a942557f SM |
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 | ||
943061bd JR |
99 | |
100 | [[capture-expr]] | |
101 | Capture expression | |
102 | ~~~~~~~~~~~~~~~~~~ | |
103 | ||
104 | A capture expression can be specified with the option:--capture option when | |
665db063 SM |
105 | creating a new event-rule-matches condition. If the capture expression |
106 | corresponds with an event's field when tracing, the runtime dynamic value | |
107 | corresponding to the capture expression is captured. | |
943061bd JR |
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 | ||
a942557f SM |
167 | OPTIONS |
168 | ------- | |
169 | ||
d0a70fd5 SM |
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 | ||
a942557f SM |
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) |