lttng-enable-event(1)
=====================
-:revdate: 12 May 2021
+:revdate: 25 May 2021
NAME
* 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.
See man:lttng-concepts(7) to learn more about instrumentation points,
Without the option:--channel option::
The channel named `channel0`.
+
-If such a channel doesn't exist, the `enable-event` automatically
-creates it.
+If there's already a channel for the selected tracing 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 tracing session
and/or channel with the man:lttng-list(1) and man:lttng-status(1)
* 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.
--
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::
~~~~~~~~~~~~~~~~~
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__:
+``<<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__.
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'::
include::common-lttng-cmd-after-options.txt[]
+[[examples]]
+EXAMPLES
+--------
+.Create a recording event rule which matches all Linux system call events (current tracing 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 tracing 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 tracing 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 tracing 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 tracing 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 tracing 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 tracing session, specific channel).
+====
+See the option:--channel option.
+
+[role="term"]
+----
+$ lttng enable-event --kernel --channel=tva ja,wendy
+----
+====
+
+
include::common-footer.txt[]