lttng-enable-event(1)
=====================
+:revdate: 4 April 2019
NAME
[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']...
*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*
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.
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)::
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 <<userspace-probe,Dynamic user space probes>> 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
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.
+
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
* Filter expression (option:--filter option) executed against the
dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-syntax,Filter expression syntax>> section
+ to true. See the <<filter-expr,Filter expression>> section
below for more information.
The available conditions for the application domains are:
* Filter expression (option:--filter option) executed against the
dynamic values of event fields at execution time that must evaluate
- to true. See the <<filter-syntax,Filter expression syntax>> section
+ to true. See the <<filter-expr,Filter expression>> 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
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.
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 (`"`). 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:.
+[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
$app.my_provider:my_context == 17.34e9 || some_enum >= 14
---------------------------------------------------------
--------------------
-filename != "*.log"
--------------------
+---------------------------------------
+$ctx.cpu_id == 2 && filename != "*.log"
+---------------------------------------
+
+------------------------------------------------
+eax_reg & 0xff7 == 0x240 && x[4] >> 12 <= 0x1234
+------------------------------------------------
[[log-levels]]
* `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[]
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 name
+* 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
+ <<userspace-probe,Dynamic user space probes>> 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
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 <<filter-syntax,Filter expression syntax>>
+ event fields. See the <<filter-expr,Filter expression>>
section above for more information.
projects / lttng-tools.git / blobdiff