18df67d465acd9fafe5faff4763e107f9ee134f6
[lttng-tools.git] / doc / man / lttng-enable-event.1.txt
1 lttng-enable-event(1)
2 =====================
3 :revdate: 4 April 2019
4
5
6 NAME
7 ----
8 lttng-enable-event - Create or enable LTTng event rules
9
10
11 SYNOPSIS
12 --------
13 Create or enable Linux kernel event rules:
14
15 [verse]
16 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
17 [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall |
18 option:--userspace-probe='SOURCE']
19 [option:--filter='EXPR'] [option:--session='SESSION']
20 [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
21
22 Create or enable an "all" Linux kernel event rule:
23
24 [verse]
25 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
26 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
27
28 Create or enable application/library event rules:
29
30 [verse]
31 *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
32 (option:--userspace | option:--jul | option:--log4j | option:--python)
33 [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...]
34 [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL']
35 [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...)
36
37
38 DESCRIPTION
39 -----------
40 The `lttng enable-event` command can create a new event rule, or enable
41 one or more existing and disabled ones.
42
43 An event rule created by `lttng enable-event` is a set of conditions
44 that must be satisfied in order for an actual event to be emitted by an
45 LTTng tracer when the execution of an application or a library or the
46 Linux kernel reaches an event source (tracepoint, system call, dynamic
47 probe). Event sources can be listed with the man:lttng-list(1) command.
48
49 The man:lttng-disable-event(1) command can be used to disable
50 existing event rules.
51
52 Event rules are always assigned to a channel when they are created. If
53 the option:--channel option is omitted, a default channel named
54 `channel0` is used (and created automatically if it does not exist for
55 the specified domain in the selected tracing session).
56
57 If the option:--session option is omitted, the chosen channel is picked
58 from the current tracing session.
59
60 Events can be enabled while tracing is active
61 (use man:lttng-start(1) to make a tracing session active).
62
63
64 Event source types
65 ~~~~~~~~~~~~~~~~~~
66 Five types of event sources are available in the Linux kernel tracing
67 domain (option:--kernel option):
68
69 Tracepoint (option:--tracepoint option; default)::
70 A Linux kernel tracepoint, that is, a static instrumentation point
71 placed in the kernel source code. Standard tracepoints are designed
72 and placed in the source code by developers and record useful
73 payload fields.
74
75 Dynamic kernel probe (option:--probe option)::
76 A Linux kernel kprobe, that is, an instrumentation point placed
77 dynamically in the compiled kernel code. Dynamic probe events do not
78 record any payload field.
79
80 Dynamic user space probe (option:--userspace-probe option)::
81 A Linux kernel uprobe, that is, an instrumentation point placed
82 dynamically in the compiled user space application/library through
83 the kernel. Dynamic user space probe events do not record any
84 payload field.
85 +
86 See the <<userspace-probe,Dynamic user space probes>> section for more
87 information.
88
89 Function probe (option:--function option)::
90 A Linux kernel kretprobe, that is, two instrumentation points placed
91 dynamically where a function is entered and where it returns in the
92 compiled kernel code. Function probe events do not record any
93 payload field.
94
95 System call (option:--syscall option)::
96 A Linux kernel system call. Two instrumentation points are
97 statically placed where a system call function is entered and where
98 it returns in the compiled kernel code. System call event sources
99 record useful payload fields.
100
101 The application tracing domains (option:--userspace, option:--jul,
102 option:--log4j, or option:--python options) only support tracepoints.
103 In the cases of the JUL, Apache log4j, and Python domains, the event
104 names correspond to _logger_ names.
105
106
107 Understanding event rule conditions
108 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109 When creating an event rule with `lttng enable-event`, conditions are
110 specified using options. The logical conjunction (logical AND) of all
111 those conditions must be true when an event source is reached by an
112 application or by the Linux kernel in order for an actual event
113 to be emitted by an LTTng tracer.
114
115 Any condition that is not explicitly specified on creation is considered
116 a _don't care_.
117
118 For example, consider the following commands:
119
120 [role="term"]
121 ----
122 $ lttng enable-event --userspace hello:world
123 $ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
124 ----
125
126 Here, two event rules are created. The first one has a single condition:
127 the tracepoint name must match `hello:world`. The second one has two
128 conditions:
129
130 * The tracepoint name must match `hello:world`, _and_
131 * The tracepoint's defined log level must be at least as severe as
132 the `TRACE_INFO` level.
133
134 In this case, the second event rule is pointless because the first one
135 is more general: it does not care about the tracepoint's log level.
136 If an event source matching both event rules is reached by the
137 application's execution, only one event is emitted.
138
139 The available conditions for the Linux kernel domain are:
140
141 * Tracepoint/system call name ('EVENT' argument with option:--tracepoint
142 or option:--syscall options) or dynamic probe/function name/address
143 (option:--probe, option:--userspace-probe, and option:--function
144 option's argument) which must match event source's equivalent.
145 +
146 You can use `*` characters at any place in the tracepoint or system
147 call name as wildcards to match zero or more characters. To use a
148 literal `*` character, use :escwc:.
149
150 * Filter expression (option:--filter option) executed against the
151 dynamic values of event fields at execution time that must evaluate
152 to true. See the <<filter-expr,Filter expression>> section
153 below for more information.
154
155 The available conditions for the application domains are:
156
157 * Tracepoint name ('EVENT' with option:--tracepoint option) which must
158 match event source's equivalent.
159 +
160 You can use `*` characters at any place in the tracepoint name as
161 wildcards to match zero or more characters. To use a literal `*`
162 character, use :escwc:. When you create an event rule with a tracepoint
163 name containing a wildcard, you can exclude specific tracepoint names
164 from the match with the option:--exclude option.
165
166 * Filter expression (option:--filter option) executed against the
167 dynamic values of event fields at execution time that must evaluate
168 to true. See the <<filter-expr,Filter expression>> section
169 below for more information.
170 * Event's log level that must be at least as severe as a given
171 log level (option:--loglevel option) or match exactly a given log
172 level (option:--loglevel-only option).
173
174 When using `lttng enable-event` with a set of conditions that does not
175 currently exist for the chosen tracing session, domain, and channel,
176 a new event rule is created. Otherwise, the existing event rule is
177 enabled if it is currently disabled
178 (see man:lttng-disable-event(1)).
179
180 The option:--all option can be used alongside the option:--tracepoint
181 or option:--syscall options. When this option is used, no 'EVENT'
182 argument must be specified. This option defines a single event rule
183 matching _all_ the possible events of a given tracing domain for the
184 chosen channel and tracing session. It is the equivalent of an 'EVENT'
185 argument named `*` (wildcard).
186
187
188 [[filter-expr]]
189 Filter expression
190 ~~~~~~~~~~~~~~~~~
191 A filter expression can be specified with the option:--filter option
192 when creating a new event rule. If the filter expression evaluates
193 to true when executed against the dynamic values of an event's fields
194 when tracing, the filtering condition passes.
195
196 NOTE: Make sure to **single-quote** the filter expression when running
197 the command from a shell, as filter expressions typically include
198 characters having a special meaning for most shells.
199
200 The filter expression syntax is similar to C language conditional
201 expressions (expressions that can be evaluated by an `if` statement),
202 albeit with a few differences:
203
204 * C integer and floating point number constants are supported, as well
205 as literal strings between double quotes (`"`). You can use `*`
206 characters at any place in a literal string as wildcards to match zero
207 or more characters. To use a literal `*` character, use :escwc:.
208 +
209 Examples: `32`, `-0x17`, `0755`, `12.34`,
210 +"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`.
211
212 * The dynamic value of an event field is read by using its name as a C
213 identifier.
214 +
215 The dot and square bracket notations are available, like in the C
216 language, to access nested structure and array/sequence fields.
217 Only a constant, positive integer number can be used within square
218 brackets. If the index is out of bounds, the whole filter expression
219 evaluates to false (the event is discarded).
220 +
221 An enumeration field's value is an integer.
222 +
223 When the expression's field does not exist, the whole filter expression
224 evaluates to false.
225 +
226 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
227
228 * The dynamic value of a statically-known context field is read by
229 prefixing its name with `$ctx.`. Statically-known context fields are
230 context fields added to channels without the `$app.` prefix using the
231 man:lttng-add-context(1) command.
232 +
233 When the expression's statically-known context field does not exist,
234 the whole filter expression evaluates to false.
235 +
236 Examples: `$ctx.prio`, `$ctx.preemptible`,
237 `$ctx.perf:cpu:stalled-cycles-frontend`.
238
239 * The dynamic value of an application-specific context field is read by
240 prefixing its name with `$app.` (follows the format used to add such a
241 context field with the man:lttng-add-context(1) command).
242 +
243 When the expression's application-specific context field does not exist,
244 the whole filter expression evaluates to false.
245 +
246 Example: `$app.server:cur_user`.
247
248 The following precedence table shows the operators which are supported
249 in a filter expression. In this table, the highest precedence is 1.
250 Parentheses are supported to bypass the default order.
251
252 IMPORTANT: Unlike the C language, the `lttng enable-event` filter
253 expression syntax's bitwise AND and OR operators (`&` and `|`) take
254 precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and
255 `!=`). This means the filter expression `2 & 2 == 2` is true while the
256 equivalent C expression is false.
257
258 [options="header"]
259 |===
260 |Precedence |Operator |Description |Associativity
261 |1 |`-` |Unary minus |Right-to-left
262 |1 |`+` |Unary plus |Right-to-left
263 |1 |`!` |Logical NOT |Right-to-left
264 |1 |`~` |Bitwise NOT |Right-to-left
265 |2 |`<<` |Bitwise left shift |Left-to-right
266 |2 |`>>` |Bitwise right shift |Left-to-right
267 |3 |`&` |Bitwise AND |Left-to-right
268 |4 |`^` |Bitwise XOR |Left-to-right
269 |5 |`\|` |Bitwise OR |Left-to-right
270 |6 |`<` |Less than |Left-to-right
271 |6 |`<=` |Less than or equal to |Left-to-right
272 |6 |`>` |Greater than |Left-to-right
273 |6 |`>=` |Greater than or equal to |Left-to-right
274 |7 |`==` |Equal to |Left-to-right
275 |7 |`!=` |Not equal to |Left-to-right
276 |8 |`&&` |Logical AND |Left-to-right
277 |9 |`\|\|` |Logical OR |Left-to-right
278 |===
279
280 The arithmetic operators are :not: supported.
281
282 All integer constants and fields are first casted to signed 64-bit
283 integers. The representation of negative integers is two's complement.
284 This means that, for example, the signed 8-bit integer field 0xff (-1)
285 becomes 0xffffffffffffffff (still -1) once casted.
286
287 Before a bitwise operator is applied, all its operands are casted to
288 unsigned 64-bit integers, and the result is casted back to a signed
289 64-bit integer. For the bitwise NOT operator, it is the equivalent of
290 this C expression:
291
292 [source,c]
293 ----
294 (int64_t) ~((uint64_t) val)
295 ----
296
297 For the binary bitwise operators, it is the equivalent of those C
298 expressions:
299
300 [source,c]
301 ----
302 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
303 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
304 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
305 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
306 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
307 ----
308
309 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
310 not in the [0,{nbsp}63] range, the whole filter expression evaluates to
311 false.
312
313 NOTE: Although it is possible to filter the process ID of an event when
314 the `pid` context has been added to its channel using, for example,
315 `$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
316 which is much more efficient (see man:lttng-track(1)).
317
318 Filter expression examples:
319
320 ----------------------------
321 msg_id == 23 && size >= 2048
322 ----------------------------
323
324 -------------------------------------------------
325 $ctx.procname == "lttng*" && (!flag || poel < 34)
326 -------------------------------------------------
327
328 ---------------------------------------------------------
329 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
330 ---------------------------------------------------------
331
332 ---------------------------------------
333 $ctx.cpu_id == 2 && filename != "*.log"
334 ---------------------------------------
335
336 ------------------------------------------------
337 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
338 ------------------------------------------------
339
340
341 [[log-levels]]
342 Log levels
343 ~~~~~~~~~~
344 Tracepoints and log statements in applications have an attached log
345 level. Application event rules can contain a _log level_ condition.
346
347 With the option:--loglevel option, the event source's log level must
348 be at least as severe as the option's argument. With the
349 option:--loglevel-only option, the event source's log level must match
350 the option's argument.
351
352 The available log levels are:
353
354 User space domain (option:--userspace option)::
355 Shortcuts such as `system` are allowed.
356 +
357 * `TRACE_EMERG` (0)
358 * `TRACE_ALERT` (1)
359 * `TRACE_CRIT` (2)
360 * `TRACE_ERR` (3)
361 * `TRACE_WARNING` (4)
362 * `TRACE_NOTICE` (5)
363 * `TRACE_INFO` (6)
364 * `TRACE_DEBUG_SYSTEM` (7)
365 * `TRACE_DEBUG_PROGRAM` (8)
366 * `TRACE_DEBUG_PROCESS` (9)
367 * `TRACE_DEBUG_MODULE` (10)
368 * `TRACE_DEBUG_UNIT` (11)
369 * `TRACE_DEBUG_FUNCTION` (12)
370 * `TRACE_DEBUG_LINE` (13)
371 * `TRACE_DEBUG` (14)
372
373 `java.util.logging` domain (option:--jul option)::
374 Shortcuts such as `severe` are allowed.
375 +
376 * `JUL_OFF` (`INT32_MAX`)
377 * `JUL_SEVERE` (1000)
378 * `JUL_WARNING` (900)
379 * `JUL_INFO` (800)
380 * `JUL_CONFIG` (700)
381 * `JUL_FINE` (500)
382 * `JUL_FINER` (400)
383 * `JUL_FINEST` (300)
384 * `JUL_ALL` (`INT32_MIN`)
385
386 Apache log4j domain (option:--log4j option)::
387 Shortcuts such as `severe` are allowed.
388 +
389 * `LOG4J_OFF` (`INT32_MAX`)
390 * `LOG4J_FATAL` (50000)
391 * `LOG4J_ERROR` (40000)
392 * `LOG4J_WARN` (30000)
393 * `LOG4J_INFO` (20000)
394 * `LOG4J_DEBUG` (10000)
395 * `LOG4J_TRACE` (5000)
396 * `LOG4J_ALL` (`INT32_MIN`)
397
398 Python domain (option:--python option)::
399 Shortcuts such as `critical` are allowed.
400 +
401 * `PYTHON_CRITICAL` (50)
402 * `PYTHON_ERROR` (40)
403 * `PYTHON_WARNING` (30)
404 * `PYTHON_INFO` (20)
405 * `PYTHON_DEBUG` (10)
406 * `PYTHON_NOTSET` (0)
407
408
409 [[userspace-probe]]
410 Dynamic user space probes
411 ~~~~~~~~~~~~~~~~~~~~~~~~~
412 With the option:--userspace-probe option, you can instrument function
413 entries of any user space binary (application or library) using either
414 an available symbol name or a SystemTap User-level Statically Defined
415 Tracing (USDT, a DTrace-style marker) probe's provider and probe names.
416 As of this version, only USDT probes that are :not: surrounded by a
417 reference counter (semaphore) are supported.
418
419 The option:--userspace-probe option must be specified with the
420 option:--kernel option because it uses Linux's uprobe feature to
421 dynamically instrument a user space application or library.
422
423 As of this version, dynamic probe events do not record any payload
424 field.
425
426
427 include::common-cmd-options-head.txt[]
428
429
430 Domain
431 ~~~~~~
432 One of:
433
434 option:-j, option:--jul::
435 Create or enable event rules in the `java.util.logging`
436 (JUL) domain.
437
438 option:-k, option:--kernel::
439 Create or enable event rules in the Linux kernel domain.
440
441 option:-l, option:--log4j::
442 Create or enable event rules in the Apache log4j domain.
443
444 option:-p, option:--python::
445 Create or enable event rules in the Python domain.
446
447 option:-u, option:--userspace::
448 Create or enable event rules in the user space domain.
449
450
451 Target
452 ~~~~~~
453 option:-c 'CHANNEL', option:--channel='CHANNEL'::
454 Create or enable event rules in the channel named 'CHANNEL' instead
455 of the default channel name `channel0`.
456
457 option:-s 'SESSION', option:--session='SESSION'::
458 Create or enable event rules in the tracing session named 'SESSION'
459 instead of the current tracing session.
460
461
462 Event source type
463 ~~~~~~~~~~~~~~~~~
464 One of:
465
466 option:--function='SOURCE'::
467 Dynamic kernel return probe (kretprobe). Only available with the
468 option:--kernel domain option. 'SOURCE' is one of:
469 +
470 * Function address (`0x` prefix supported)
471 * Function symbol name
472 * Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
473
474 option:--probe='SOURCE'::
475 Dynamic kernel probe (kprobe). Only available with the
476 option:--kernel domain option. 'SOURCE' is one of:
477 +
478 * Address (`0x` prefix supported)
479 * Symbol nane
480 * Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
481
482 option:--userspace-probe='SOURCE'::
483 Dynamic user space probe (uprobe). Only available with the
484 option:--kernel domain option. See the
485 <<userspace-probe,Dynamic user space probes>> section.
486 +
487 'SOURCE' is one of:
488 +
489 --
490 \[++elf:++]__PATH__++:++__SYMBOL__::
491 Dynamically instrument an available symbol within a user space
492 application or library.
493 +
494 --
495 'PATH'::
496 Application or library path.
497 +
498 This can be:
499 +
500 * An absolute path.
501 * A relative path.
502 * An application's name as found in the directories listed in the
503 `PATH` environment variable.
504
505 'SYMBOL'::
506 Symbol name of the function of which to instrument the entry.
507 +
508 This can be any defined code symbol listed by the man:nm(1) command
509 (including with its nloption:--dynamic option which lists dynamic
510 symbols).
511 --
512 +
513 As of this version, not specifying `elf:` is equivalent to specifying
514 it.
515 +
516 Examples:
517 +
518 * `--userspace-probe=/usr/lib/libc.so.6:malloc`
519 * `--userspace-probe=./myapp:createUser`
520 * `--userspace-probe=httpd:ap_run_open_htaccess`
521
522 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
523 Dynamically instrument a USDT probe within a user space application
524 or library.
525 +
526 --
527 'PATH'::
528 Application or library path.
529 +
530 This can be:
531 +
532 * An absolute path.
533 * A relative path.
534 * An application's name as found in the directories listed in the
535 `PATH` environment variable.
536
537 __PROVIDER__++:++__NAME__::
538 USDT provider and probe names.
539 +
540 For example, with the following USDT probe:
541 +
542 [source,c]
543 ----
544 DTRACE_PROBE2("server", "accept_request",
545 request_id, ip_addr);
546 ----
547 +
548 The provider/probe name pair is `server:accept_request`.
549 --
550 +
551 Example:
552 +
553 * `--userspace-probe=sdt:./build/server:server:accept_request`
554 --
555
556 option:--syscall::
557 Linux kernel system call. Only available with the option:--kernel
558 domain option.
559
560 option:--tracepoint::
561 Linux kernel or application tracepoint (default).
562
563
564 Log level
565 ~~~~~~~~~
566 One of:
567
568 option:--loglevel='LOGLEVEL'::
569 Add log level condition to the event rule: the event source's
570 defined log level must be at least as severe as 'LOGLEVEL'.
571 See the <<log-levels,Log levels>> section above for the available
572 log levels. Only available with application domains.
573
574 option:--loglevel-only='LOGLEVEL'::
575 Add log level condition to the event rule: the event source's
576 defined log level must match 'LOGLEVEL'. See the
577 <<log-levels,Log levels>> section above for the available log
578 levels. Only available with application domains.
579
580
581 Filtering and exclusion
582 ~~~~~~~~~~~~~~~~~~~~~~~
583 option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
584 Exclude events named 'EVENT' from the event rule. This option
585 can be used when the command's 'EVENT' argument contains at least
586 one wildcard star (`*`) to exclude specific names. 'EVENT' can also
587 contain wildcard stars. To use a
588 literal `,` character, use :esccomma:.
589 Only available with the option:--userspace domain.
590
591 option:-f 'EXPR', option:--filter='EXPR'::
592 Add filter expression condition to the event rule. Expression 'EXPR'
593 must evaluate to true when executed against the dynamic values of
594 event fields. See the <<filter-expr,Filter expression>>
595 section above for more information.
596
597
598 Shortcuts
599 ~~~~~~~~~
600 option:-a, option:--all::
601 Equivalent to an 'EVENT' argument named `*` (wildcard) when also
602 using the option:--tracepoint (default) or option:--syscall option.
603
604
605 include::common-cmd-help-options.txt[]
606
607
608 include::common-cmd-footer.txt[]
609
610
611 SEE ALSO
612 --------
613 man:lttng-disable-event(1),
614 man:lttng(1)
This page took 0.039886 seconds and 3 git commands to generate.