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