lttng-enable-event(1)
=====================
-:revdate: 13 April 2021
+:revdate: 14 June 2021
NAME
[verse]
*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* option:--kernel
(option:--probe='LOC' | option:--function='LOC' | option:--userspace-probe='LOC') 'RECORDNAME'
- [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL']
+ [option:--session='SESSION'] [option:--channel='CHANNEL']
Create or enable one or more recording event rules to match
user space tracepoint events:
* Create one or more recording event rules.
-* Enable one or more existing, disabled recording event rules.
+* Enable one or more disabled recording event rules.
+
-See the <<enable,Enable a disabled recording event rule>> section
+See the ``<<enable,Enable a disabled recording event rule>>'' section
below.
-An _instrumentation point_ is a point, within a piece of software,
-which, when executed, creates an LTTng _event_.
-
-LTTng offers various types of instrumentation; see the
-<<inst-point-type-cond,Instrumentation point type condition>> section
-below to learn about them.
-
-An _event rule_ is a set of conditions to match a set of events. A
-_recording event rule_ is a specific type of event rule of which the
-associated action is to serialize and record the matched event.
+See man:lttng-concepts(7) to learn more about instrumentation points,
+events, recording event rules, and event records.
-When LTTng creates an event{nbsp}__E__, a recording event
-rule{nbsp}__ER__ is said to __match__{nbsp}__E__ when{nbsp}__E__
-satisfies *all* the conditions of{nbsp}__ER__. This concept is similar
-to a regular expression which matches a set of strings.
+The recording event rule(s) to create or enable belong to:
-When a recording event rule matches an event, LTTng _emits_ the event,
-therefore attempting to serialize and record it to one of the
-sub-buffers of its attached channel (see man:lttng-enable-channel(1) to
-learn more about LTTng channels).
+With the option:--session='SESSION' option::
+ The recording session named 'SESSION'.
-Without the option:--channel option, the `enable-event` command selects
-the channel named `channel0`. When the `enable-event` command creates a
-recording event rule, it automatically creates the `channel0` channel
-(for the specified tracing domain in the selected tracing session) if it
-doesn't exist.
+Without the option:--session option::
+ The current recording session (see man:lttng-concepts(7) to learn
+ more about the current recording session).
-When multiple matching recording event rules are attached to the same
-channel, LTTng attempts to serialize and record the matched event
-_once_. In the following example, the second recording event
-rule is redundant when both are enabled:
+With the option:--channel='CHANNEL' option::
+ The channel named 'CHANNEL'.
-[role="term"]
-----
-$ lttng enable-event --userspace hello:world
-$ lttng enable-event --userspace hello:world --loglevel=TRACE_INFO
-----
-
-Without the option:--session option, the `enable-event` command selects
-the current tracing session (see man:lttng-create(1) and
-man:lttng-set-session(1) to learn more about the current tracing
-session).
+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.
-[NOTE]
-====
-The event creation and emission processes are documentation concepts to
-help understand the journey from an instrumentation point to the
-serialization and recording of an event.
-
-The actual creation of an event can be costly because LTTng needs to
-evalute the arguments of the instrumentation point.
-
-In practice, LTTng implements various optimizations for the Linux kernel
-and user space tracing domains (option:--kernel and option:--userspace
-options) to avoid actually creating an event when the tracer knows,
-thanks to properties which are independent from the event payload and
-current context, that it would never emit such an event. Those
-properties are:
-
-* The status of the rule itself (enabled or disabled).
-* The status of the channel (enabled or disabled; see
- man:lttng-enable-channel(1) and man:lttng-disable-channel(1)).
-* The activity of the tracing session (started or stopped; see
- man:lttng-start(1) and man:lttng-stop(1)).
-* The instrumentation point type (see the
- <<inst-point-type-cond,Instrumentation point type>> section below).
-* The instrumentation point name (or event name)
- (see the <<event-name-cond,Event name condition>> section below).
-* The instrumentation point log level (see the
- <<inst-point-log-level-cond,Instrumentation point log level condition>>
- section below).
-
-In other words: if, for a given instrumentation point{nbsp}__IP__, the
-LTTng tracer knows that it would never emit and record an event,
-executing{nbsp}__IP__ represents a simple boolean variable check and,
-for the kernel tracer, a few process attribute checks.
-====
+See the ``<<examples,EXAMPLES>>'' section below for usage examples.
-List the existing recording event rules of a given tracing session
-and/or channel with the man:lttng-list(1) command.
+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 existing, enabled recording event rule with the
+Disable an enabled recording event rule with the
man:lttng-disable-event(1) command.
-Recording event rule overview
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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:
* 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.
+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.
+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.
+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>>
+See the ``<<filter-cond,Event payload and context filter condition>>''
section below.
--
+
A recording event rule is enabled on creation.
+
-Enable an existing, disabled recording event rule with the
-`enable-event` command.
+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 an existing, disabled channel with the
-man:lttng-enable-channel(1) command.
+Enable a disabled channel with the man:lttng-enable-channel(1) command.
-* The tracing session of{nbsp}__ER__ is active (started).
+* The recording session of{nbsp}__ER__ is active (started).
+
-A tracing session is inactive (stopped) on creation.
+A recording session is inactive (stopped) on creation.
+
-Start an inactive tracing session with the man:lttng-start(1) command.
+Start an inactive recording session with the man:lttng-start(1) command.
-* The process for which LTTng creates{nbsp}__E__ to match is allowed to
- record events.
+* The process for which LTTng creates{nbsp}__E__ is allowed to record
+ events.
+
-All processes are allowed to record events on tracing session
+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
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).
+of{nbsp}__E__ (see the ``<<er-name,Event record name>>'' section below).
+
The payload of a Linux kprobe event is empty.
--
+
'RECORDNAME' is the name of the record of{nbsp}__E__ (see the
-<<er-name,Event record name>> section below).
+``<<er-name,Event record name>>'' section below).
+
The payload of a Linux user space probe event is empty.
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).
+of{nbsp}__E__ (see the ``<<er-name,Event record name>>'' section below).
+
The payload of a Linux kretprobe event is empty.
* 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:
+ ``<<inst-point-type-cond,Instrumentation point type condition>>''
+ section above) of{nbsp}__ER__, 'NAME' matches:
+
--
LTTng tracepoint::
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)
++
+* `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)::
- 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`)
++
+* `OFF` (`INT32_MAX`)
+* `SEVERE` (1000)
+* `WARNING` (900)
+* `INFO` (800)
+* `CONFIG` (700)
+* `FINE` (500)
+* `FINER` (400)
+* `FINEST` (300)
+* `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`)
+* `OFF` (`INT32_MAX`)
+* `FATAL` (50000)
+* `ERROR` (40000)
+* `WARN` (30000)
+* `INFO` (20000)
+* `DEBUG` (10000)
+* `TRACE` (5000)
+* `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)
+* `CRITICAL` (50)
+* `ERROR` (40)
+* `WARNING` (30)
+* `INFO` (20)
+* `DEBUG` (10)
+* `NOTSET` (0)
[[filter-cond]]
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.
~~~~~~~~~~~~~~~~~
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)
-of the recording event rule which matched{nbsp}__E__:
+``<<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__.
[[enable]]
Enable a disabled recording event rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The `enable-event` command can enable an existing, disabled recording
-event rule, as listed in the output of the man:lttng-list(1) command.
+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
+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`
must be the exact same string as the one you used on creation.
-include::common-cmd-options-head.txt[]
+include::common-lttng-cmd-options-head.txt[]
Tracing domain
'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.
+ 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.
+See the ``<<inst-point-type-cond,Instrumentation point type
+condition>>'' section above.
At most one of:
--
+
You must specify the event record name with 'RECORDNAME'. See the
-<<er-name,Event record name>> section above to learn more.
+``<<er-name,Event record name>>'' section above to learn more.
option:--probe='LOC'::
Only match Linux kprobe events.
--
+
You must specify the event record name with 'RECORDNAME'. See the
-<<er-name,Event record name>> section above to learn more.
+``<<er-name,Event record name>>'' section above to learn more.
option:--userspace-probe='LOC'::
Only match Linux user space probe events.
--
+
You must specify the event record name with 'RECORDNAME'. See the
-<<er-name,Event record name>> section above to learn more.
+``<<er-name,Event record name>>'' section above to learn more.
option:--syscall::
Only match Linux system call events.
Event name condition
~~~~~~~~~~~~~~~~~~~~
-See the <<event-name-cond,Event name condition>> section above.
+See the ``<<event-name-cond,Event name condition>>'' section above.
option:-a, option:--all::
Equivalent to a single 'NAME' argument (LTTng tracepoint or logger
Instrumentation point log level condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See the <<inst-point-log-level-cond,Instrumentation point log level
-condition>> section above.
+See the ``<<inst-point-log-level-cond,Instrumentation point log level
+condition>>'' section above.
At most one of:
Event payload and context filter condition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See the <<filter-cond,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-cmd-help-options.txt[]
+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 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 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-cmd-footer.txt[]
+include::common-footer.txt[]
SEE ALSO
man:lttng-enable-channel(1),
man:lttng-list(1),
man:lttng-start(1),
-man:lttng-track(1)
+man:lttng-track(1),
+man:lttng-concepts(7)
projects / lttng-tools.git / blobdiff