lttng-enable-event(1): update the Filter expression section
[lttng-tools.git] / doc / man / lttng-enable-event.1.txt
1 lttng-enable-event(1)
2 =====================
3
4
5 NAME
6 ----
7 lttng-enable-event - Create or enable LTTng event rules
8
9
10 SYNOPSIS
11 --------
12 Create or enable Linux kernel event rules:
13
14 [verse]
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']...
19
20 Create or enable an "all" Linux kernel event rule:
21
22 [verse]
23 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
24 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
25
26 Create or enable application event rules:
27
28 [verse]
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']...)
34
35
36 DESCRIPTION
37 -----------
38 The `lttng enable-event` command can create a new event rule, or enable
39 one or more existing and disabled ones.
40
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.
46
47 The man:lttng-disable-event(1) command can be used to disable
48 existing event rules.
49
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).
54
55 If the option:--session option is omitted, the chosen channel is picked
56 from the current tracing session.
57
58 Events can be enabled while tracing is active
59 (use man:lttng-start(1) to make a tracing session active).
60
61
62 Event source types
63 ~~~~~~~~~~~~~~~~~~
64 Four types of event sources are available in the Linux kernel tracing
65 domain (option:--kernel option):
66
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
71 payload fields.
72
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.
77
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
82 payload field.
83
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.
89
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.
94
95
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.
103
104 Any condition that is not explicitly specified on creation is considered
105 a _don't care_.
106
107 For example, consider the following commands:
108
109 [role="term"]
110 ----
111 $ lttng enable-event --userspace hello:world
112 $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
113 ----
114
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
117 conditions:
118
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.
122
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.
127
128 The available conditions for the Linux kernel domain are:
129
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.
135 +
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:.
139
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-expr,Filter expression>> section
143 below for more information.
144
145 The available conditions for the application domains are:
146
147 * Tracepoint name ('EVENT' with option:--tracepoint option) which must
148 match event source's equivalent.
149 +
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.
155
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-expr,Filter expression>> 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).
163
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)).
169
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).
176
177
178 [[filter-expr]]
179 Filter expression
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
183 to true when executed against the dynamic values of an event's fields
184 when tracing, the filtering condition passes.
185
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.
189
190 The filter expression syntax is similar to C language conditional
191 expressions (expressions that can be evaluated by an `if` statement),
192 albeit with a few differences:
193
194 * C integer and floating point number constants are supported, as well
195 as literal strings between double quotes (`"`). You can use `*`
196 characters at any place in a literal string as wildcards to match zero
197 or more characters. To use a literal `*` character, use :escwc:.
198 +
199 Examples: `32`, `-0x17`, `0755`, `12.34`,
200 +"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`.
201
202 * The dynamic value of an event field is read by using its name as a C
203 identifier.
204 +
205 The dot and square bracket notations are available, like in the C
206 language, to access nested structure and array/sequence fields.
207 Only a constant, positive integer number can be used within square
208 brackets. If the index is out of bounds, the whole filter expression
209 evaluates to false (the event is discarded).
210 +
211 An enumeration field's value is an integer.
212 +
213 When the expression's field does not exist, the whole filter expression
214 evaluates to false.
215 +
216 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
217
218 * The dynamic value of a statically-known context field is read by
219 prefixing its name with `$ctx.`. Statically-known context fields are
220 context fields added to channels without the `$app.` prefix using the
221 man:lttng-add-context(1) command.
222 +
223 When the expression's statically-known context field does not exist,
224 the whole filter expression evaluates to false.
225 +
226 Examples: `$ctx.prio`, `$ctx.preemptible`,
227 `$ctx.perf:cpu:stalled-cycles-frontend`.
228
229 * The dynamic value of an application-specific context field is read by
230 prefixing its name with `$app.` (follows the format used to add such a
231 context field with the man:lttng-add-context(1) command).
232 +
233 When the expression's application-specific context field does not exist,
234 the whole filter expression evaluates to false.
235 +
236 Example: `$app.server:cur_user`.
237
238 The following precedence table shows the operators which are supported
239 in a filter expression. In this table, the highest precedence is 1.
240 Parentheses are supported to bypass the default order.
241
242 IMPORTANT: Unlike the C language, the `lttng enable-event` filter
243 expression syntax's bitwise AND and OR operators (`&` and `|`) take
244 precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and
245 `!=`). This means the filter expression `2 & 2 == 2` is true while the
246 equivalent C expression is false.
247
248 [options="header"]
249 |===
250 |Precedence |Operator |Description |Associativity
251 |1 |`-` |Unary minus |Right-to-left
252 |1 |`+` |Unary plus |Right-to-left
253 |1 |`!` |Logical NOT |Right-to-left
254 |1 |`~` |Bitwise NOT |Right-to-left
255 |2 |`<<` |Bitwise left shift |Left-to-right
256 |2 |`>>` |Bitwise right shift |Left-to-right
257 |3 |`&` |Bitwise AND |Left-to-right
258 |4 |`^` |Bitwise XOR |Left-to-right
259 |5 |`\|` |Bitwise OR |Left-to-right
260 |6 |`<` |Less than |Left-to-right
261 |6 |`<=` |Less than or equal to |Left-to-right
262 |6 |`>` |Greater than |Left-to-right
263 |6 |`>=` |Greater than or equal to |Left-to-right
264 |7 |`==` |Equal to |Left-to-right
265 |7 |`!=` |Not equal to |Left-to-right
266 |8 |`&&` |Logical AND |Left-to-right
267 |9 |`\|\|` |Logical OR |Left-to-right
268 |===
269
270 The arithmetic operators are :not: supported.
271
272 All integer constants and fields are first casted to signed 64-bit
273 integers. The representation of negative integers is two's complement.
274 This means that, for example, the signed 8-bit integer field 0xff (-1)
275 becomes 0xffffffffffffffff (still -1) once casted.
276
277 Before a bitwise operator is applied, all its operands are casted to
278 unsigned 64-bit integers, and the result is casted back to a signed
279 64-bit integer. For the bitwise NOT operator, it is the equivalent of
280 this C expression:
281
282 [source,c]
283 ----
284 (int64_t) ~((uint64_t) val)
285 ----
286
287 For the binary bitwise operators, it is the equivalent of those C
288 expressions:
289
290 [source,c]
291 ----
292 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
293 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
294 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
295 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
296 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
297 ----
298
299 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
300 not in the [0,{nbsp}63] range, the whole filter expression evaluates to
301 false.
302
303 NOTE: Although it is possible to filter the process ID of an event when
304 the `pid` context has been added to its channel using, for example,
305 `$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
306 which is much more efficient (see man:lttng-track(1)).
307
308 Filter expression examples:
309
310 ----------------------------
311 msg_id == 23 && size >= 2048
312 ----------------------------
313
314 -------------------------------------------------
315 $ctx.procname == "lttng*" && (!flag || poel < 34)
316 -------------------------------------------------
317
318 ---------------------------------------------------------
319 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
320 ---------------------------------------------------------
321
322 ---------------------------------------
323 $ctx.cpu_id == 2 && filename != "*.log"
324 ---------------------------------------
325
326 ------------------------------------------------
327 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
328 ------------------------------------------------
329
330
331 [[log-levels]]
332 Log levels
333 ~~~~~~~~~~
334 Tracepoints and log statements in applications have an attached log
335 level. Application event rules can contain a _log level_ condition.
336
337 With the option:--loglevel option, the event source's log level must
338 be at least as severe as the option's argument. With the
339 option:--loglevel-only option, the event source's log level must match
340 the option's argument.
341
342 The available log levels are:
343
344 User space domain (option:--userspace option)::
345 Shortcuts such as `system` are allowed.
346 +
347 * `TRACE_EMERG` (0)
348 * `TRACE_ALERT` (1)
349 * `TRACE_CRIT` (2)
350 * `TRACE_ERR` (3)
351 * `TRACE_WARNING` (4)
352 * `TRACE_NOTICE` (5)
353 * `TRACE_INFO` (6)
354 * `TRACE_DEBUG_SYSTEM` (7)
355 * `TRACE_DEBUG_PROGRAM` (8)
356 * `TRACE_DEBUG_PROCESS` (9)
357 * `TRACE_DEBUG_MODULE` (10)
358 * `TRACE_DEBUG_UNIT` (11)
359 * `TRACE_DEBUG_FUNCTION` (12)
360 * `TRACE_DEBUG_LINE` (13)
361 * `TRACE_DEBUG` (14)
362
363 `java.util.logging` domain (option:--jul option)::
364 Shortcuts such as `severe` are allowed.
365 +
366 * `JUL_OFF` (`INT32_MAX`)
367 * `JUL_SEVERE` (1000)
368 * `JUL_WARNING` (900)
369 * `JUL_INFO` (800)
370 * `JUL_CONFIG` (700)
371 * `JUL_FINE` (500)
372 * `JUL_FINER` (400)
373 * `JUL_FINEST` (300)
374 * `JUL_ALL` (`INT32_MIN`)
375
376 Apache log4j domain (option:--log4j option)::
377 Shortcuts such as `severe` are allowed.
378 +
379 * `LOG4J_OFF` (`INT32_MAX`)
380 * `LOG4J_FATAL` (50000)
381 * `LOG4J_ERROR` (40000)
382 * `LOG4J_WARN` (30000)
383 * `LOG4J_INFO` (20000)
384 * `LOG4J_DEBUG` (10000)
385 * `LOG4J_TRACE` (5000)
386 * `LOG4J_ALL` (`INT32_MIN`)
387
388 Python domain (option:--python option)::
389 Shortcuts such as `critical` are allowed.
390 +
391 * `PYTHON_CRITICAL` (50)
392 * `PYTHON_ERROR` (40)
393 * `PYTHON_WARNING` (30)
394 * `PYTHON_INFO` (20)
395 * `PYTHON_DEBUG` (10)
396 * `PYTHON_NOTSET` (0)
397
398
399 include::common-cmd-options-head.txt[]
400
401
402 Domain
403 ~~~~~~
404 One of:
405
406 option:-j, option:--jul::
407 Create or enable event rules in the `java.util.logging`
408 (JUL) domain.
409
410 option:-k, option:--kernel::
411 Create or enable event rules in the Linux kernel domain.
412
413 option:-l, option:--log4j::
414 Create or enable event rules in the Apache log4j domain.
415
416 option:-p, option:--python::
417 Create or enable event rules in the Python domain.
418
419 option:-u, option:--userspace::
420 Create or enable event rules in the user space domain.
421
422
423 Target
424 ~~~~~~
425 option:-c 'CHANNEL', option:--channel='CHANNEL'::
426 Create or enable event rules in the channel named 'CHANNEL' instead
427 of the default channel name `channel0`.
428
429 option:-s 'SESSION', option:--session='SESSION'::
430 Create or enable event rules in the tracing session named 'SESSION'
431 instead of the current tracing session.
432
433
434 Event source type
435 ~~~~~~~~~~~~~~~~~
436 One of:
437
438 option:--function='SOURCE'::
439 Linux kernel kretprobe. Only available with the option:--kernel
440 domain option. 'SOURCE' is one of:
441 +
442 * Function address (`0x` prefix supported)
443 * Function symbol
444 * Function symbol and offset (`SYMBOL+OFFSET` format)
445
446 option:--probe='SOURCE'::
447 Linux kernel kprobe. Only available with the option:--kernel
448 domain option. 'SOURCE' is one of:
449 +
450 * Address (`0x` prefix supported)
451 * Symbol
452 * Symbol and offset (`SYMBOL+OFFSET` format)
453
454 option:--syscall::
455 Linux kernel system call. Only available with the option:--kernel
456 domain option.
457
458 option:--tracepoint::
459 Linux kernel or application tracepoint (default).
460
461
462 Log level
463 ~~~~~~~~~
464 One of:
465
466 option:--loglevel='LOGLEVEL'::
467 Add log level condition to the event rule: the event source's
468 defined log level must be at least as severe as 'LOGLEVEL'.
469 See the <<log-levels,Log levels>> section above for the available
470 log levels. Only available with application domains.
471
472 option:--loglevel-only='LOGLEVEL'::
473 Add log level condition to the event rule: the event source's
474 defined log level must match 'LOGLEVEL'. See the
475 <<log-levels,Log levels>> section above for the available log
476 levels. Only available with application domains.
477
478
479 Filtering and exclusion
480 ~~~~~~~~~~~~~~~~~~~~~~~
481 option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
482 Exclude events named 'EVENT' from the event rule. This option
483 can be used when the command's 'EVENT' argument contains at least
484 one wildcard star (`*`) to exclude specific names. 'EVENT' can also
485 contain wildcard stars. To use a
486 literal `,` character, use :esccomma:.
487 Only available with the option:--userspace domain.
488
489 option:-f 'EXPR', option:--filter='EXPR'::
490 Add filter expression condition to the event rule. Expression 'EXPR'
491 must evaluate to true when executed against the dynamic values of
492 event fields. See the <<filter-expr,Filter expression>>
493 section above for more information.
494
495
496 Shortcuts
497 ~~~~~~~~~
498 option:-a, option:--all::
499 Equivalent to an 'EVENT' argument named `*` (wildcard) when also
500 using the option:--tracepoint (default) or option:--syscall option.
501
502
503 include::common-cmd-help-options.txt[]
504
505
506 include::common-cmd-footer.txt[]
507
508
509 SEE ALSO
510 --------
511 man:lttng-disable-event(1),
512 man:lttng(1)
This page took 0.062238 seconds and 4 git commands to generate.