X-Git-Url: https://git.lttng.org/?p=lttng-tools.git;a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-event.1.txt;h=ceb533bd10492f8958ed7b6f9ed2b4506aa25861;hp=2230df059c8c512882efc9666409a290a8ad18d9;hb=0e63136b82364512210f497c60a0cc98a9d57fd7;hpb=03c5529d5cb12b279866d2c3245712a639284ce8 diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 2230df059..ceb533bd1 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -13,7 +13,8 @@ Create or enable Linux kernel event rules: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel - [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall] + [option:--probe='SOURCE' | option:--function='SOURCE' | option:--syscall | + option:--userspace-probe='SOURCE'] [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] 'EVENT'[,'EVENT']... @@ -23,7 +24,7 @@ Create or enable an "all" Linux kernel event rule: *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel option:--all [option:--syscall] [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] -Create or enable application event rules: +Create or enable application/library event rules: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* @@ -39,10 +40,10 @@ 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. +that must be satisfied in order for an actual event to be emitted by an +LTTng tracer when the execution of an application or a library 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. @@ -61,7 +62,7 @@ Events can be enabled while tracing is active Event source types ~~~~~~~~~~~~~~~~~~ -Four types of event sources are available in the Linux kernel tracing +Five types of event sources are available in the Linux kernel tracing domain (option:--kernel option): Tracepoint (option:--tracepoint option; default):: @@ -70,11 +71,20 @@ Tracepoint (option:--tracepoint option; default):: and placed in the source code by developers and record useful payload fields. -Dynamic probe (option:--probe option):: +Dynamic kernel 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. +Dynamic user space probe (option:--userspace-probe option):: + A Linux kernel uprobe, that is, an instrumentation point placed + dynamically in the compiled user space application/library through + the kernel. Dynamic user space probe events do not record any + payload field. ++ +See the <> section for more +information. + 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 @@ -127,18 +137,18 @@ 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. +* Tracepoint/system call name ('EVENT' argument with option:--tracepoint + or option:--syscall options) or dynamic probe/function name/address + (option:--probe, option:--userspace-probe, and option:--function + option's argument) which must match event source's equivalent. + -Wildcard using the `*` character are supported _at the end_ of -tracepoint and system call names. +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 + to true. See the <> section below for more information. The available conditions for the application domains are: @@ -146,14 +156,15 @@ The available conditions for the application domains are: * Tracepoint name ('EVENT' with option:--tracepoint option) which must match event source's equivalent. + -Wildcard using the `*` character are supported _at the end_ of -tracepoint names. When creating an event rule with a tracepoint name -containing a wildcard, specific tracepoint names can be excluded from -the match using the option:--exclude option. +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 + 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 @@ -173,10 +184,10 @@ 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 +[[filter-expr]] +Filter expression +~~~~~~~~~~~~~~~~~ +A filter expression 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. @@ -185,66 +196,125 @@ 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 filter expression syntax is similar to C language conditional +expressions (expressions that can be evaluated by an `if` statement), +albeit with a few differences: -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. +* 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:. ++ +Examples: `32`, `-0x17`, `0755`, `12.34`, ++"a :escbs:"literal string:escbs:""+, `"src/*/*.h"`. -The dynamic value of an event field is read by using its name as -a C identifier. +* The dynamic value of an event field is read by using its name as a C + identifier. ++ +The dot and square bracket notations are available, like in the C +language, to access nested structure and array/sequence fields. +Only a constant, positive integer number can be used within square +brackets. If the index is out of bounds, the whole filter expression +evaluates to false (the event is discarded). ++ +An enumeration field's value is an integer. ++ +When the expression's field does not exist, the whole filter expression +evaluates to false. ++ +Examples: `my_field`, `target_cpu`, `seq[7]`, `msg.user[1].data[2][17]`. -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. +* 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. ++ +When the expression's statically-known context field does not exist, +the whole filter expression evaluates to false. ++ +Examples: `$ctx.prio`, `$ctx.preemptible`, +`$ctx.perf:cpu:stalled-cycles-frontend`. -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). +* 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). ++ +When the expression's application-specific context field does not exist, +the whole filter expression evaluates to false. ++ +Example: `$app.server:cur_user`. + +The following precedence table shows the operators which are supported +in a filter expression. In this table, the highest precedence is 1. +Parentheses are supported to bypass the default order. + +IMPORTANT: Unlike the C language, the `lttng enable-event` filter +expression syntax's bitwise AND and OR operators (`&` and `|`) take +precedence over relational operators (`<`, `<=`, `>`, `>=`, `==`, and +`!=`). This means the filter expression `2 & 2 == 2` is true while the +equivalent C expression is false. + +[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 +|=== + +The arithmetic operators are :not: supported. + +All integer constants and fields are first casted 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, all its operands are casted to +unsigned 64-bit integers, and the result is casted back to a signed +64-bit integer. For the bitwise NOT operator, it is the equivalent of +this C expression: + +[source,c] +---- +(int64_t) ~((uint64_t) val) +---- -When a comparison includes a non existent event field, the whole filter -expression evaluates to false (the event is discarded). +For the binary bitwise operators, it is the equivalent of those C +expressions: -C integer and floating point number constants are supported, as well as -literal strings between double quotes (`"`). Literal strings can contain -a wildcard character (`*`) at the end to match more than one string. -This wildcard can be escaped using :escwc:. +[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) +---- -LTTng-UST enumeration fields can be compared to integer values (fields -or constants). +If the right-hand side of a bitwise shift operator (`<<` and `>>`) is +not in the [0,{nbsp}63] range, the whole filter expression evaluates to +false. 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)). -Examples: +Filter expression examples: ---------------------------- msg_id == 23 && size >= 2048 @@ -258,6 +328,14 @@ $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 +------------------------------------------------ + [[log-levels]] Log levels @@ -327,6 +405,24 @@ Python domain (option:--python option):: * `PYTHON_NOTSET` (0) +[[userspace-probe]] +Dynamic user space probes +~~~~~~~~~~~~~~~~~~~~~~~~~ +With the option:--userspace-probe option, you can instrument function +entries of any user space binary (application or library) using either +an available symbol name or a SystemTap User-level Statically Defined +Tracing (USDT, a DTrace-style marker) probe's provider and probe names. +As of this version, only USDT probes that are :not: surrounded by a +reference counter (semaphore) are supported. + +The option:--userspace-probe option must be specified with the +option:--kernel option because it uses Linux's uprobe feature to +dynamically instrument a user space application or library. + +As of this version, dynamic probe events do not record any payload +field. + + include::common-cmd-options-head.txt[] @@ -367,20 +463,94 @@ Event source type One of: option:--function='SOURCE':: - Linux kernel kretprobe. Only available with the option:--kernel - domain option. 'SOURCE' is one of: + Dynamic kernel return probe (kretprobe). Only available with the + option:--kernel domain option. 'SOURCE' is one of: + * Function address (`0x` prefix supported) -* Function symbol -* Function symbol and offset (`SYMBOL+OFFSET` format) +* Function symbol name +* Function symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) option:--probe='SOURCE':: - Linux kernel kprobe. Only available with the option:--kernel - domain option. 'SOURCE' is one of: + Dynamic kernel probe (kprobe). Only available with the + option:--kernel domain option. 'SOURCE' is one of: + * Address (`0x` prefix supported) -* Symbol -* Symbol and offset (`SYMBOL+OFFSET` format) +* Symbol nane +* Symbol name and offset (__SYMBOL__++pass:[+]++__OFFSET__ format) + +option:--userspace-probe='SOURCE':: + Dynamic user space probe (uprobe). Only available with the + option:--kernel domain option. See the + <> section. ++ +'SOURCE' is one of: ++ +-- +\[++elf:++]__PATH__++:++__SYMBOL__:: + Dynamically instrument an available symbol within a user space + application or library. ++ +-- +'PATH':: + Application or library path. ++ +This can be: ++ +* An absolute path. +* A relative path. +* An application's name as found in the directories listed in the + `PATH` environment variable. + +'SYMBOL':: + Symbol name of the function of which to instrument the entry. ++ +This can be any defined code symbol listed by the man:nm(1) command +(including with its nloption:--dynamic option which lists dynamic +symbols). +-- ++ +As of this version, not specifying `elf:` is equivalent to specifying +it. ++ +Examples: ++ +* `--userspace-probe=/usr/lib/libc.so.6:malloc` +* `--userspace-probe=./myapp:createUser` +* `--userspace-probe=httpd:ap_run_open_htaccess` + +++sdt:++__PATH__++:++__PROVIDER__++:++__NAME__:: + Dynamically instrument a USDT probe within a user space application + or library. ++ +-- +'PATH':: + Application or library path. ++ +This can be: ++ +* An absolute path. +* A relative path. +* An application's name 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` +-- option:--syscall:: Linux kernel system call. Only available with the option:--kernel @@ -411,14 +581,16 @@ 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 a wildcard - (`*`) to exclude specific names. Only available with application - domains. + 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. 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 <> + event fields. See the <> section above for more information.