Fix: build: libcommon fd-tracker dependency is not available
[lttng-tools.git] / doc / man / lttng-event-rule.7.txt
CommitLineData
484b2a0c
PP
1lttng-event-rule(7)
2===================
4ccdbb61 3:revdate: 12 May 2021
484b2a0c
PP
4
5
6NAME
7----
8lttng-event-rule - Common LTTng event rule specification
9
10
11SYNOPSIS
12--------
13Specify an event rule to match Linux kernel tracepoint or system call
14events:
15
16[verse]
26f0c779 17option:--domain=**kernel** option:--type=(**tracepoint** | **syscall**[**:entry**|**:exit**|**pass:[:entry+exit]**])]
484b2a0c
PP
18pass:[[]option:--name='NAME'] [option:--filter='EXPR']
19
20Specify an event rule to match Linux kernel kprobe or user space
21probe events:
22
23[verse]
26f0c779 24option:--domain=**kernel** option:--type=(**kprobe** | **uprobe**) option:--location='LOC'
4ccdbb61 25pass:[[]option:--event-name='EVENTNAME']
484b2a0c
PP
26
27Specify an event rule to match user space tracepoint events:
28
29[verse]
26f0c779 30option:--domain=**user** [option:--type=**tracepoint**] [option:--name='NAME'] [option:--exclude-name='XNAME']...
484b2a0c
PP
31pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
32
33Specify an event rule to match Java/Python logging events:
34
35[verse]
26f0c779 36option:--domain=(**jul** | **log4j** | **python**) [option:--type=**logging**] [option:--name='NAME']
484b2a0c
PP
37pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR']
38
39
40DESCRIPTION
41-----------
42This manual page shows how to specify an LTTng event rule on the command
43line.
44
45As of LTTng{nbsp}{lttng_version}, the command-line options documented
46here only apply to the `event-rule-matches` trigger condition specifier
47(see man:lttng-add-trigger(1)).
48
26f0c779
PP
49See man:lttng-concepts(7) to learn more about instrumentation points,
50events, and event rules.
51
484b2a0c
PP
52[NOTE]
53====
54This manual page only describes the common event rule options. The
55man:lttng(1) commands which require an event rule specification may
56accept or require other options and arguments, depending on the context.
57
58For example, the man:lttng-add-trigger(1) command also accepts
59nloption:--capture options with the `event-rule-matches` trigger
60condition.
61====
62
63
26f0c779
PP
64Overview of event rule condtions
65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
484b2a0c
PP
66For LTTng to emit an event{nbsp}__E__,{nbsp}__E__ must satisfy *all* the
67conditions of an event rule, that is:
68
69* The instrumentation point from which LTTng creates{nbsp}__E__ has a
70 specific type.
71+
72See the <<inst-point-type-cond,Instrumentation point type condition>>
73section below.
74
75* A pattern matches the name of{nbsp}__E__ while another pattern
76 doesn't.
77+
78See 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+
84See the <<inst-point-log-level-cond,Instrumentation point log level
85condition>> section below.
86
87* The fields of the payload of{nbsp}__E__ and the current context fields
88 satisfy a filter expression.
89+
90See the <<filter-cond,Event payload and context filter condition>>
91section below.
92
93The dedicated command-line options of most conditions are optional: if
94you don't specify the option, the associated condition is always
95satisfied.
96
97
98[[inst-point-type-cond]]
99Instrumentation point type condition
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101An event{nbsp}__E__ satisfies the instrumentation point type condition
102of an event rule if the instrumentation point from which LTTng
103creates{nbsp}__E__ is:
104
105For 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+
111As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
112point type of the Linux kernel tracing domain, but this may change in
113the future.
114+
115List the available Linux kernel tracepoints with `lttng list --kernel`.
116See 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+
122List 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+
129You must specify the kprobe location with the option:--location option.
130+
131The 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+
138LTTng{nbsp}{lttng_version} supports the ELF and SystemTap User-level
139Statically Defined Tracing (USDT; a DTrace-style marker) probing
140methods. LTTng only supports USDT probes which are :not:
141reference-counted.
142+
143You must specify the user space probe location with the
144option:--location option.
145+
146The payload of a Linux user space probe event is empty.
147
148For 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+
154As of LTTng{nbsp}{lttng_version}, this is the default and sole
155instrumentation point type of the user space tracing domain, but this
156may change in the future.
157+
158List the available user space tracepoints with `lttng list --userspace`.
159See man:lttng-list(1) to learn more.
160
161For 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+
165As of LTTng{nbsp}{lttng_version}, this is the default and sole
166instrumentation point type of the `java.util.logging`, Apache log4j, and
167Python tracing domains, but this may change in the future.
168+
169List the available Java and Python loggers with `lttng list --jul`,
170`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1)
171to learn more.
172
173
174[[event-name-cond]]
175Event name condition
176~~~~~~~~~~~~~~~~~~~~
177An event{nbsp}__E__ satisfies the event name condition of an event
178rule{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--
186LTTng tracepoint::
187 The full name of the tracepoint from which LTTng creates{nbsp}__E__.
188+
189Note that the full name of a user space tracepoint is
190__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider
191name and __NAME__ is the tracepoint name.
192
193Logging statement::
194 The name of the Java or Python logger from which LTTng
195 creates{nbsp}__E__.
196
197Linux 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+
206The option:--exclude-name option is only available with the
207option:--domain=++user++ option.
208
209This condition is only meaningful for the LTTng tracepoint, logging
210statement, and Linux system call instrumentation point types: it's
211always satisfied for the other types.
212
213In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*`
214character means ``match anything''. To match a literal `*` character,
215use :escwc:.
216
217IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they
218contain the `*` character and when you run an man:lttng(1) command from
219a shell.
220
221As of LTTng{nbsp}{lttng_version}, not specifying the option:--name
222option is equivalent to specifying option:--name=++\'*\'++, but this
223default may change in the future.
224
225
226[[inst-point-log-level-cond]]
227Instrumentation point log level condition
228~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
229An event{nbsp}__E__ satisfies the instrumentation point log level
230condition 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+
235Defaulting to option:--log-level=++..++ when you don't specify the
236option:--log-level option is specific to LTTng{nbsp}{lttng_version} and
237may 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
247As of LTTng{nbsp}{lttng_version}, the ++..++__LOGLEVEL__ and
248__LOGLEVEL__++..++__LOGLEVEL__ formats are :not: supported.
249
250This condition is only meaningful for the LTTng user space tracepoint
251and logging statement instrumentation point types: it's always satisfied
252for other types.
253
254The available values of 'LOGLEVEL' are, depending on the tracing domain,
255from the most to the least severe:
256
257User space (option:--domain=++user++ option)::
484b2a0c 258+
4fc37e3e
PP
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)
484b2a0c
PP
274
275`java.util.logging` (option:--domain=++jul++ option)::
484b2a0c 276+
4fc37e3e
PP
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`)
484b2a0c
PP
286
287Apache log4j (option:--domain=++log4j++ option)::
484b2a0c 288+
4fc37e3e
PP
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`)
484b2a0c
PP
297
298Python (option:--domain=++python++ option)::
484b2a0c 299+
4fc37e3e
PP
300* `CRITICAL` (50)
301* `ERROR` (40)
302* `WARNING` (30)
303* `INFO` (20)
304* `DEBUG` (10)
305* `NOTSET` (0)
484b2a0c
PP
306
307
308[[filter-cond]]
309Event payload and context filter condition
310~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
311An event{nbsp}__E__ satisfies the event payload and context filter
312condition of an event rule if the option:--filter='EXPR' option is
313missing or if 'EXPR' is _true_.
314
4ccdbb61
PP
315This condition is only meaningful for the LTTng tracepoint and Linux
316system call instrumentation point types: it's always satisfied for other
317types.
318
484b2a0c
PP
319'EXPR' can contain references to the payload fields of{nbsp}__E__ and
320to the current context fields.
321
322IMPORTANT: Make sure to **single-quote** 'EXPR' when you run an
323man:lttng(1) command from a shell, as filter expressions typically
324include characters having a special meaning for most shells.
325
326The expected syntax of 'EXPR' is similar to the syntax of a
327C{nbsp}language conditional expression (an expression which an `if`
328statement 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+
333Use the C{nbsp}language dot and square bracket notations to access
334nested structure and array/sequence fields. You can only use a constant,
335positive integer number within square brackets. If the index is out of
336bounds, 'EXPR' is _false_.
337+
338The value of an enumeration field is an integer.
339+
340When a field expression doesn't exist, 'EXPR' is _false_.
341+
342Examples: `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+
347List the available statically-known context field names with the
348man:lttng-add-context(1) command.
349+
350When a field expression doesn't exist, 'EXPR' is _false_.
351+
352Examples: `$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+
359When a field expression doesn't exist, 'EXPR' is _false_.
360+
361Example: `$app.server:cur_user`.
362
363* Compare strings, either string fields or string literals
364 (double-quoted), with the `==` and `!=` operators.
365+
366When comparing to a string literal, the `*` character means ``match
367anything''. To match a literal `*` character, use :escwc:.
368+
369Examples: `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+
397Parentheses are supported to bypass the default order.
398+
399IMPORTANT: 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`
402is _true_ while the equivalent C{nbsp}expression is _false_.
403+
404The arithmetic operators are :not: supported.
405+
406LTTng first casts all integer constants and fields to signed 64-bit
407integers. The representation of negative integers is two's complement.
408This means that, for example, the signed 8-bit integer field 0xff (-1)
409becomes 0xffffffffffffffff (still -1) once casted.
410+
411Before a bitwise operator is applied, LTTng casts all its operands to
412unsigned 64-bit integers, and then casts the result back to a signed
41364-bit integer. For the bitwise NOT operator, it's the equivalent of
414this C{nbsp}expression:
415+
416[source,c]
417----
418(int64_t) ~((uint64_t) val)
419----
420+
421For the binary bitwise operators, it's the equivalent of those
422C{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+
433If the right-hand side of a bitwise shift operator (`<<` and `>>`) is
434not in the [0,{nbsp}63] range, then 'EXPR' is _false_.
435
436'EXPR' examples:
437
438----------------------------
439msg_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------------------------------------------------
455eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
456------------------------------------------------
457
458
459Migration from a recording event rule specification
460~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461Since LTTng{nbsp}2.13, what this manual page documents is the standard,
462common way to specify an LTTng event rule.
463
464With the man:lttng-enable-event(1) command, you also specify an event
465rule, but with deprecated options and arguments.
466
467The following table shows how to translate from the
468man:lttng-enable-event(1) options and arguments to the common event
469rule 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
495OPTIONS
496-------
497Tracing domain
498~~~~~~~~~~~~~~
499option:-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+
519This option is mandatory.
520
521
522Instrumentation point type condition
523~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
524See the <<inst-point-type-cond,Instrumentation point type condition>>
525section above.
526
527option:-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+
532Defaulting to 'LOC' is specific to LTTng{nbsp}{lttng_version} and may
533change in the future.
534
535option:-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+
557One 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)
568command, including with its nloption:--dynamic option, which lists
569dynamic symbols.
570--
571+
572As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to
573specifying it, but this default may change in the future.
574+
575Examples:
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+
589This 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+
600For example, with the following USDT probe:
601+
602[source,c]
603----
604DTRACE_PROBE2("server", "accept_request",
605 request_id, ip_addr);
606----
607+
608The provider/probe name pair is `server:accept_request`.
609--
610+
611Example: `sdt:./build/server:server:accept_request`
612
613option:-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+
623Only available with the option:--domain=++kernel++ and
624option:--domain=++user++ options.
625+
626As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
627point type of the Linux kernel and user space tracing domains, but this
628may change in the future.
629
630`logging`::
631 Logging statement.
632+
633Only available with the option:--domain=++jul++,
634option:--domain=++log4j++, and option:--domain=++python++ options.
635+
636As of LTTng{nbsp}{lttng_version}, this is the default instrumentation
637point type of the `java.util.logging`, Apache log4j, and Python tracing
638domains, 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+
644Only available with the option:--domain=++kernel++ option.
645
646`syscall:entry`::
647 Linux system call entry.
648+
649Only available with the option:--domain=++kernel++ option.
650
651`syscall:exit`::
652 Linux system call exit.
653+
654Only 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+
660Only available with the option:--domain=++kernel++ option.
661
662`kprobe`::
663 Linux kprobe.
664+
665Only available with the option:--domain=++kernel++ option.
666+
667You must specify the location of the kprobe to insert with the
668option:--location option.
669+
670You may specify the name of the emitted events with the
671option:--event-name option.
672
673`uprobe` or `userspace-probe`::
674 Linux user space probe.
675+
676Only available with the option:--domain=++kernel++ option.
677+
678You must specify the location of the user space probe to insert with the
679option:--location option.
680+
681You may specify the name of the emitted events with the
682option:--event-name option.
683--
684
685
686Event name condition
687~~~~~~~~~~~~~~~~~~~~
688See the <<event-name-cond,Event name condition>> section above.
689
690option:-n 'NAME', option:--name='NAME'::
691 Only match events of which 'NAME' matches:
692+
693--
694With 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
697With the option:--domain=++jul++, option:--domain=++log4j++, or option:--domain=++python++ option:::
698 The Java or Python logger name.
699
700With 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+
704This option is :not: available with the option:--type=++kprobe++ and
705option:--type=++uprobe++ options.
706+
707As of LTTng{nbsp}{lttng_version}, not specifying this option is
708equivalent to specifying option:--name=++\'*\'++ (when it applies), but
709this default may change in the future.
710
711option:-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+
715Only 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
721Instrumentation point log level condition
722~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
723See the <<inst-point-log-level-cond,Instrumentation point log level
724condition>> section above.
725
726option:-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+
741This option is :not: available with the option:--domain=++kernel++
742option.
743+
744As of LTTng{nbsp}{lttng_version}, not specifying this option is
745equivalent to specifying option:--log-level=++..++ (when it applies),
746but this default may change in the future.
747
748
749Event payload and context filter condition
750~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
751See the <<filter-cond,Event payload and context filter condition>>
752section above.
753
754option:-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_.
4ccdbb61
PP
757+
758This 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++
484b2a0c
PP
765
766
26f0c779
PP
767include::common-footer.txt[]
768
769
484b2a0c
PP
770SEE ALSO
771--------
772man:lttng(1),
26f0c779 773man:lttng-add-trigger(1),
af1c4164
PP
774man:lttng-list(1),
775man:lttng-concepts(7)
This page took 0.05257 seconds and 4 git commands to generate.