7 lttng-enable-event - Create or enable LTTng event rules
12 Create or enable Linux kernel event rules:
15 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
16 [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall]
17 [option:--filter='EXPR'] [option:--session='SESSION']
18 [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
20 Create or enable an "all" Linux kernel event rule:
23 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
24 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
26 Create or enable application event rules:
29 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
30 (option:--userspace | option:--jul | option:--log4j | option:--python)
31 [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
32 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
33 [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...)
38 The `lttng enable-event` command can create a new event rule, or enable
39 one or more existing and disabled ones.
41 An event rule created by `lttng enable-event` is a set of conditions
42 that must be satisfied in order for an actual event to be emitted by
43 an LTTng tracer when the execution of an application or the Linux kernel
44 reaches an event source (tracepoint, system call, dynamic probe).
45 Event sources can be listed with the man:lttng-list(1) command.
47 The man:lttng-disable-event(1) command can be used to disable
50 Event rules are always assigned to a channel when they are created. If
51 the option:--channel option is omitted, a default channel named
52 `channel0` is used (and created automatically if it does not exist for
53 the specified domain in the selected tracing session).
55 If the option:--session option is omitted, the chosen channel is picked
56 from the current tracing session.
58 Events can be enabled while tracing is active
59 (use man:lttng-start(1) to make a tracing session active).
64 Four types of event sources are available in the Linux kernel tracing
65 domain (option:--kernel option):
67 Tracepoint (option:--tracepoint option; default)::
68 A Linux kernel tracepoint, that is, a static instrumentation point
69 placed in the kernel source code. Standard tracepoints are designed
70 and placed in the source code by developers and record useful
73 Dynamic probe (option:--probe option)::
74 A Linux kernel kprobe, that is, an instrumentation point placed
75 dynamically in the compiled kernel code. Dynamic probe events do not
76 record any payload field.
78 Function probe (option:--function option)::
79 A Linux kernel kretprobe, that is, two instrumentation points placed
80 dynamically where a function is entered and where it returns in the
81 compiled kernel code. Function probe events do not record any
84 System call (option:--syscall option)::
85 A Linux kernel system call. Two instrumentation points are
86 statically placed where a system call function is entered and where
87 it returns in the compiled kernel code. System call event sources
88 record useful payload fields.
90 The application tracing domains (option:--userspace, option:--jul,
91 option:--log4j, or option:--python options) only support tracepoints.
92 In the cases of the JUL, Apache log4j, and Python domains, the event
93 names correspond to _logger_ names.
96 Understanding event rule conditions
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98 When creating an event rule with `lttng enable-event`, conditions are
99 specified using options. The logical conjunction (logical AND) of all
100 those conditions must be true when an event source is reached by an
101 application or by the Linux kernel in order for an actual event
102 to be emitted by an LTTng tracer.
104 Any condition that is not explicitly specified on creation is considered
107 For example, consider the following commands:
111 $ lttng enable-event --userspace hello:world
112 $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
115 Here, two event rules are created. The first one has a single condition:
116 the tracepoint name must match `hello:world`. The second one has two
119 * The tracepoint name must match `hello:world`, _and_
120 * The tracepoint's defined log level must be at least as severe as
121 the `TRACE_INFO` level.
123 In this case, the second event rule is pointless because the first one
124 is more general: it does not care about the tracepoint's log level.
125 If an event source matching both event rules is reached by the
126 application's execution, only one event is emitted.
128 The available conditions for the Linux kernel domain are:
130 * Tracepoint/system call name ('EVENT' argument with
131 option:--tracepoint or option:--syscall options) or
132 dynamic probe/function name/address
133 (option:--probe or option:--function option's argument) which must
134 match event source's equivalent.
136 You can use `*` characters at any place in the tracepoint or system
137 call name as wildcards to match zero or more characters. To use a
138 literal `*` character, use :escwc:.
140 * Filter expression (option:--filter option) executed against the
141 dynamic values of event fields at execution time that must evaluate
142 to true. See the <<filter-syntax,Filter expression syntax>> section
143 below for more information.
145 The available conditions for the application domains are:
147 * Tracepoint name ('EVENT' with option:--tracepoint option) which must
148 match event source's equivalent.
150 You can use `*` characters at any place in the tracepoint name as
151 wildcards to match zero or more characters. To use a literal `*`
152 character, use :escwc:. When you create an event rule with a tracepoint
153 name containing a wildcard, you can exclude specific tracepoint names
154 from the match with the option:--exclude option.
156 * Filter expression (option:--filter option) executed against the
157 dynamic values of event fields at execution time that must evaluate
158 to true. See the <<filter-syntax,Filter expression syntax>> section
159 below for more information.
160 * Event's log level that must be at least as severe as a given
161 log level (option:--loglevel option) or match exactly a given log
162 level (option:--loglevel-only option).
164 When using `lttng enable-event` with a set of conditions that does not
165 currently exist for the chosen tracing session, domain, and channel,
166 a new event rule is created. Otherwise, the existing event rule is
167 enabled if it is currently disabled
168 (see man:lttng-disable-event(1)).
170 The option:--all option can be used alongside the option:--tracepoint
171 or option:--syscall options. When this option is used, no 'EVENT'
172 argument must be specified. This option defines a single event rule
173 matching _all_ the possible events of a given tracing domain for the
174 chosen channel and tracing session. It is the equivalent of an 'EVENT'
175 argument named `*` (wildcard).
179 Filter expression syntax
180 ~~~~~~~~~~~~~~~~~~~~~~~~
181 A filter expression can be specified with the option:--filter option
182 when creating a new event rule. If the filter expression evaluates to
183 true when executed against the dynamic values of an event's fields when
184 tracing, the filtering condition passes.
186 NOTE: Make sure to **single-quote** the filter expression when running
187 the command from a shell, as filter expressions typically include
188 characters having a special meaning for most shells.
190 The filter expression syntax is very similar to C language conditional
191 expressions (expressions that can be evaluated by an `if` statement).
193 The following logical operators are supported:
195 [width="40%",options="header"]
196 |=====================================
198 | Logical negation (NOT) | `!a`
199 | Logical conjunction (AND) | `a && b`
200 | Logical disjunction (OR) | `a \|\| b`
201 |=====================================
203 The following comparison operators/relational operators are supported:
205 [width="40%",options="header"]
206 |====================================
208 | Equal to | `a == b`
209 | Not equal to | `a != b`
210 | Greater than | `a > b`
211 | Less than | `a < b`
212 | Greater than or equal to | `a >= b`
213 | Less than or equal to | `a <= b`
214 |====================================
216 The arithmetic and bitwise operators are :not: supported.
218 The precedence table of the operators above is the same as the one of
219 the C language. Parentheses are supported to bypass this.
221 The dynamic value of an event field is read by using its name as a C
224 The dynamic value of a statically-known context field is read by
225 prefixing its name with `$ctx.`. Statically-known context fields are
226 context fields added to channels without the `$app.` prefix using the
227 man:lttng-add-context(1) command. `$ctx.cpu_id` is also available as the
228 ID of the CPU which emits the event.
230 The dynamic value of an application-specific context field is read by
231 prefixing its name with `$app.` (follows the format used to add such a
232 context field with the man:lttng-add-context(1) command).
234 When a comparison includes a non existent event field, the whole filter
235 expression evaluates to false (the event is discarded).
237 C integer and floating point number constants are supported, as well as
238 literal strings between double quotes (`"`). You can use `*` characters
239 at any place in a literal string as wildcards to match zero or more
240 characters. To use a literal `*` character, use :escwc:.
242 LTTng-UST enumeration fields can be compared to integer values (fields
245 NOTE: Although it is possible to filter the process ID of an event when
246 the `pid` context has been added to its channel using, for example,
247 `$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
248 which is much more efficient (see man:lttng-track(1)).
252 ----------------------------
253 msg_id == 23 && size >= 2048
254 ----------------------------
256 -------------------------------------------------
257 $ctx.procname == "lttng*" && (!flag || poel < 34)
258 -------------------------------------------------
260 ---------------------------------------------------------
261 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
262 ---------------------------------------------------------
264 ---------------------------------------
265 $ctx.cpu_id == 2 && filename != "*.log"
266 ---------------------------------------
272 Tracepoints and log statements in applications have an attached log
273 level. Application event rules can contain a _log level_ condition.
275 With the option:--loglevel option, the event source's log level must
276 be at least as severe as the option's argument. With the
277 option:--loglevel-only option, the event source's log level must match
278 the option's argument.
280 The available log levels are:
282 User space domain (option:--userspace option)::
283 Shortcuts such as `system` are allowed.
289 * `TRACE_WARNING` (4)
292 * `TRACE_DEBUG_SYSTEM` (7)
293 * `TRACE_DEBUG_PROGRAM` (8)
294 * `TRACE_DEBUG_PROCESS` (9)
295 * `TRACE_DEBUG_MODULE` (10)
296 * `TRACE_DEBUG_UNIT` (11)
297 * `TRACE_DEBUG_FUNCTION` (12)
298 * `TRACE_DEBUG_LINE` (13)
301 `java.util.logging` domain (option:--jul option)::
302 Shortcuts such as `severe` are allowed.
304 * `JUL_OFF` (`INT32_MAX`)
305 * `JUL_SEVERE` (1000)
306 * `JUL_WARNING` (900)
312 * `JUL_ALL` (`INT32_MIN`)
314 Apache log4j domain (option:--log4j option)::
315 Shortcuts such as `severe` are allowed.
317 * `LOG4J_OFF` (`INT32_MAX`)
318 * `LOG4J_FATAL` (50000)
319 * `LOG4J_ERROR` (40000)
320 * `LOG4J_WARN` (30000)
321 * `LOG4J_INFO` (20000)
322 * `LOG4J_DEBUG` (10000)
323 * `LOG4J_TRACE` (5000)
324 * `LOG4J_ALL` (`INT32_MIN`)
326 Python domain (option:--python option)::
327 Shortcuts such as `critical` are allowed.
329 * `PYTHON_CRITICAL` (50)
330 * `PYTHON_ERROR` (40)
331 * `PYTHON_WARNING` (30)
333 * `PYTHON_DEBUG` (10)
334 * `PYTHON_NOTSET` (0)
337 include::common-cmd-options-head.txt[]
344 option:-j, option:--jul::
345 Create or enable event rules in the `java.util.logging`
348 option:-k, option:--kernel::
349 Create or enable event rules in the Linux kernel domain.
351 option:-l, option:--log4j::
352 Create or enable event rules in the Apache log4j domain.
354 option:-p, option:--python::
355 Create or enable event rules in the Python domain.
357 option:-u, option:--userspace::
358 Create or enable event rules in the user space domain.
363 option:-c 'CHANNEL', option:--channel='CHANNEL'::
364 Create or enable event rules in the channel named 'CHANNEL' instead
365 of the default channel name `channel0`.
367 option:-s 'SESSION', option:--session='SESSION'::
368 Create or enable event rules in the tracing session named 'SESSION'
369 instead of the current tracing session.
376 option:--function='SOURCE'::
377 Linux kernel kretprobe. Only available with the option:--kernel
378 domain option. 'SOURCE' is one of:
380 * Function address (`0x` prefix supported)
382 * Function symbol and offset (`SYMBOL+OFFSET` format)
384 option:--probe='SOURCE'::
385 Linux kernel kprobe. Only available with the option:--kernel
386 domain option. 'SOURCE' is one of:
388 * Address (`0x` prefix supported)
390 * Symbol and offset (`SYMBOL+OFFSET` format)
393 Linux kernel system call. Only available with the option:--kernel
396 option:--tracepoint::
397 Linux kernel or application tracepoint (default).
404 option:--loglevel='LOGLEVEL'::
405 Add log level condition to the event rule: the event source's
406 defined log level must be at least as severe as 'LOGLEVEL'.
407 See the <<log-levels,Log levels>> section above for the available
408 log levels. Only available with application domains.
410 option:--loglevel-only='LOGLEVEL'::
411 Add log level condition to the event rule: the event source's
412 defined log level must match 'LOGLEVEL'. See the
413 <<log-levels,Log levels>> section above for the available log
414 levels. Only available with application domains.
417 Filtering and exclusion
418 ~~~~~~~~~~~~~~~~~~~~~~~
419 option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
420 Exclude events named 'EVENT' from the event rule. This option
421 can be used when the command's 'EVENT' argument contains at least
422 one wildcard star (`*`) to exclude specific names. 'EVENT' can also
423 contain wildcard stars. To use a
424 literal `,` character, use :esccomma:.
425 Only available with the option:--userspace domain.
427 option:-f 'EXPR', option:--filter='EXPR'::
428 Add filter expression condition to the event rule. Expression 'EXPR'
429 must evaluate to true when executed against the dynamic values of
430 event fields. See the <<filter-syntax,Filter expression syntax>>
431 section above for more information.
436 option:-a, option:--all::
437 Equivalent to an 'EVENT' argument named `*` (wildcard) when also
438 using the option:--tracepoint (default) or option:--syscall option.
441 include::common-cmd-help-options.txt[]
444 include::common-cmd-footer.txt[]
449 man:lttng-disable-event(1),