Use compiler-agnostic defines to silence warning

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

lttng-enable-event(1)
=====================
:revdate: 14 June 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:--log4j2 | 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 recording session named 'SESSION'.

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

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

Without the option:--channel option::
    The channel named `channel0`.
+
If there's already a channel for the selected recording session and
domain which isn't named `channel0`, the `enable-event` command fails.
Otherwise, it automatically creates it.

See the ``<<examples,EXAMPLES>>'' section below for usage examples.

List the recording event rules of a specific recording 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 recording session of{nbsp}__ER__ is active (started).
+
A recording session is inactive (stopped) on creation.
+
Start an inactive recording 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 recording 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 1.x log4j (option:--log4j option), Apache 2.x log4j (option:--log4j2 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 1.x, Apache
log4j 2.x, 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`, `lttng list --log4j2`, 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)::
+
* `EMERG` (0)
* `ALERT` (1)
* `CRIT` (2)
* `ERR` (3)
* `WARNING` (4)
* `NOTICE` (5)
* `INFO` (6)
* `DEBUG_SYSTEM` (7)
* `DEBUG_PROGRAM` (8)
* `DEBUG_PROCESS` (9)
* `DEBUG_MODULE` (10)
* `DEBUG_UNIT` (11)
* `DEBUG_FUNCTION` (12)
* `DEBUG_LINE` (13)
* `DEBUG` (14)

`java.util.logging` (option:--jul option)::
+
* `OFF` (`INT32_MAX`)
* `SEVERE` (1000)
* `WARNING` (900)
* `INFO` (800)
* `CONFIG` (700)
* `FINE` (500)
* `FINER` (400)
* `FINEST` (300)
* `ALL` (`INT32_MIN`)

Apache Log4j 1.x (option:--log4j option)::
+
* `OFF` (`INT32_MAX`)
* `FATAL` (50000)
* `ERROR` (40000)
* `WARN` (30000)
* `INFO` (20000)
* `DEBUG` (10000)
* `TRACE` (5000)
* `ALL` (`INT32_MIN`)

Apache Log4j 2 (option:--log4j2 option)::
+
* `OFF` (`0`)
* `FATAL` (100)
* `ERROR` (200)
* `WARN` (300)
* `INFO` (400)
* `DEBUG` (500)
* `TRACE` (600)
* `ALL` (`INT32_MAX`)

Python (option:--python option)::
+
* `CRITICAL` (50)
* `ERROR` (40)
* `WARNING` (30)
* `INFO` (20)
* `DEBUG` (10)
* `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 1.x 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 1.x logger from which LTTng creates{nbsp}__E__.

Apache Log4j 2 logging statement (option:--log4j2 and option:--tracepoint options)::
    `lttng_log4j2:event`
+
Such an event record has a string field `logger_name` which contains the
name of the Apache Log4j 2 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 recording 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 1.x tracing
    domain.

option:--log4j2::
    Create or enable recording event rules in the Apache Log4j 2 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 recording session
    named 'SESSION' instead of the current recording 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, option:--log4j2, 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, option:--log4j2, 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[]


[[examples]]
EXAMPLES
--------
.Create a recording event rule which matches all Linux system call events (current recording session, default channel).
====
See the option:--all and option:--syscall options.

[role="term"]
----
$ lttng enable-event --kernel --all --syscall
----
====

.Create a recording event rule which matches user space tracepoint events named specifically (current recording session, default channel).
====
The recording event rule below matches all user space tracepoint events
of which the name starts with `my_provider:msg`.

[role="term"]
----
$ lttng enable-event --userspace 'my_provider:msg*'
----
====

.Create three recording event rules which match Python logging events named specifically (current recording session, default channel).
====
[role="term"]
----
$ lttng enable-event --python server3,ui.window,user-mgmt
----
====

.Create a recording event rule which matches Apache Log4j 1.x logging events with a specific log level range (current recording session, specific channel).
====
See the option:--channel, option:--all, and option:--loglevel options.

[role="term"]
----
$ lttng enable-event --log4j --channel=my-loggers \
                     --all --loglevel=INFO
----
====

.Create a recording event rule which matches Apache Log4j 2 logging events with a specific log level range (current recording session, specific channel).
====
See the option:--channel, option:--all, and option:--loglevel options.

[role="term"]
----
$ lttng enable-event --log4j2 --channel=my-loggers \
                     --all --loglevel=INFO
----
====

.Create a recording event rule which matches specific Linux kprobe events (current recording session, default channel).
====
The recording event rule below matches the entry of `usb_disconnect()`
Linux kernel function calls. The records of such events are named `usbd`
(see the ``<<er-name,Event record name>>'' section above).

See the option:--probe option.

[role="term"]
----
$ lttng enable-event --kernel --probe=usb_disconnect usbd
----
====

.Create a recording event rule which matches Linux kernel tracepoint events which satisfy an event payload and context filter (specific recording session, default channel).
====
See the option:--session and option:--filter options.

[role="term"]
----
$ lttng enable-event --kernel --session=my-session 'sched_*' \
        --filter='$ctx.preemptible && comm != "systemd*"'
----
====

.Enable two Linux kernel tracepoint recording event rules (current recording session, specific channel).
====
See the option:--channel option.

[role="term"]
----
$ lttng enable-event --kernel --channel=tva ja,wendy
----
====


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)