X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-event.1.txt;h=526266fe145cf2ee46db1fe94ca7a01388e6b748;hp=b6141b25847a873b4c87a6c997161895c23f8688;hb=f5511eeafdb40b9589306519633566c3be48756c;hpb=f69e7997198da92ea89cf67003c52d15b40099c4 diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index b6141b258..526266fe1 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -1,284 +1,339 @@ lttng-enable-event(1) ===================== +:revdate: 3 May 2021 NAME ---- -lttng-enable-event - Create or enable LTTng event rules +lttng-enable-event - Create or enable LTTng recording event rules SYNOPSIS -------- -Create or enable Linux kernel event rules: +Create or enable one or more recording event rules to match Linux kernel +tracepoint or system call events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel - [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall] - [option:--filter='EXPR'] [option:--session='SESSION'] - [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']... +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel [option:--tracepoint | option:--syscall] + (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR'] + [option:--session='SESSION'] [option:--channel='CHANNEL'] -Create or enable an "all" Linux kernel event rule: +Create or enable a recording event rule to match Linux kernel events +created from a dynamic instrumentation point: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel + (option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME' [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] -Create or enable application event rules: +Create or enable one or more recording event rules to match +user space tracepoint events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* - (option:--userspace | option:--jul | option:--log4j | option:--python) - [option:--filter='EXPR'] [option:--exclude='EVENT'[,'EVENT']...] - [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] - [option:--session='SESSION'] [option:--channel='CHANNEL'] (option:--all | 'EVENT'[,'EVENT']...) +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--userspace [option:--tracepoint] + (option:--all | 'NAME'[,'NAME']...) [option:--exclude='XNAME'[,'XNAME']...] + [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] + [option:--session='SESSION'] [option:--channel='CHANNEL'] +Create or enable one or more recording event rules to match +Java/Python logging events: + +[verse] +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python) + [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...) + [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] + [option:--session='SESSION'] [option:--channel='CHANNEL'] DESCRIPTION ----------- -The `lttng enable-event` command can create a new event rule, or enable -one or more existing and disabled ones. - -An event rule created by `lttng enable-event` is a set of conditions -that must be satisfied in order for an actual event to be emitted by -an LTTng tracer when the execution of an application or the Linux kernel -reaches an event source (tracepoint, system call, dynamic probe). -Event sources can be listed with the man:lttng-list(1) command. - -The man:lttng-disable-event(1) command can be used to disable -existing event rules. - -Event rules are always assigned to a channel when they are created. If -the option:--channel option is omitted, a default channel named -`channel0` is used (and created automatically if it does not exist for -the specified domain in the selected tracing session). - -If the option:--session option is omitted, the chosen channel is picked -from the current tracing session. - -Events can be enabled while tracing is active -(use man:lttng-start(1) to make a tracing session active). - - -Event source types -~~~~~~~~~~~~~~~~~~ -Four types of event sources are available in the Linux kernel tracing -domain (option:--kernel option): - -Tracepoint (option:--tracepoint option; default):: - A Linux kernel tracepoint, that is, a static instrumentation point - placed in the kernel source code. Standard tracepoints are designed - and placed in the source code by developers and record useful - payload fields. - -Dynamic probe (option:--probe option):: - A Linux kernel kprobe, that is, an instrumentation point placed - dynamically in the compiled kernel code. Dynamic probe events do not - record any payload field. - -Function probe (option:--function option):: - A Linux kernel kretprobe, that is, two instrumentation points placed - dynamically where a function is entered and where it returns in the - compiled kernel code. Function probe events do not record any - payload field. - -System call (option:--syscall option):: - A Linux kernel system call. Two instrumentation points are - statically placed where a system call function is entered and where - it returns in the compiled kernel code. System call event sources - record useful payload fields. - -The application tracing domains (option:--userspace, option:--jul, -option:--log4j, or option:--python options) only support tracepoints. -In the cases of the JUL, Apache log4j, and Python domains, the event -names correspond to _logger_ names. - - -Understanding event rule conditions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When creating an event rule with `lttng enable-event`, conditions are -specified using options. The logical conjunction (logical AND) of all -those conditions must be true when an event source is reached by an -application or by the Linux kernel in order for an actual event -to be emitted by an LTTng tracer. - -Any condition that is not explicitly specified on creation is considered -a _don't care_. - -For example, consider the following commands: - -[role="term"] ----- -$ lttng enable-event --userspace hello:world -$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO ----- +The `lttng enable-event` command does one of: -Here, two event rules are created. The first one has a single condition: -the tracepoint name must match `hello:world`. The second one has two -conditions: - -* The tracepoint name must match `hello:world`, _and_ -* The tracepoint's defined log level must be at least as severe as - the `TRACE_INFO` level. - -In this case, the second event rule is pointless because the first one -is more general: it does not care about the tracepoint's log level. -If an event source matching both event rules is reached by the -application's execution, only one event is emitted. - -The available conditions for the Linux kernel domain are: - -* Tracepoint/system call name ('EVENT' argument with - option:--tracepoint or option:--syscall options) or - dynamic probe/function name/address - (option:--probe or option:--function option's argument) which must - match event source's equivalent. -+ -You can use `*` characters at any place in the tracepoint or system -call name as wildcards to match zero or more characters. To use a -literal `*` character, use :escwc:. - -* Filter expression (option:--filter option) executed against the - dynamic values of event fields at execution time that must evaluate - to true. See the <> section - below for more information. - -The available conditions for the application domains are: - -* Tracepoint name ('EVENT' with option:--tracepoint option) which must - match event source's equivalent. -+ -You can use `*` characters at any place in the tracepoint name as -wildcards to match zero or more characters. To use a literal `*` -character, use :escwc:. When you create an event rule with a tracepoint -name containing a wildcard, you can exclude specific tracepoint names -from the match with the option:--exclude option. - -* Filter expression (option:--filter option) executed against the - dynamic values of event fields at execution time that must evaluate - to true. See the <> section - below for more information. -* Event's log level that must be at least as severe as a given - log level (option:--loglevel option) or match exactly a given log - level (option:--loglevel-only option). - -When using `lttng enable-event` with a set of conditions that does not -currently exist for the chosen tracing session, domain, and channel, -a new event rule is created. Otherwise, the existing event rule is -enabled if it is currently disabled -(see man:lttng-disable-event(1)). - -The option:--all option can be used alongside the option:--tracepoint -or option:--syscall options. When this option is used, no 'EVENT' -argument must be specified. This option defines a single event rule -matching _all_ the possible events of a given tracing domain for the -chosen channel and tracing session. It is the equivalent of an 'EVENT' -argument named `*` (wildcard). - - -[[filter-syntax]] -Filter expression syntax -~~~~~~~~~~~~~~~~~~~~~~~~ -Filter expressions can be specified with the option:--filter option -when creating a new event rule. If the filter expression evaluates -to true when executed against the dynamic values of an event's fields -when tracing, the filtering condition passes. - -NOTE: Make sure to **single-quote** the filter expression when running -the command from a shell, as filter expressions typically include -characters having a special meaning for most shells. - -The filter expression syntax is very similar to C language conditional -expressions (expressions that can be evaluated by an `if` statement). - -The following logical operators are supported: - -[width="40%",options="header"] -|===================================== -| Name | Syntax -| Logical negation (NOT) | `!a` -| Logical conjunction (AND) | `a && b` -| Logical disjunction (OR) | `a \|\| b` -|===================================== - -The following comparison operators/relational operators are supported: - -[width="40%",options="header"] -|==================================== -| Name | Syntax -| Equal to | `a == b` -| Not equal to | `a != b` -| Greater than | `a > b` -| Less than | `a < b` -| Greater than or equal to | `a >= b` -| Less than or equal to | `a <= b` -|==================================== - -The arithmetic and bitwise operators are :not: supported. - -The precedence table of the operators above is the same as the one of -the C language. Parentheses are supported to bypass this. - -The dynamic value of an event field is read by using its name as -a C identifier. - -The dynamic value of a statically-known context field is read by -prefixing its name with `$ctx.`. Statically-known context fields are -context fields added to channels without the `$app.` prefix using the -man:lttng-add-context(1) command. +* Create one or more recording event rules. -The dynamic value of an application-specific context field is read by -prefixing its name with `$app.` (follows the format used to add such a -context field with the man:lttng-add-context(1) command). +* Enable one or more disabled recording event rules. ++ +See the <> section +below. -When a comparison includes a non existent event field, the whole filter -expression evaluates to false (the event is discarded). +See man:lttng-concepts(7) to learn more about instrumentation points, +events, recording event rules, and event records. -C integer and floating point number constants are supported, as well as -literal strings between double quotes (`"`). You can use `*` characters -at any place in a literal string as wildcards to match zero or more -characters. To use a literal `*` character, use :escwc:. +The recording event rule(s) to create or enable belong to: -LTTng-UST enumeration fields can be compared to integer values (fields -or constants). +With the option:--session='SESSION' option:: + The tracing session named 'SESSION'. -NOTE: Although it is possible to filter the process ID of an event when -the `pid` context has been added to its channel using, for example, -`$ctx.pid == 2832`, it is recommended to use the PID tracker instead, -which is much more efficient (see man:lttng-track(1)). +Without the option:--session option:: + The current tracing session (see man:lttng-concepts(7) to learn more + about the current tracing session). -Examples: +With the option:--channel='CHANNEL' option:: + The channel named 'CHANNEL'. ----------------------------- -msg_id == 23 && size >= 2048 ----------------------------- +Without the option:--channel option:: + The channel named `channel0`. ++ +If such a channel doesn't exist, the `enable-event` automatically +creates it. -------------------------------------------------- -$ctx.procname == "lttng*" && (!flag || poel < 34) -------------------------------------------------- +List the recording event rules of a specific tracing session +and/or channel with the man:lttng-list(1) and man:lttng-status(1) +commands. ---------------------------------------------------------- -$app.my_provider:my_context == 17.34e9 || some_enum >= 14 ---------------------------------------------------------- +Disable an enabled recording event rule with the +man:lttng-disable-event(1) command. + + +Overview of recording event rule conditions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +For LTTng to emit and record an event{nbsp}__E__,{nbsp}__E__ must +satisfy *all* the conditions of a recording event rule{nbsp}__ER__, that +is: + +Explicit conditions:: + You set the following conditions when you create or + enable{nbsp}__ER__ with the `enable-event` command: ++ +-- +* The instrumentation point type from which LTTng creates{nbsp}__E__ + has a specific type. ++ +See the <> +section below. + +* A pattern matches the name of{nbsp}__E__ while another pattern + doesn't. ++ +See the <> section below. + +* The log level of the instrumentation point from which LTTng + creates{nbsp}__E__ is at least as severe as some value, or is exactly + some value. ++ +See the <> +section below. + +* The fields of the payload of{nbsp}__E__ and the current context fields + satisfy a filter expression. ++ +See the <> +section below. +-- + +Implicit conditions:: ++ +-- +* _ER_ itself is enabled. ++ +A recording event rule is enabled on creation. ++ +Enable a disabled recording event rule with the `enable-event` command. + +* The channel to which{nbsp}__ER__ is attached is enabled. ++ +A channel is enabled on creation. ++ +Enable a disabled channel with the man:lttng-enable-channel(1) command. + +* The tracing session of{nbsp}__ER__ is active (started). ++ +A tracing session is inactive (stopped) on creation. ++ +Start an inactive tracing session with the man:lttng-start(1) command. + +* The process for which LTTng creates{nbsp}__E__ is allowed to record + events. ++ +All processes are allowed to record events on tracing session +creation. ++ +Use the man:lttng-track(1) and man:lttng-untrack(1) commands to select +which processes are allowed to record events based on specific process +attributes. +-- + +The dedicated command-line options of most conditions are optional: if +you don't specify the option, the associated condition is always +satisfied. + + +[[inst-point-type-cond]] +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the instrumentation point type condition +of a recording event rule if the instrumentation point from which LTTng +creates{nbsp}__E__ is: + +For the Linux kernel tracing domain (option:--kernel option):: + With the option:--tracepoint option or without any other instrumentation point type option::: + An LTTng kernel tracepoint, that is, a statically defined point + in the source code of the kernel image or of a kernel module + with LTTng kernel tracer macros. ++ +As of LTTng{nbsp}{lttng_version}, this is the default instrumentation +point type of the Linux kernel tracing domain, but this may change in +the future. ++ +List the available Linux kernel tracepoints with `lttng list --kernel`. +See man:lttng-list(1) to learn more. + + With the option:--syscall option::: + The entry and exit of a Linux kernel system call. ++ +List the available Linux kernel system call instrumentation points with +`lttng list --kernel --syscall`. See man:lttng-list(1) to learn more. + + With the option:--probe option::: + A Linux kprobe, that is, a single probe dynamically placed in + the compiled kernel code. ++ +The argument of the option:--probe option is the location of the +kprobe to insert, either a symbol or a +memory address, while 'RECORDNAME' is the name of the record +of{nbsp}__E__ (see the <> section below). ++ +The payload of a Linux kprobe event is empty. + + With the option:--userspace-probe option::: + A Linux user space probe, that is, a single probe dynamically + placed at the entry of a compiled user space application/library + function through the kernel. ++ +The argument of the option:--userspace-probe option is the location +of the user space probe to insert, one of: ++ +-- +* A path and symbol (ELF method). +* A path, provider name, and probe name (SystemTap User-level Statically + Defined Tracing (USDT) method; a DTrace-style marker). ++ +As of LTTng{nbsp}{lttng_version}, LTTng only supports USDT probes which +are :not: reference-counted. +-- ++ +'RECORDNAME' is the name of the record of{nbsp}__E__ (see the +<> section below). ++ +The payload of a Linux user space probe event is empty. + + With the option:--function option::: + A Linux kretprobe, that is, two probes dynamically placed at the + entry and exit of a function in the compiled kernel code. ++ +The argument of the option:--function option is the location of the +Linux kretprobe to insert, either a symbol or +a memory address, while 'RECORDNAME' is the name of the record +of{nbsp}__E__ (see the <> section below). ++ +The payload of a Linux kretprobe event is empty. + +For the user space tracing domain (option:--userspace option):: + With or without the option:--tracepoint option::: + An LTTng user space tracepoint, that is, a statically defined + point in the source code of a C/$$C++$$ application/library with + LTTng user space tracer macros. ++ +As of LTTng{nbsp}{lttng_version}, this is the default and sole +instrumentation point type of the user space tracing domain, but this +may change in the future. ++ +List the available user space tracepoints with `lttng list --userspace`. +See man:lttng-list(1) to learn more. + +For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains:: + With or without the option:--tracepoint option::: + A logging statement. ++ +As of LTTng{nbsp}{lttng_version}, this is the default and sole +instrumentation point type of the `java.util.logging`, Apache log4j, and +Python tracing domains, but this may change in the future. ++ +List the available Java and Python loggers with `lttng list --jul`, +`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1) +to learn more. + + +[[event-name-cond]] +Event name condition +~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the event name condition of a recording +event rule{nbsp}__ER__ if the two following statements are true: + +* You specify the option:--all option or, depending on the + instrumentation type condition (see the + <> section + above) of{nbsp}__ER__, 'NAME' matches: ++ +-- +LTTng tracepoint:: + The full name of the tracepoint from which LTTng creates{nbsp}__E__. ++ +Note that the full name of a user space tracepoint is +__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider +name and __NAME__ is the tracepoint name. + +Logging statement:: + The name of the Java or Python logger from which LTTng + creates{nbsp}__E__. + +Linux system call:: + The name of the system call, without any `sys_` prefix, from which + LTTng creates{nbsp}__E__. +-- + +* You don't specify the option:--exclude=__XNAME__[++,++__XNAME__]... + option or, depending on the instrumentation type condition + of{nbsp}__ER__, none of the 'XNAME' arguments matches the full name of + the user space tracepoint from which LTTng creates{nbsp}__E__. ++ +The option:--exclude option is only available with the option:--userspace +option. + +This condition is only meaningful for the LTTng tracepoint, logging +statement, and Linux system call instrumentation point types: it's +always satisfied for the other types. + +In all cases, 'NAME' and 'XNAME' are globbing patterns: the `*` +character means ``match anything''. To match a literal `*` character, +use :escwc:. To match a literal `,` character, use +:esccomma:. + +IMPORTANT: Make sure to **single-quote** 'NAME' and 'XNAME' when they +contain the `*` character and when you run the `enable-event` command +from a shell. + +With the LTTng tracepoint, logging statement, and Linux system call +instrumentation point types, the `enable-event` command creates or +enables one independent recording event rule per 'NAME' argument +(non-option, comma-separated). With the option:--all option, the +`enable-event` command creates or enables a single recording event rule. -------------------- -filename != "*.log" -------------------- +[[inst-point-log-level-cond]] +Instrumentation point log level condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the instrumentation point log level +condition of a recording event rule if either: -[[log-levels]] -Log levels -~~~~~~~~~~ -Tracepoints and log statements in applications have an attached log -level. Application event rules can contain a _log level_ condition. +* The option:--loglevel and option:--loglevel-only options are + missing. -With the option:--loglevel option, the event source's log level must -be at least as severe as the option's argument. With the -option:--loglevel-only option, the event source's log level must match -the option's argument. +* The log level of the LTTng user space tracepoint or logging statement + which creates{nbsp}__E__ is: + With the option:--loglevel='LOGLEVEL' option:: + At least as severe as 'LOGLEVEL'. -The available log levels are: + With the option:--loglevel-only='LOGLEVEL' option:: + Exactly 'LOGLEVEL'. -User space domain (option:--userspace option):: +This condition is only meaningful for the LTTng user space tracepoint +and logging statement instrumentation point types: it's always satisfied +for other types. + +The available values of 'LOGLEVEL' are, depending on the tracing domain, +from the most to the least severe: + +User space (option:--userspace option):: Shortcuts such as `system` are allowed. + * `TRACE_EMERG` (0) @@ -297,7 +352,7 @@ User space domain (option:--userspace option):: * `TRACE_DEBUG_LINE` (13) * `TRACE_DEBUG` (14) -`java.util.logging` domain (option:--jul option):: +`java.util.logging` (option:--jul option):: Shortcuts such as `severe` are allowed. + * `JUL_OFF` (`INT32_MAX`) @@ -310,7 +365,7 @@ User space domain (option:--userspace option):: * `JUL_FINEST` (300) * `JUL_ALL` (`INT32_MIN`) -Apache log4j domain (option:--log4j option):: +Apache log4j (option:--log4j option):: Shortcuts such as `severe` are allowed. + * `LOG4J_OFF` (`INT32_MAX`) @@ -322,7 +377,7 @@ Apache log4j domain (option:--log4j option):: * `LOG4J_TRACE` (5000) * `LOG4J_ALL` (`INT32_MIN`) -Python domain (option:--python option):: +Python (option:--python option):: Shortcuts such as `critical` are allowed. + * `PYTHON_CRITICAL` (50) @@ -333,117 +388,478 @@ Python domain (option:--python option):: * `PYTHON_NOTSET` (0) -include::common-cmd-options-head.txt[] +[[filter-cond]] +Event payload and context filter condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +An event{nbsp}__E__ satisfies the event payload and context filter +condition of a recording event rule if the option:--filter='EXPR' +option is missing or if 'EXPR' is _true_. + +'EXPR' can contain references to the payload fields of{nbsp}__E__ and +to the current context fields. + +IMPORTANT: Make sure to **single-quote** 'EXPR' when you run the +`enable-event` command from a shell, as filter expressions typically +include characters having a special meaning for most shells. + +The expected syntax of 'EXPR' is similar to the syntax of a +C{nbsp}language conditional expression (an expression which an `if` +statement can evaluate), but there are a few differences: + +* A _NAME_ expression identifies an event payload field named + _NAME_ (a C{nbsp}identifier). ++ +Use the C{nbsp}language dot and square bracket notations to access +nested structure and array/sequence fields. You can only use a constant, +positive integer number within square brackets. If the index is out of +bounds, 'EXPR' is _false_. ++ +The value of an enumeration field is an integer. ++ +When a field expression doesn't exist, 'EXPR' is _false_. ++ +Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. + +* A ++$ctx.++__TYPE__ expression identifies the statically-known context + field having the type _TYPE_ (a C{nbsp}identifier). ++ +List the available statically-known context field names with the +man:lttng-add-context(1) command. ++ +When a field expression doesn't exist, 'EXPR' is _false_. ++ +Examples: `$ctx.prio`, `$ctx.preemptible`, +`$ctx.perf:cpu:stalled-cycles-frontend`. + +* A ++$app.++__PROVIDER__++:++__TYPE__ expression identifies the + application-specific context field having the type _TYPE_ (a + C{nbsp}identifier) from the provider _PROVIDER_ (a C{nbsp}identifier). ++ +When a field expression doesn't exist, 'EXPR' is _false_. ++ +Example: `$app.server:cur_user`. + +* Compare strings, either string fields or string literals + (double-quoted), with the `==` and `!=` operators. ++ +When comparing to a string literal, the `*` character means ``match +anything''. To match a literal `*` character, use :escwc:. ++ +Examples: `my_field == "user34"`, `my_field == my_other_field`, +`my_field == "192.168.*"`. + +* The precedence table of the operators which are supported in 'EXPR' + is as follows. In this table, the highest precedence is{nbsp}1: ++ +[options="header"] +|=== +|Precedence |Operator |Description |Associativity +|1 |`-` |Unary minus |Right-to-left +|1 |`+` |Unary plus |Right-to-left +|1 |`!` |Logical NOT |Right-to-left +|1 |`~` |Bitwise NOT |Right-to-left +|2 |`<<` |Bitwise left shift |Left-to-right +|2 |`>>` |Bitwise right shift |Left-to-right +|3 |`&` |Bitwise AND |Left-to-right +|4 |`^` |Bitwise XOR |Left-to-right +|5 |`\|` |Bitwise OR |Left-to-right +|6 |`<` |Less than |Left-to-right +|6 |`<=` |Less than or equal to |Left-to-right +|6 |`>` |Greater than |Left-to-right +|6 |`>=` |Greater than or equal to |Left-to-right +|7 |`==` |Equal to |Left-to-right +|7 |`!=` |Not equal to |Left-to-right +|8 |`&&` |Logical AND |Left-to-right +|9 |`\|\|` |Logical OR |Left-to-right +|=== ++ +Parentheses are supported to bypass the default order. ++ +IMPORTANT: Unlike the C{nbsp}language, the bitwise AND and OR operators +(`&` and `|`) in 'EXPR' take precedence over relational operators (`<`, +`<=`, `>`, `>=`, `==`, and `!=`). This means the expression `2 & 2 == 2` +is _true_ while the equivalent C{nbsp}expression is _false_. ++ +The arithmetic operators are :not: supported. ++ +LTTng first casts all integer constants and fields to signed 64-bit +integers. The representation of negative integers is two's complement. +This means that, for example, the signed 8-bit integer field 0xff (-1) +becomes 0xffffffffffffffff (still -1) once casted. ++ +Before a bitwise operator is applied, LTTng casts all its operands to +unsigned 64-bit integers, and then casts the result back to a signed +64-bit integer. For the bitwise NOT operator, it's the equivalent of +this C{nbsp}expression: ++ +[source,c] +---- +(int64_t) ~((uint64_t) val) +---- ++ +For the binary bitwise operators, it's the equivalent of those +C{nbsp}expressions: ++ +[source,c] +---- +(int64_t) ((uint64_t) lhs >> (uint64_t) rhs) +(int64_t) ((uint64_t) lhs << (uint64_t) rhs) +(int64_t) ((uint64_t) lhs & (uint64_t) rhs) +(int64_t) ((uint64_t) lhs ^ (uint64_t) rhs) +(int64_t) ((uint64_t) lhs | (uint64_t) rhs) +---- ++ +If the right-hand side of a bitwise shift operator (`<<` and `>>`) is +not in the [0,{nbsp}63] range, then 'EXPR' is _false_. + +[NOTE] +==== +Use the man:lttng-track(1) and man:lttng-untrack(1) commands to allow or +disallow processes to record LTTng events based on their attributes +instead of using equivalent statically-known context fields in 'EXPR' +like `$ctx.pid`. + +The former method is much more efficient. +==== + +'EXPR' examples: + +---------------------------- +msg_id == 23 && size >= 2048 +---------------------------- + +------------------------------------------------- +$ctx.procname == "lttng*" && (!flag || poel < 34) +------------------------------------------------- + +--------------------------------------------------------- +$app.my_provider:my_context == 17.34e9 || some_enum >= 14 +--------------------------------------------------------- + +--------------------------------------- +$ctx.cpu_id == 2 && filename != "*.log" +--------------------------------------- + +------------------------------------------------ +eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234 +------------------------------------------------ + + +[[er-name]] +Event record name +~~~~~~~~~~~~~~~~~ +When LTTng records an event{nbsp}__E__, the resulting event record has a +name which depends on the instrumentation point type condition (see the +<> section +above) of the recording event rule which matched{nbsp}__E__: + +LTTng tracepoint (option:--kernel/option:--userspace and option:--tracepoint options):: + Full name of the tracepoint from which LTTng creates{nbsp}__E__. ++ +Note that the full name of a user space tracepoint is +__PROVIDER__++:++__NAME__, where __PROVIDER__ is the tracepoint provider +name and __NAME__ is the tracepoint name. + +`java.util.logging` logging statement (option:--jul and option:--tracepoint options):: + `lttng_jul:event` ++ +Such an event record has a string field `logger_name` which contains the +name of the `java.util.logging` logger from which LTTng +creates{nbsp}__E__. + +Apache log4j logging statement (option:--log4j and option:--tracepoint options):: + `lttng_log4j:event` ++ +Such an event record has a string field `logger_name` which contains the +name of the Apache log4j logger from which LTTng creates{nbsp}__E__. + +Python logging statement (option:--python and option:--tracepoint options):: + `lttng_python:event` ++ +Such an event record has a string field `logger_name` which contains the +name of the Python logger from which LTTng creates{nbsp}__E__. + +Linux system call (option:--kernel and option:--syscall options):: + Entry::: + ++syscall_entry_++__NAME__, where _NAME_ is the name of the + system call from which LTTng creates{nbsp}__E__, without any + `sys_` prefix. + + Exit::: + ++syscall_exit_++__NAME__, where _NAME_ is the name of the + system call from which LTTng creates{nbsp}__E__, without any + `sys_` prefix. + +Linux kprobe (option:--kernel and option:--probe options):: +Linux user space probe (option:--kernel and option:--userspace-probe options):: + 'RECORDNAME' (first non-option argument). + +Linux kretprobe (option:--kernel and option:--function options):: + Entry::: + __RECORDNAME__++_entry++ + + Exit::: + __RECORDNAME__++_exit++ + + +[[enable]] +Enable a disabled recording event rule +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The `enable-event` command can enable a disabled recording event rule, +as listed in the output of the man:lttng-list(1) command. + +You may enable a disabled recording event rule regardless of the +activity (started or stopped) of its tracing session (see +man:lttng-start(1) and man:lttng-stop(1)). + +To enable a disabled recording event rule, run the `enable-event` +command with the exact same options and arguments that you used to +create it. In particular, with the option:--filter='EXPR' option, 'EXPR' +must be the exact same string as the one you used on creation. + + +include::common-lttng-cmd-options-head.txt[] -Domain -~~~~~~ +Tracing domain +~~~~~~~~~~~~~~ One of: option:-j, option:--jul:: - Create or enable event rules in the `java.util.logging` - (JUL) domain. + Create or enable recording event rules in the `java.util.logging` + (JUL) tracing domain. option:-k, option:--kernel:: - Create or enable event rules in the Linux kernel domain. + Create or enable recording event rules in the Linux kernel tracing + domain. option:-l, option:--log4j:: - Create or enable event rules in the Apache log4j domain. + Create or enable recording event rules in the Apache log4j tracing + domain. option:-p, option:--python:: - Create or enable event rules in the Python domain. + Create or enable recording event rules in the Python tracing domain. option:-u, option:--userspace:: - Create or enable event rules in the user space domain. + Create or enable recording event rules in the user space tracing + domain. -Target -~~~~~~ +Recording target +~~~~~~~~~~~~~~~~ option:-c 'CHANNEL', option:--channel='CHANNEL':: - Create or enable event rules in the channel named 'CHANNEL' instead - of the default channel name `channel0`. + Create or enable recording event rules attached to the channel named + 'CHANNEL' instead of `channel0`. option:-s 'SESSION', option:--session='SESSION':: - Create or enable event rules in the tracing session named 'SESSION' - instead of the current tracing session. + Create or enable recording event rules in the tracing session named + 'SESSION' instead of the current tracing session. -Event source type -~~~~~~~~~~~~~~~~~ +Instrumentation point type condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> +section above. + +At most one of: + +option:--function='LOC':: + Only match Linux kretprobe events. ++ +Only available with the option:--kernel option. ++ +'LOC' is one of: ++ +-- +* A function address (`0x` hexadecimal prefix supported). +* A function symbol name. +* A function symbol name and an offset + (__SYMBOL__++pass:[+]++__OFFSET__ format). +-- ++ +You must specify the event record name with 'RECORDNAME'. See the +<> section above to learn more. + +option:--probe='LOC':: + Only match Linux kprobe events. ++ +Only available with the option:--kernel option. ++ +'LOC' is one of: ++ +-- +* An address (`0x` hexadecimal prefix supported). +* A symbol name. +* A symbol name and an offset (__SYMBOL__++pass:[+]++__OFFSET__ format). +-- ++ +You must specify the event record name with 'RECORDNAME'. See the +<> section above to learn more. + +option:--userspace-probe='LOC':: + Only match Linux user space probe events. ++ +Only available with the option:--kernel option. ++ +'LOC' is one of: ++ +-- +\[++elf:++]__PATH__++:++__SYMBOL__:: + Probe an available symbol within a user space application or + library. ++ +-- +'PATH':: + Application or library path. ++ One of: ++ +* An absolute path. +* A relative path. +* The name of an application as found in the directories listed in the + `PATH` environment variable. -option:--function='SOURCE':: - Linux kernel kretprobe. Only available with the option:--kernel - domain option. 'SOURCE' is one of: +'SYMBOL':: + Symbol name of the function of which to instrument the entry. + -* Function address (`0x` prefix supported) -* Function symbol -* Function symbol and offset (`SYMBOL+OFFSET` format) +'SYMBOL' can be any defined code symbol in the output of the man:nm(1) +command, including with its nloption:--dynamic option, which lists +dynamic symbols. +-- ++ +As of LTTng{nbsp}{lttng_version}, not specifying `elf:` is equivalent to +specifying it, but this default may change in the future. ++ +Examples: ++ +* `--userspace-probe=/usr/lib/libc.so.6:malloc` +* `--userspace-probe=./myapp:createUser` +* `--userspace-probe=elf:httpd:ap_run_open_htaccess` -option:--probe='SOURCE':: - Linux kernel kprobe. Only available with the option:--kernel - domain option. 'SOURCE' is one of: +++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:: + Use a SystemTap User-level Statically Defined Tracing (USDT) probe + within a user space application or library. ++ +-- +'PATH':: + Application or library path. ++ +This can be: + -* Address (`0x` prefix supported) -* Symbol -* Symbol and offset (`SYMBOL+OFFSET` format) +* An absolute path. +* A relative path. +* The name of an application as found in the directories listed in the + `PATH` environment variable. + +'PROVIDER':: +'NAME':: + USDT provider and probe names. ++ +For example, with the following USDT probe: ++ +[source,c] +---- +DTRACE_PROBE2("server", "accept_request", + request_id, ip_addr); +---- ++ +The provider/probe name pair is `server:accept_request`. +-- ++ +Example: `--userspace-probe=sdt:./build/server:server:accept_request` +-- ++ +You must specify the event record name with 'RECORDNAME'. See the +<> section above to learn more. option:--syscall:: - Linux kernel system call. Only available with the option:--kernel - domain option. + Only match Linux system call events. ++ +Only available with the option:--kernel option. option:--tracepoint:: - Linux kernel or application tracepoint (default). + Only match: ++ +With the option:--kernel or option:--userspace option::: + LTTng tracepoint events. +With the option:--jul, option:--log4j, or option:--python option::: + Logging events. +With the option:--kernel, not specifying any of the instrumentation +point type options is equivalent to specifying the option:--tracepoint +option, but this default may change in the future. -Log level -~~~~~~~~~ -One of: +With the option:--userspace, option:--jul, option:--log4j, and +option:--python options, not specifying the option:--tracepoint option +is equivalent to specifying it, but this default may change in the +future. + + +Event name condition +~~~~~~~~~~~~~~~~~~~~ +See the <> section above. + +option:-a, option:--all:: + Equivalent to a single 'NAME' argument (LTTng tracepoint or logger + name) set to `*` (match anything). ++ +You may :not: use this option with a 'NAME' argument. + +option:-x 'XNAME'[,'XNAME']..., option:--exclude='XNAME'[,'XNAME']...:: + Only match events of which none of the 'XNAME' arguments + matches the full name of the LTTng user space tracepoint. ++ +Only available with the option:--userspace option. ++ +'XNAME' is a globbing pattern: the `*` character means ``match +anything''. To match a literal `*` character, use :escwc:. To match +a literal `,` character, use :esccomma:. + + +Instrumentation point log level condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> section above. + +At most one of: option:--loglevel='LOGLEVEL':: - Add log level condition to the event rule: the event source's - defined log level must be at least as severe as 'LOGLEVEL'. - See the <> section above for the available - log levels. Only available with application domains. + Only match events of which the log level of the LTTng tracepoint or + logging statement is at least as severe as 'LOGLEVEL'. option:--loglevel-only='LOGLEVEL':: - Add log level condition to the event rule: the event source's - defined log level must match 'LOGLEVEL'. See the - <> section above for the available log - levels. Only available with application domains. - - -Filtering and exclusion -~~~~~~~~~~~~~~~~~~~~~~~ -option:-x 'EVENT'[,'EVENT']..., option:--exclude='EVENT'[,'EVENT']...:: - Exclude events named 'EVENT' from the event rule. This option - can be used when the command's 'EVENT' argument contains at least - one wildcard star (`*`) to exclude specific names. 'EVENT' can also - contain wildcard stars. To use a - literal `,` character, use :esccomma:. - Only available with the option:--userspace domain. + Only match events of which the log level of the LTTng tracepoint or + logging statement is exactly 'LOGLEVEL'. + +The instrumentation point log level options above are :not: available +with the option:--kernel option. + + +Event payload and context filter condition +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +See the <> +section above. option:-f 'EXPR', option:--filter='EXPR':: - Add filter expression condition to the event rule. Expression 'EXPR' - must evaluate to true when executed against the dynamic values of - event fields. See the <> - section above for more information. + Only match events of which 'EXPR', which can contain references to + event payload and current context fields, is _true_. -Shortcuts -~~~~~~~~~ -option:-a, option:--all:: - Equivalent to an 'EVENT' argument named `*` (wildcard) when also - using the option:--tracepoint (default) or option:--syscall option. +include::common-lttng-cmd-help-options.txt[] -include::common-cmd-help-options.txt[] +include::common-lttng-cmd-after-options.txt[] -include::common-cmd-footer.txt[] +include::common-footer.txt[] SEE ALSO -------- +man:lttng(1), man:lttng-disable-event(1), -man:lttng(1) +man:lttng-enable-channel(1), +man:lttng-list(1), +man:lttng-start(1), +man:lttng-track(1), +man:lttng-concepts(7)