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