lttng-{enable-event(1),event-rule(7)}: `--filter` is not always avail.

[lttng-tools.git] / doc / man / lttng-enable-event.1.txt

lttng-enable-event(1)
=====================
:revdate: 12 May 2021


NAME
----
lttng-enable-event - Create or enable LTTng recording event rules


SYNOPSIS
--------
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:--tracepoint | option:--syscall]
      (option:--all | 'NAME'[,'NAME']...) [option:--filter='EXPR']
      [option:--session='SESSION'] [option:--channel='CHANNEL']

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:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
      [option:--session='SESSION'] [option:--channel='CHANNEL']

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:--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 does one of:

* Create one or more recording event rules.

* Enable one or more disabled recording event rules.
+
See the <<enable,Enable a disabled recording event rule>> section
below.

See man:lttng-concepts(7) to learn more about instrumentation points,
events, recording event rules, and event records.

The recording event rule(s) to create or enable belong to:

With the option:--session='SESSION' option::
    The tracing session named 'SESSION'.

Without the option:--session option::
    The current tracing session (see man:lttng-concepts(7) to learn more
    about the current tracing session).

With the option:--channel='CHANNEL' option::
    The channel named 'CHANNEL'.

Without the option:--channel option::
    The channel named `channel0`.
+
If such a channel doesn't exist, the `enable-event` automatically
creates it.

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.

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 <<inst-point-type-cond,Instrumentation point type condition>>
section below.

* A pattern matches the name of{nbsp}__E__ while another pattern
  doesn't.
+
See the <<event-name-cond,Event name condition>> 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 <<inst-point-log-level-cond,Instrumentation point log level condition>>
section below.

* The fields of the payload of{nbsp}__E__ and the current context fields
  satisfy a filter expression.
+
See the <<filter-cond,Event payload and context filter condition>>
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 <<er-name,Event record name>> 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
<<er-name,Event record name>> 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 <<er-name,Event record name>> 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
  <<inst-point-type-cond,Instrumentation point type condition>> 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.


[[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:

* The option:--loglevel and option:--loglevel-only options are
  missing.

* 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'.

      With the option:--loglevel-only='LOGLEVEL' option::
          Exactly 'LOGLEVEL'.

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)
* `TRACE_ALERT` (1)
* `TRACE_CRIT` (2)
* `TRACE_ERR` (3)
* `TRACE_WARNING` (4)
* `TRACE_NOTICE` (5)
* `TRACE_INFO` (6)
* `TRACE_DEBUG_SYSTEM` (7)
* `TRACE_DEBUG_PROGRAM` (8)
* `TRACE_DEBUG_PROCESS` (9)
* `TRACE_DEBUG_MODULE` (10)
* `TRACE_DEBUG_UNIT` (11)
* `TRACE_DEBUG_FUNCTION` (12)
* `TRACE_DEBUG_LINE` (13)
* `TRACE_DEBUG` (14)

`java.util.logging` (option:--jul option)::
    Shortcuts such as `severe` are allowed.
+
* `JUL_OFF` (`INT32_MAX`)
* `JUL_SEVERE` (1000)
* `JUL_WARNING` (900)
* `JUL_INFO` (800)
* `JUL_CONFIG` (700)
* `JUL_FINE` (500)
* `JUL_FINER` (400)
* `JUL_FINEST` (300)
* `JUL_ALL` (`INT32_MIN`)

Apache log4j (option:--log4j option)::
    Shortcuts such as `severe` are allowed.
+
* `LOG4J_OFF` (`INT32_MAX`)
* `LOG4J_FATAL` (50000)
* `LOG4J_ERROR` (40000)
* `LOG4J_WARN` (30000)
* `LOG4J_INFO` (20000)
* `LOG4J_DEBUG` (10000)
* `LOG4J_TRACE` (5000)
* `LOG4J_ALL` (`INT32_MIN`)

Python (option:--python option)::
    Shortcuts such as `critical` are allowed.
+
* `PYTHON_CRITICAL` (50)
* `PYTHON_ERROR` (40)
* `PYTHON_WARNING` (30)
* `PYTHON_INFO` (20)
* `PYTHON_DEBUG` (10)
* `PYTHON_NOTSET` (0)


[[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_.

This condition is only meaningful for the LTTng tracepoint and Linux
system call instrumentation point types: it's always satisfied for other
types.

'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
<<inst-point-type-cond,Instrumentation point type condition>> 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[]


Tracing domain
~~~~~~~~~~~~~~
One of:

option:-j, option:--jul::
    Create or enable recording event rules in the `java.util.logging`
    (JUL) tracing domain.

option:-k, option:--kernel::
    Create or enable recording event rules in the Linux kernel tracing
    domain.

option:-l, option:--log4j::
    Create or enable recording event rules in the Apache log4j tracing
    domain.

option:-p, option:--python::
    Create or enable recording event rules in the Python tracing domain.

option:-u, option:--userspace::
    Create or enable recording event rules in the user space tracing
    domain.


Recording target
~~~~~~~~~~~~~~~~
option:-c 'CHANNEL', option:--channel='CHANNEL'::
    Create or enable recording event rules attached to the channel named
    'CHANNEL' instead of `channel0`.

option:-s 'SESSION', option:--session='SESSION'::
    Create or enable recording event rules in the tracing session named
    'SESSION' instead of the current tracing session.


Instrumentation point type condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
See the <<inst-point-type-cond,Instrumentation point type condition>>
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
<<er-name,Event record name>> 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
<<er-name,Event record name>> 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.

'SYMBOL'::
    Symbol name of the function of which to instrument the entry.
+
'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`

++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:
+
* 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
<<er-name,Event record name>> section above to learn more.

option:--syscall::
    Only match Linux system call events.
+
Only available with the option:--kernel option.

option:--tracepoint::
    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.

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 <<event-name-cond,Event name condition>> 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 <<inst-point-log-level-cond,Instrumentation point log level
condition>> section above.

At most one of:

option:--loglevel='LOGLEVEL'::
    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'::
    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 <<filter-cond,Event payload and context filter condition>>
section above.

option:-f 'EXPR', option:--filter='EXPR'::
    Only match events of which 'EXPR', which can contain references to
    event payload and current context fields, is _true_.
+
This option is only available with the option:--tracepoint or
option:--syscall option.


include::common-lttng-cmd-help-options.txt[]


include::common-lttng-cmd-after-options.txt[]


include::common-footer.txt[]


SEE ALSO
--------
man:lttng(1),
man:lttng-disable-event(1),
man:lttng-enable-channel(1),
man:lttng-list(1),
man:lttng-start(1),
man:lttng-track(1),
man:lttng-concepts(7)