Fix: build: libcommon fd-tracker dependency is not available
[lttng-tools.git] / doc / man / lttng-event-rule.7.txt
1 lttng-event-rule(7)
2 ===================
3 :revdate: 12 May 2021
4
5
6 NAME
7 ----
8 lttng-event-rule - Common LTTng event rule specification
9
10
11 SYNOPSIS
12 --------
13 Specify an event rule to match Linux kernel tracepoint or system call
14 events:
15
16 [verse]
17 option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])]
18 pass:[[]option:--name='NAME'] [option:--filter='EXPR']
19
20 Specify an event rule to match Linux kernel kprobe or user space
21 probe events:
22
23 [verse]
24 option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC'
25 pass:[[]option:--event-name='EVENTNAME']
26
27 Specify an event rule to match user space tracepoint events:
28
29 [verse]
30 option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']...
31 pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
32
33 Specify an event rule to match Java/Python logging events:
34
35 [verse]
36 option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME']
37 pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
38
39
40 DESCRIPTION
41 -----------
42 This manual page shows how to specify an LTTng event rule on the command
43 line.
44
45 As of LTTng{nbsp}{lttng_version}, the command-line options documented
46 here only apply to the `event-rule-matches` trigger condition specifier
47 (see man:lttng-add-trigger(1)).
48
49 See man:lttng-concepts(7) to learn more about instrumentation points,
50 events, and event rules.
51
52 [NOTE]
53 ====
54 This manual page only describes the common event rule options. The
55 man:lttng(1) commands which require an event rule specification may
56 accept or require other options and arguments, depending on the context.
57
58 For example, the man:lttng-add-trigger(1) command also accepts
59 nloption:--capture options with the `event-rule-matches` trigger
60 condition.
61 ====
62
63
64 Overview of event rule condtions
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66 For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
67 conditions of an event rule, that is:
68
69 * The instrumentation point from which LTTng creates{nbsp}__E__ has a
70 specific type.
71 +
72 See the <<inst-point-type-cond,Instrumentation point type condition>>
73 section below.
74
75 * A pattern matches the name of{nbsp}__E__ while another pattern
76 doesn't.
77 +
78 See the <<event-name-cond,Event name condition>> section below.
79
80 * The log level of the instrumentation point from which LTTng
81 creates{nbsp}__E__ is at least as severe as some value, or is exactly
82 some value.
83 +
84 See the <<inst-point-log-level-cond,Instrumentation point log level
85 condition>> section below.
86
87 * The fields of the payload of{nbsp}__E__ and the current context fields
88 satisfy a filter expression.
89 +
90 See the <<filter-cond,Event payload and context filter condition>>
91 section below.
92
93 The dedicated command-line options of most conditions are optional: if
94 you don't specify the option, the associated condition is always
95 satisfied.
96
97
98 [[inst-point-type-cond]]
99 Instrumentation point type condition
100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101 An event{nbsp}__E__ satisfies the instrumentation point type condition
102 of an event rule if the instrumentation point from which LTTng
103 creates{nbsp}__E__ is:
104
105 For the Linux kernel tracing domain (option:--domain=++kernel++ option)::
106 With the option:--type=++tracepoint++ option or without any option:--type option:::
107 An LTTng kernel tracepoint, that is, a statically defined point
108 in the source code of the kernel image or of a kernel module
109 with LTTng kernel tracer macros.
110 +
111 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
112 point type of the Linux kernel tracing domain, but this may change in
113 the future.
114 +
115 List the available Linux kernel tracepoints with `lttng list --kernel`.
116 See man:lttng-list(1) to learn more.
117
118 With the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, or option:--type=++syscall:entry+exit++ option:::
119 The entry, exit, or entry and exit of a Linux kernel system
120 call.
121 +
122 List the available Linux kernel system call instrumentation points with
123 `lttng list --kernel --syscall`. See man:lttng-list(1) to learn more.
124
125 With the option:--type=++kprobe++ option:::
126 A Linux kprobe, that is, a single probe dynamically placed in
127 the compiled kernel code.
128 +
129 You must specify the kprobe location with the option:--location option.
130 +
131 The payload of a Linux kprobe event is empty.
132
133 With the option:--type=++uprobe++ option:::
134 A Linux user space probe, that is, a single probe dynamically
135 placed at the entry of a compiled user space application/library
136 function through the kernel.
137 +
138 LTTng{nbsp}{lttng_version} supports the ELF and SystemTap User-level
139 Statically Defined Tracing (USDT; a DTrace-style marker) probing
140 methods. LTTng only supports USDT probes which are :not:
141 reference-counted.
142 +
143 You must specify the user space probe location with the
144 option:--location option.
145 +
146 The payload of a Linux user space probe event is empty.
147
148 For the user space tracing domain (option:--domain=++user++ option)::
149 With or without the option:--type=++tracepoint++ option:::
150 An LTTng user space tracepoint, that is, a statically defined point
151 in the source code of a C/$$C++$$ application/library
152 with LTTng user space tracer macros.
153 +
154 As of LTTng{nbsp}{lttng_version}, this is the default and sole
155 instrumentation point type of the user space tracing domain, but this
156 may change in the future.
157 +
158 List the available user space tracepoints with `lttng list --userspace`.
159 See man:lttng-list(1) to learn more.
160
161 For the `java.util.logging` (option:--domain=++jul++ option), Apache log4j (option:--domain=++log4j++ option), and Python (option:--domain=++python++ option) tracing domains::
162 With or without the option:--type=++logging++ option:::
163 A logging statement.
164 +
165 As of LTTng{nbsp}{lttng_version}, this is the default and sole
166 instrumentation point type of the `java.util.logging`, Apache log4j, and
167 Python tracing domains, but this may change in the future.
168 +
169 List the available Java and Python loggers with `lttng list --jul`,
170 `lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
171 to learn more.
172
173
174 [[event-name-cond]]
175 Event name condition
176 ~~~~~~~~~~~~~~~~~~~~
177 An event{nbsp}__E__ satisfies the event name condition of an event
178 rule{nbsp}__ER__ if the two following statements are true:
179
180 * You don't specify the option:--name='NAME' option or, depending on the
181 instrumentation type condition (see the
182 <<inst-point-type-cond,Instrumentation point type condition>> section
183 above) of{nbsp}__ER__, 'NAME' matches:
184 +
185 --
186 LTTng tracepoint::
187 The full name of the tracepoint from which LTTng creates{nbsp}__E__.
188 +
189 Note that the full name of a user space tracepoint is
190 __PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
191 name and __NAME__ is the tracepoint name.
192
193 Logging statement::
194 The name of the Java or Python logger from which LTTng
195 creates{nbsp}__E__.
196
197 Linux system call::
198 The name of the system call, without any `sys_` prefix, from which
199 LTTng creates{nbsp}__E__.
200 --
201
202 * You don't specify any option:--exclude-name='XNAME' option or
203 none of the 'XNAME' arguments matches the full name of the user space
204 tracepoint from which LTTng creates{nbsp}__E__.
205 +
206 The option:--exclude-name option is only available with the
207 option:--domain=++user++ option.
208
209 This condition is only meaningful for the LTTng tracepoint, logging
210 statement, and Linux system call instrumentation point types: it's
211 always satisfied for the other types.
212
213 In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
214 character means ``match anything''. To match a literal `*` character,
215 use :escwc:.
216
217 IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
218 contain the `*` character and when you run an man:lttng(1) command from
219 a shell.
220
221 As of LTTng{nbsp}{lttng_version}, not specifying the option:--name
222 option is equivalent to specifying option:--name=++\'*\'++, but this
223 default may change in the future.
224
225
226 [[inst-point-log-level-cond]]
227 Instrumentation point log level condition
228 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229 An event{nbsp}__E__ satisfies the instrumentation point log level
230 condition of an event rule if either:
231
232 * You specify the option:--log-level=++..++ option or you don't specify
233 the option:--log-level option.
234 +
235 Defaulting to option:--log-level=++..++ when you don't specify the
236 option:--log-level option is specific to LTTng{nbsp}{lttng_version} and
237 may change in the future.
238
239 * The log level of the LTTng user space tracepoint or logging statement
240 from which LTTng creates{nbsp}__E__ is:
241 With the option:--log-level=__LOGLEVEL__++..++ option::
242 At least as severe as 'LOGLEVEL'.
243
244 With the option:--log-level=__LOGLEVEL__ option::
245 Exactly 'LOGLEVEL'.
246
247 As of LTTng{nbsp}{lttng_version}, the ++..++__LOGLEVEL__ and
248 __LOGLEVEL__++..++__LOGLEVEL__ formats are :not: supported.
249
250 This condition is only meaningful for the LTTng user space tracepoint
251 and logging statement instrumentation point types: it's always satisfied
252 for other types.
253
254 The available values of 'LOGLEVEL' are, depending on the tracing domain,
255 from the most to the least severe:
256
257 User space (option:--domain=++user++ option)::
258 +
259 * `EMERG` (0)
260 * `ALERT` (1)
261 * `CRIT` (2)
262 * `ERR` (3)
263 * `WARNING` (4)
264 * `NOTICE` (5)
265 * `INFO` (6)
266 * `DEBUG_SYSTEM` (7)
267 * `DEBUG_PROGRAM` (8)
268 * `DEBUG_PROCESS` (9)
269 * `DEBUG_MODULE` (10)
270 * `DEBUG_UNIT` (11)
271 * `DEBUG_FUNCTION` (12)
272 * `DEBUG_LINE` (13)
273 * `DEBUG` (14)
274
275 `java.util.logging` (option:--domain=++jul++ option)::
276 +
277 * `OFF` (`INT32_MAX`)
278 * `SEVERE` (1000)
279 * `WARNING` (900)
280 * `INFO` (800)
281 * `CONFIG` (700)
282 * `FINE` (500)
283 * `FINER` (400)
284 * `FINEST` (300)
285 * `ALL` (`INT32_MIN`)
286
287 Apache log4j (option:--domain=++log4j++ option)::
288 +
289 * `OFF` (`INT32_MAX`)
290 * `FATAL` (50000)
291 * `ERROR` (40000)
292 * `WARN` (30000)
293 * `INFO` (20000)
294 * `DEBUG` (10000)
295 * `TRACE` (5000)
296 * `ALL` (`INT32_MIN`)
297
298 Python (option:--domain=++python++ option)::
299 +
300 * `CRITICAL` (50)
301 * `ERROR` (40)
302 * `WARNING` (30)
303 * `INFO` (20)
304 * `DEBUG` (10)
305 * `NOTSET` (0)
306
307
308 [[filter-cond]]
309 Event payload and context filter condition
310 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311 An event{nbsp}__E__ satisfies the event payload and context filter
312 condition of an event rule if the option:--filter='EXPR' option is
313 missing or if 'EXPR' is _true_.
314
315 This condition is only meaningful for the LTTng tracepoint and Linux
316 system call instrumentation point types: it's always satisfied for other
317 types.
318
319 'EXPR' can contain references to the payload fields of{nbsp}__E__ and
320 to the current context fields.
321
322 IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an
323 man:lttng(1) command from a shell, as filter expressions typically
324 include characters having a special meaning for most shells.
325
326 The expected syntax of 'EXPR' is similar to the syntax of a
327 C{nbsp}language conditional expression (an expression which an `if`
328 statement can evaluate), but there are a few differences:
329
330 * A _NAME_ expression identifies an event payload field named
331 _NAME_ (a C{nbsp}identifier).
332 +
333 Use the C{nbsp}language dot and square bracket notations to access
334 nested structure and array/sequence fields. You can only use a constant,
335 positive integer number within square brackets. If the index is out of
336 bounds, 'EXPR' is _false_.
337 +
338 The value of an enumeration field is an integer.
339 +
340 When a field expression doesn't exist, 'EXPR' is _false_.
341 +
342 Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`.
343
344 * A ++$ctx.++__TYPE__ expression identifies the statically-known context
345 field having the type _TYPE_ (a C{nbsp}identifier).
346 +
347 List the available statically-known context field names with the
348 man:lttng-add-context(1) command.
349 +
350 When a field expression doesn't exist, 'EXPR' is _false_.
351 +
352 Examples: `$ctx.prio`, `$ctx.preemptible`,
353 `$ctx.perf:cpu:stalled-cycles-frontend`.
354
355 * A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the
356 application-specific context field having the type _TYPE_ (a
357 C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier).
358 +
359 When a field expression doesn't exist, 'EXPR' is _false_.
360 +
361 Example: `$app.server:cur_user`.
362
363 * Compare strings, either string fields or string literals
364 (double-quoted), with the `==` and `!=` operators.
365 +
366 When comparing to a string literal, the `*` character means ``match
367 anything''. To match a literal `*` character, use :escwc:.
368 +
369 Examples: `my_field == "user34"`, `my_field == my_other_field`,
370 `my_field == "192.168.*"`.
371
372 * The precedence table of the operators which are supported in 'EXPR'
373 is as follows. In this table, the highest precedence is{nbsp}1:
374 +
375 [options="header"]
376 |===
377 |Precedence |Operator |Description |Associativity
378 |1 |`-` |Unary minus |Right-to-left
379 |1 |`+` |Unary plus |Right-to-left
380 |1 |`!` |Logical NOT |Right-to-left
381 |1 |`~` |Bitwise NOT |Right-to-left
382 |2 |`<<` |Bitwise left shift |Left-to-right
383 |2 |`>>` |Bitwise right shift |Left-to-right
384 |3 |`&` |Bitwise AND |Left-to-right
385 |4 |`^` |Bitwise XOR |Left-to-right
386 |5 |`\|` |Bitwise OR |Left-to-right
387 |6 |`<` |Less than |Left-to-right
388 |6 |`<=` |Less than or equal to |Left-to-right
389 |6 |`>` |Greater than |Left-to-right
390 |6 |`>=` |Greater than or equal to |Left-to-right
391 |7 |`==` |Equal to |Left-to-right
392 |7 |`!=` |Not equal to |Left-to-right
393 |8 |`&&` |Logical AND |Left-to-right
394 |9 |`\|\|` |Logical OR |Left-to-right
395 |===
396 +
397 Parentheses are supported to bypass the default order.
398 +
399 IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators
400 (`&` and `|`) in 'EXPR' take precedence over relational operators (`<`,
401 `<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2`
402 is _true_ while the equivalent C{nbsp}expression is _false_.
403 +
404 The arithmetic operators are :not: supported.
405 +
406 LTTng first casts all integer constants and fields to signed 64-bit
407 integers. The representation of negative integers is two's complement.
408 This means that, for example, the signed 8-bit integer field 0xff (-1)
409 becomes 0xffffffffffffffff (still -1) once casted.
410 +
411 Before a bitwise operator is applied, LTTng casts all its operands to
412 unsigned 64-bit integers, and then casts the result back to a signed
413 64-bit integer. For the bitwise NOT operator, it's the equivalent of
414 this C{nbsp}expression:
415 +
416 [source,c]
417 ----
418 (int64_t) ~((uint64_t) val)
419 ----
420 +
421 For the binary bitwise operators, it's the equivalent of those
422 C{nbsp}expressions:
423 +
424 [source,c]
425 ----
426 (int64_t) ((uint64_t) lhs >> (uint64_t) rhs)
427 (int64_t) ((uint64_t) lhs << (uint64_t) rhs)
428 (int64_t) ((uint64_t) lhs & (uint64_t) rhs)
429 (int64_t) ((uint64_t) lhs ^ (uint64_t) rhs)
430 (int64_t) ((uint64_t) lhs | (uint64_t) rhs)
431 ----
432 +
433 If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
434 not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
435
436 'EXPR' examples:
437
438 ----------------------------
439 msg_id == 23 && size >= 2048
440 ----------------------------
441
442 -------------------------------------------------
443 $ctx.procname == "lttng*" && (!flag || poel < 34)
444 -------------------------------------------------
445
446 ---------------------------------------------------------
447 $app.my_provider:my_context == 17.34e9 || some_enum >= 14
448 ---------------------------------------------------------
449
450 ---------------------------------------
451 $ctx.cpu_id == 2 && filename != "*.log"
452 ---------------------------------------
453
454 ------------------------------------------------
455 eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
456 ------------------------------------------------
457
458
459 Migration from a recording event rule specification
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461 Since LTTng{nbsp}2.13, what this manual page documents is the standard,
462 common way to specify an LTTng event rule.
463
464 With the man:lttng-enable-event(1) command, you also specify an event
465 rule, but with deprecated options and arguments.
466
467 The following table shows how to translate from the
468 man:lttng-enable-event(1) options and arguments to the common event
469 rule specification options:
470
471 [options="header"]
472 |===
473 |Recording event rule option(s)/argument(s) |Common event rule option(s)
474
475 |nloption:--kernel |option:--domain=++kernel++
476 |nloption:--userspace |option:--domain=++user++
477 |nloption:--jul |option:--domain=++jul++
478 |nloption:--log4j |option:--domain=++log4j++
479 |nloption:--python |option:--domain=++python++
480 |nloption:--tracepoint (with nloption:--kernel/nloption:--userspace) |option:--type=++tracepoint++ or no option:--type option
481 |nloption:--tracepoint (with nloption:--jul/nloption:--log4j/nloption:--python) |option:--type=++logging++ or no option:--type option
482 |nloption:--syscall |option:--type=++syscall++ or option:--type=++syscall:entry+exit++
483 |nloption:--probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++kprobe++, option:--location='LOC', and option:--event-name='RECORDNAME'
484 |nloption:--userspace-probe='LOC' and 'RECORDNAME' (non-option) |option:--type=++uprobe++, option:--location='LOC', and option:--event-name='RECORDNAME'
485 |nloption:--function='LOC' and 'RECORDNAME' (non-option) |Not available as of LTTng{nbsp}{lttng_version}
486 |'NAME' (non-option) |option:--name='NAME'
487 |nloption:--all |option:--name=++\'*\'++ or no option:--name option
488 |nloption:--exclude=__XNAME__[++,++__XNAME__]... |option:--exclude-name='XNAME' for each 'XNAME'
489 |nloption:--loglevel='LOGLEVEL' |option:--log-level=__LOGLEVEL__++..++
490 |nloption:--loglevel-only='LOGLEVEL' |option:--log-level=__LOGLEVEL__
491 |nloption:--filter='EXPR' |option:--filter='EXPR'
492 |===
493
494
495 OPTIONS
496 -------
497 Tracing domain
498 ~~~~~~~~~~~~~~
499 option:-d 'DOMAIN', option:--domain='DOMAIN'::
500 Only match events which LTTng creates in the tracing domain
501 'DOMAIN'.
502 +
503 'DOMAIN' is one of:
504 +
505 --
506 `kernel`:::
507 Linux kernel
508 `user`:::
509 `userspace`:::
510 User space tracing
511 `jul`:::
512 `java.util.logging`
513 `log4j`:::
514 Apache log4j
515 `python`:::
516 Python
517 --
518 +
519 This option is mandatory.
520
521
522 Instrumentation point type condition
523 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
524 See the <<inst-point-type-cond,Instrumentation point type condition>>
525 section above.
526
527 option:-E 'NAME', option:--event-name='NAME'::
528 With the option:--type=++kprobe++ or option:--type=++uprobe++
529 option, set the name of the emitted events to 'NAME' instead of the
530 'LOC' argument of the option:--location='LOC' option.
531 +
532 Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may
533 change in the future.
534
535 option:-L 'LOC', option:--location='LOC'::
536 With the option:--type=++kprobe++ option:::
537 Set the location of the Linux kprobe to insert to 'LOC'.
538 +
539 'LOC' is one of:
540 +
541 * An address (`0x` hexadecimal prefix supported).
542 * A symbol name.
543 * A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format).
544
545 With the option:--type=++uprobe++ option:::
546 Set the location of the user space probe to insert to 'LOC'.
547 +
548 'LOC' is one of:
549 +
550 \[++elf:++]__PATH__++:++__SYMBOL__::::
551 An available symbol within a user space application or library.
552 +
553 --
554 'PATH'::
555 Application or library path.
556 +
557 One of:
558 +
559 * An absolute path.
560 * A relative path.
561 * The name of an application as found in the directories listed in the
562 `PATH` environment variable.
563
564 'SYMBOL'::
565 Symbol name of the function of which to instrument the entry.
566 +
567 'SYMBOL' can be any defined code symbol in the output of the man:nm(1)
568 command, including with its nloption:--dynamic option, which lists
569 dynamic symbols.
570 --
571 +
572 As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
573 specifying it, but this default may change in the future.
574 +
575 Examples:
576 +
577 * `/usr/lib/libc.so.6:malloc`
578 * `./myapp:createUser`
579 * `elf:httpd:ap_run_open_htaccess`
580
581 ++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__::::
582 A SystemTap User-level Statically Defined Tracing (USDT) probe
583 within a user space application or library.
584 +
585 --
586 'PATH'::
587 Application or library path.
588 +
589 This can be:
590 +
591 * An absolute path.
592 * A relative path.
593 * The name of an application as found in the directories listed in the
594 `PATH` environment variable.
595
596 'PROVIDER'::
597 'NAME'::
598 USDT provider and probe names.
599 +
600 For example, with the following USDT probe:
601 +
602 [source,c]
603 ----
604 DTRACE_PROBE2("server", "accept_request",
605 request_id, ip_addr);
606 ----
607 +
608 The provider/probe name pair is `server:accept_request`.
609 --
610 +
611 Example: `sdt:./build/server:server:accept_request`
612
613 option:-t 'TYPE', option:--type='TYPE'::
614 Only match events which LTTng creates from an instrumentation point
615 having the type 'TYPE'.
616 +
617 'TYPE' is one of:
618 +
619 --
620 `tracepoint`::
621 LTTng tracepoint.
622 +
623 Only available with the option:--domain=++kernel++ and
624 option:--domain=++user++ options.
625 +
626 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
627 point type of the Linux kernel and user space tracing domains, but this
628 may change in the future.
629
630 `logging`::
631 Logging statement.
632 +
633 Only available with the option:--domain=++jul++,
634 option:--domain=++log4j++, and option:--domain=++python++ options.
635 +
636 As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
637 point type of the `java.util.logging`, Apache log4j, and Python tracing
638 domains, but this may change in the future.
639
640 `syscall`::
641 As of LTTng{nbsp}{lttng_version}, equivalent to
642 `syscall:entry+exit`, but this default may change in the future.
643 +
644 Only available with the option:--domain=++kernel++ option.
645
646 `syscall:entry`::
647 Linux system call entry.
648 +
649 Only available with the option:--domain=++kernel++ option.
650
651 `syscall:exit`::
652 Linux system call exit.
653 +
654 Only available with the option:--domain=++kernel++ option.
655
656 `syscall:entry+exit`::
657 Linux system call entry and exit (two distinct instrumentation
658 points).
659 +
660 Only available with the option:--domain=++kernel++ option.
661
662 `kprobe`::
663 Linux kprobe.
664 +
665 Only available with the option:--domain=++kernel++ option.
666 +
667 You must specify the location of the kprobe to insert with the
668 option:--location option.
669 +
670 You may specify the name of the emitted events with the
671 option:--event-name option.
672
673 `uprobe` or `userspace-probe`::
674 Linux user space probe.
675 +
676 Only available with the option:--domain=++kernel++ option.
677 +
678 You must specify the location of the user space probe to insert with the
679 option:--location option.
680 +
681 You may specify the name of the emitted events with the
682 option:--event-name option.
683 --
684
685
686 Event name condition
687 ~~~~~~~~~~~~~~~~~~~~
688 See the <<event-name-cond,Event name condition>> section above.
689
690 option:-n 'NAME', option:--name='NAME'::
691 Only match events of which 'NAME' matches:
692 +
693 --
694 With the option:--domain=++kernel++ or option:--domain=++user++ option, with the option:--type=++tracepoint++ option or without the option:--type option:::
695 The full name of the LTTng tracepoint.
696
697 With the option:--domain=++jul++, option:--domain=++log4j++, or option:--domain=++python++ option:::
698 The Java or Python logger name.
699
700 With the option:--domain=++kernel++ option and one of the option:--type=++syscall++, option:--type=++syscall:entry++, option:--type=++syscall:exit++, and option:--type=++syscall:entry+exit++ options:::
701 The name of the system call, without any `sys_` prefix.
702 --
703 +
704 This option is :not: available with the option:--type=++kprobe++ and
705 option:--type=++uprobe++ options.
706 +
707 As of LTTng{nbsp}{lttng_version}, not specifying this option is
708 equivalent to specifying option:--name=++\'*\'++ (when it applies), but
709 this default may change in the future.
710
711 option:-x 'XNAME', option:--exclude='XNAME'::
712 Only match events of which 'XNAME' does :not: match the full name of
713 the LTTng user space tracepoint.
714 +
715 Only available with the option:--domain=++user++ option.
716
717 'NAME' and 'XNAME' are globbing patterns: the `*` character means
718 ``match anything''. To match a literal `*` character, use :escwc:.
719
720
721 Instrumentation point log level condition
722 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
723 See the <<inst-point-log-level-cond,Instrumentation point log level
724 condition>> section above.
725
726 option:-l 'LOGLEVELSPEC', option:--log-level='LOGLEVELSPEC'::
727 Only match events of which the log level of the LTTng tracepoint or
728 logging statement is, depending on the format of 'LOGLEVELSPEC':
729 +
730 --
731 __LOGLEVEL__++..++::
732 At least as severe as 'LOGLEVEL'.
733
734 'LOGLEVEL'::
735 Exactly 'LOGLEVEL'.
736
737 ++..++::
738 Anything.
739 --
740 +
741 This option is :not: available with the option:--domain=++kernel++
742 option.
743 +
744 As of LTTng{nbsp}{lttng_version}, not specifying this option is
745 equivalent to specifying option:--log-level=++..++ (when it applies),
746 but this default may change in the future.
747
748
749 Event payload and context filter condition
750 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
751 See the <<filter-cond,Event payload and context filter condition>>
752 section above.
753
754 option:-f 'EXPR', option:--filter='EXPR'::
755 Only match events of which 'EXPR', which can contain references to
756 event payload and current context fields, is _true_.
757 +
758 This option is only available with the following options:
759 +
760 * option:--type=++tracepoint++
761 * option:--type=++syscall++
762 * option:--type=++syscall:entry++
763 * option:--type=++syscall:exit++
764 * option:--type=++syscall:entry+exit++
765
766
767 include::common-footer.txt[]
768
769
770 SEE ALSO
771 --------
772 man:lttng(1),
773 man:lttng-add-trigger(1),
774 man:lttng-list(1),
775 man:lttng-concepts(7)
This page took 0.047073 seconds and 4 git commands to generate.