doc: fix typo in lttng-enable-event man page
[lttng-tools.git] / doc / man / lttng-enable-event.1.txt
CommitLineData
e9b06e2b
PP
1lttng-enable-event(1)
2=====================
4605890e 3:revdate: 4 April 2019
e9b06e2b
PP
4
5
6NAME
7----
8lttng-enable-event - Create or enable LTTng event rules
9
10
11SYNOPSIS
12--------
13Create or enable Linux kernel event rules:
14
15[verse]
ce19b9ed 16*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
b981f450
PP
17 [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall |
18 option:--userspace-probe='SOURCE']
e9b06e2b
PP
19 [option:--filter='EXPR'] [option:--session='SESSION']
20 [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']...
21
22Create or enable an "all" Linux kernel event rule:
23
24[verse]
ce19b9ed 25*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall]
e9b06e2b
PP
26 [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
27
b981f450 28Create or enable application/library event rules:
e9b06e2b
PP
29
30[verse]
ce19b9ed 31*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event*
e9b06e2b
PP
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
38DESCRIPTION
39-----------
40The `lttng enable-event` command can create a new event rule, or enable
41one or more existing and disabled ones.
42
43An event rule created by `lttng enable-event` is a set of conditions
b981f450
PP
44that must be satisfied in order for an actual event to be emitted by an
45LTTng tracer when the execution of an application or a library or the
46Linux kernel reaches an event source (tracepoint, system call, dynamic
47probe). Event sources can be listed with the man:lttng-list(1) command.
e9b06e2b 48
7c1a4458 49The man:lttng-disable-event(1) command can be used to disable
e9b06e2b
PP
50existing event rules.
51
52Event rules are always assigned to a channel when they are created. If
53the option:--channel option is omitted, a default channel named
54`channel0` is used (and created automatically if it does not exist for
55the specified domain in the selected tracing session).
56
57If the option:--session option is omitted, the chosen channel is picked
58from the current tracing session.
59
60Events can be enabled while tracing is active
7c1a4458 61(use man:lttng-start(1) to make a tracing session active).
e9b06e2b
PP
62
63
64Event source types
65~~~~~~~~~~~~~~~~~~
b981f450 66Five types of event sources are available in the Linux kernel tracing
e9b06e2b
PP
67domain (option:--kernel option):
68
69Tracepoint (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
b981f450 75Dynamic kernel probe (option:--probe option)::
e9b06e2b
PP
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
b981f450
PP
80Dynamic 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+
86See the <<userspace-probe,Dynamic user space probes>> section for more
87information.
88
e9b06e2b
PP
89Function 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
95System 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
101The application tracing domains (option:--userspace, option:--jul,
102option:--log4j, or option:--python options) only support tracepoints.
103In the cases of the JUL, Apache log4j, and Python domains, the event
104names correspond to _logger_ names.
105
106
107Understanding event rule conditions
108~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
109When creating an event rule with `lttng enable-event`, conditions are
110specified using options. The logical conjunction (logical AND) of all
111those conditions must be true when an event source is reached by an
112application or by the Linux kernel in order for an actual event
113to be emitted by an LTTng tracer.
114
115Any condition that is not explicitly specified on creation is considered
116a _don't care_.
117
118For example, consider the following commands:
119
d4f093aa 120[role="term"]
03c5529d
PP
121----
122$ lttng enable-event --userspace hello:world
123$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
124----
e9b06e2b
PP
125
126Here, two event rules are created. The first one has a single condition:
127the tracepoint name must match `hello:world`. The second one has two
128conditions:
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
134In this case, the second event rule is pointless because the first one
135is more general: it does not care about the tracepoint's log level.
136If an event source matching both event rules is reached by the
137application's execution, only one event is emitted.
138
139The available conditions for the Linux kernel domain are:
140
b981f450
PP
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.
e9b06e2b 145+
f69e7997
PP
146You can use `*` characters at any place in the tracepoint or system
147call name as wildcards to match zero or more characters. To use a
148literal `*` character, use :escwc:.
e9b06e2b
PP
149
150* Filter expression (option:--filter option) executed against the
151 dynamic values of event fields at execution time that must evaluate
11613178 152 to true. See the <<filter-expr,Filter expression>> section
e9b06e2b
PP
153 below for more information.
154
155The 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+
f69e7997
PP
160You can use `*` characters at any place in the tracepoint name as
161wildcards to match zero or more characters. To use a literal `*`
162character, use :escwc:. When you create an event rule with a tracepoint
163name containing a wildcard, you can exclude specific tracepoint names
164from the match with the option:--exclude option.
e9b06e2b
PP
165
166* Filter expression (option:--filter option) executed against the
167 dynamic values of event fields at execution time that must evaluate
11613178 168 to true. See the <<filter-expr,Filter expression>> section
e9b06e2b
PP
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
174When using `lttng enable-event` with a set of conditions that does not
175currently exist for the chosen tracing session, domain, and channel,
176a new event rule is created. Otherwise, the existing event rule is
177enabled if it is currently disabled
7c1a4458 178(see man:lttng-disable-event(1)).
e9b06e2b
PP
179
180The option:--all option can be used alongside the option:--tracepoint
181or option:--syscall options. When this option is used, no 'EVENT'
182argument must be specified. This option defines a single event rule
183matching _all_ the possible events of a given tracing domain for the
184chosen channel and tracing session. It is the equivalent of an 'EVENT'
185argument named `*` (wildcard).
186
187
11613178
PP
188[[filter-expr]]
189Filter expression
190~~~~~~~~~~~~~~~~~
c52365cc 191A filter expression can be specified with the option:--filter option
11613178
PP
192when creating a new event rule. If the filter expression evaluates
193to true when executed against the dynamic values of an event's fields
194when tracing, the filtering condition passes.
e9b06e2b 195
60f7980c
PP
196NOTE: Make sure to **single-quote** the filter expression when running
197the command from a shell, as filter expressions typically include
198characters having a special meaning for most shells.
199
11613178
PP
200The filter expression syntax is similar to C language conditional
201expressions (expressions that can be evaluated by an `if` statement),
202albeit with a few differences:
e9b06e2b 203
11613178
PP
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+
209Examples: `32`, `-0x17`, `0755`, `12.34`,
210+"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`.
e9b06e2b 211
11613178
PP
212* The dynamic value of an event field is read by using its name as a C
213 identifier.
214+
215The dot and square bracket notations are available, like in the C
216language, to access nested structure and array/sequence fields.
217Only a constant, positive integer number can be used within square
218brackets. If the index is out of bounds, the whole filter expression
219evaluates to false (the event is discarded).
220+
221An enumeration field's value is an integer.
222+
223When the expression's field does not exist, the whole filter expression
224evaluates to false.
225+
226Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
e9b06e2b 227
11613178
PP
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+
233When the expression's statically-known context field does not exist,
234the whole filter expression evaluates to false.
235+
236Examples: `$ctx.prio`, `$ctx.preemptible`,
237`$ctx.perf:cpu:stalled-cycles-frontend`.
e9b06e2b 238
11613178
PP
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+
243When the expression's application-specific context field does not exist,
244the whole filter expression evaluates to false.
245+
246Example: `$app.server:cur_user`.
247
248The following precedence table shows the operators which are supported
249in a filter expression. In this table, the highest precedence is 1.
250Parentheses are supported to bypass the default order.
251
252IMPORTANT: Unlike the C language, the `lttng enable-event` filter
253expression syntax's bitwise AND and OR operators (`&` and `|`) take
254precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and
255`!=`). This means the filter expression `2 & 2 == 2` is true while the
256equivalent 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
280The arithmetic operators are :not: supported.
281
282All integer constants and fields are first casted to signed 64-bit
283integers. The representation of negative integers is two's complement.
284This means that, for example, the signed 8-bit integer field 0xff (-1)
285becomes 0xffffffffffffffff (still -1) once casted.
286
287Before a bitwise operator is applied, all its operands are casted to
288unsigned 64-bit integers, and the result is casted back to a signed
28964-bit integer. For the bitwise NOT operator, it is the equivalent of
290this C expression:
291
292[source,c]
293----
294(int64_t) ~((uint64_t) val)
295----
e9b06e2b 296
11613178
PP
297For the binary bitwise operators, it is the equivalent of those C
298expressions:
e9b06e2b 299
11613178
PP
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----
e9b06e2b 308
11613178
PP
309If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
310not in the [0,{nbsp}63] range, the whole filter expression evaluates to
311false.
e9b06e2b
PP
312
313NOTE: Although it is possible to filter the process ID of an event when
314the `pid` context has been added to its channel using, for example,
315`$ctx.pid == 2832`, it is recommended to use the PID tracker instead,
7c1a4458 316which is much more efficient (see man:lttng-track(1)).
e9b06e2b 317
11613178 318Filter expression examples:
e9b06e2b
PP
319
320----------------------------
321msg_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
c52365cc
PP
332---------------------------------------
333$ctx.cpu_id == 2 && filename != "*.log"
334---------------------------------------
f69e7997 335
11613178
PP
336------------------------------------------------
337eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
338------------------------------------------------
339
e9b06e2b
PP
340
341[[log-levels]]
342Log levels
343~~~~~~~~~~
344Tracepoints and log statements in applications have an attached log
345level. Application event rules can contain a _log level_ condition.
346
347With the option:--loglevel option, the event source's log level must
348be at least as severe as the option's argument. With the
349option:--loglevel-only option, the event source's log level must match
350the option's argument.
351
352The available log levels are:
353
354User 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
386Apache 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
398Python 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
b981f450
PP
409[[userspace-probe]]
410Dynamic user space probes
411~~~~~~~~~~~~~~~~~~~~~~~~~
412With the option:--userspace-probe option, you can instrument function
413entries of any user space binary (application or library) using either
0e63136b
GB
414an available symbol name or a SystemTap User-level Statically Defined
415Tracing (USDT, a DTrace-style marker) probe's provider and probe names.
416As of this version, only USDT probes that are :not: surrounded by a
417reference counter (semaphore) are supported.
b981f450
PP
418
419The option:--userspace-probe option must be specified with the
420option:--kernel option because it uses Linux's uprobe feature to
421dynamically instrument a user space application or library.
422
423As of this version, dynamic probe events do not record any payload
424field.
425
b981f450 426
fa72991a
PP
427include::common-cmd-options-head.txt[]
428
429
430Domain
431~~~~~~
432One of:
433
434option:-j, option:--jul::
435 Create or enable event rules in the `java.util.logging`
436 (JUL) domain.
437
438option:-k, option:--kernel::
439 Create or enable event rules in the Linux kernel domain.
440
441option:-l, option:--log4j::
442 Create or enable event rules in the Apache log4j domain.
443
444option:-p, option:--python::
445 Create or enable event rules in the Python domain.
446
447option:-u, option:--userspace::
448 Create or enable event rules in the user space domain.
449
450
451Target
452~~~~~~
453option:-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
457option:-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
462Event source type
463~~~~~~~~~~~~~~~~~
464One of:
465
466option:--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
474option:--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)
c32f3198 479* Symbol name
fa72991a
PP
480* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format)
481
482option:--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__::
b981f450 491 Dynamically instrument an available symbol within a user space
fa72991a 492 application or library.
b981f450
PP
493+
494--
495'PATH'::
496 Application or library path.
497+
498This can be:
499+
500* An absolute path.
501* A relative path.
fa72991a 502* An application's name as found in the directories listed in the
b981f450
PP
503 `PATH` environment variable.
504
505'SYMBOL'::
506 Symbol name of the function of which to instrument the entry.
507+
508This can be any defined code symbol listed by the man:nm(1) command
509(including with its nloption:--dynamic option which lists dynamic
510symbols).
511--
512+
513As of this version, not specifying `elf:` is equivalent to specifying
514it.
515+
516Examples:
517+
518* `--userspace-probe=/usr/lib/libc.so.6:malloc`
519* `--userspace-probe=./myapp:createUser`
520* `--userspace-probe=httpd:ap_run_open_htaccess`
521
fa72991a 522++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::
0e63136b 523 Dynamically instrument a USDT probe within a user space application
fa72991a 524 or library.
b981f450
PP
525+
526--
527'PATH'::
528 Application or library path.
529+
530This can be:
531+
532* An absolute path.
533* A relative path.
fa72991a 534* An application's name as found in the directories listed in the
b981f450
PP
535 `PATH` environment variable.
536
fa72991a 537__PROVIDER__++:++__NAME__::
0e63136b 538 USDT provider and probe names.
b981f450 539+
0e63136b 540For example, with the following USDT probe:
b981f450
PP
541+
542[source,c]
543----
544DTRACE_PROBE2("server", "accept_request",
545 request_id, ip_addr);
546----
547+
548The provider/probe name pair is `server:accept_request`.
549--
550+
551Example:
552+
553* `--userspace-probe=sdt:./build/server:server:accept_request`
fa72991a 554--
b981f450 555
e9b06e2b
PP
556option:--syscall::
557 Linux kernel system call. Only available with the option:--kernel
558 domain option.
559
560option:--tracepoint::
561 Linux kernel or application tracepoint (default).
562
563
564Log level
565~~~~~~~~~
566One of:
567
568option:--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
574option:--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
581Filtering and exclusion
582~~~~~~~~~~~~~~~~~~~~~~~
59b19c3c 583option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...::
e9b06e2b 584 Exclude events named 'EVENT' from the event rule. This option
f69e7997
PP
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.
e9b06e2b 590
59b19c3c 591option:-f 'EXPR', option:--filter='EXPR'::
e9b06e2b
PP
592 Add filter expression condition to the event rule. Expression 'EXPR'
593 must evaluate to true when executed against the dynamic values of
11613178 594 event fields. See the <<filter-expr,Filter expression>>
e9b06e2b
PP
595 section above for more information.
596
597
598Shortcuts
599~~~~~~~~~
600option:-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
605include::common-cmd-help-options.txt[]
606
607
608include::common-cmd-footer.txt[]
609
610
611SEE ALSO
612--------
7c1a4458
PP
613man:lttng-disable-event(1),
614man:lttng(1)
This page took 0.053736 seconds and 4 git commands to generate.