Document kernel events filtering

[lttng-docs.git] / contents / using-lttng / controlling-tracing / enabling-disabling-events.md

diff --git a/contents/using-lttng/controlling-tracing/enabling-disabling-events.md b/contents/using-lttng/controlling-tracing/enabling-disabling-events.md
index ac4d137d653d4405b0d0f7c07e6f6c3bf49e72dc..5c40f4cbbcc4787a6cde6fdfa1dce5cf84fc732e 100644 (file)
--- a/contents/using-lttng/controlling-tracing/enabling-disabling-events.md
+++ b/contents/using-lttng/controlling-tracing/enabling-disabling-events.md
@@ -12,24 +12,25 @@ in source code/binary program, logical processor and time capturing
 some payload) being recorded as trace data. This specific condition is
 composed of:
 
-  1. A **domain** (kernel, user space or Java Util Logging) (required).
+  1. A **domain** (kernel, user space, `java.util.logging`, or log4j)
+     (required).
   2. One or many **instrumentation points** in source code or binary
      program (tracepoint name, address, symbol name, function name,
-     logger name, etc.) to be executed (required).
+     logger name, amongst other types of probes) to be executed
+     (required).
   3. A **log level** (each instrumentation point declares its own log
      level) or log level range to match (optional; only valid for user
      space domain).
   4. A **custom user expression**, or **filter**, that must evaluate to
-     _true_ when a tracepoint is executed (optional; only valid for user
-     space domain).
+     _true_ when a tracepoint is executed (optional).
 
 All conditions are specified using arguments passed to the
 `enable-event` command of the `lttng` tool.
 
-Condition 1 is specified using either `--kernel/-k` (kernel),
-`--userspace/-u` (user space) or `--jul/-j`
-(<abbr title="Java Util Logging">JUL</abbr>). Exactly one of those
-three arguments must be specified.
+Condition 1 is specified using either `--kernel`/`-k` (kernel),
+`--userspace`/`-u` (user space), `--jul`/`-j`
+(<abbr title="java.util.logging">JUL</abbr>), or `--log4j`/`-l` (log4j).
+Exactly one of those four arguments must be specified.
 
 Condition 2 is specified using one of:
 
@@ -79,6 +80,8 @@ lttng enable-event -k --tracepoint sched_switch
 lttng enable-event -k --tracepoint gpio_value
 lttng enable-event -k --function usb_probe_device usb_probe_device
 lttng enable-event -k --syscall --all
+lttng enable-event -k --tracepoint irq_handler_entry  \
+                   --filter 'irq == 28 || irq == 17'
 </pre>
 
 The wildcard symbol, `*`, matches _anything_ and may only be used at
@@ -86,6 +89,21 @@ the end of the string when specifying a _tracepoint_. Make sure to
 use it between single quotes in your favorite shell to avoid
 undesired shell expansion.
 
+System call events can be enabled individually, too:
+
+<pre class="term" style="position: relative">
+<div class="since">Since 2.6</div>lttng enable-event -k --syscall open
+lttng enable-event -k --syscall read
+lttng enable-event -k --syscall fork,chdir,pipe
+</pre>
+
+The complete list of available system call events can be
+obtained using
+
+<pre class="term">
+lttng list --kernel --syscall
+</pre>
+
 You can see a list of events (enabled or disabled) using
 
 <pre class="term">
@@ -111,7 +129,7 @@ Disabling an event is simpler: you only need to provide the event
 name to the `disable-event` command:
 
 <pre class="term">
-lttng disable-event -u my_app:hello_you
+lttng disable-event --userspace my_app:hello_you
 </pre>
 
 This name has to match a name previously given to `enable-event` (it
@@ -123,7 +141,7 @@ Disabling an event does not add it to some blacklist: it simply removes
 it from its channel's whitelist. This is why you cannot disable an event
 which wasn't previously enabled.
 
-A disabled event will not generate any trace data, even if all its
+A disabled event doesn't generate any trace data, even if all its
 specified conditions are met.
 
 Events may be enabled and disabled at will, either when LTTng tracers