X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-event.1.txt;h=94efe497cc1203d4a9a479bb2c57849f82a47238;hb=d22ba1ec0497c9dbea3d7263d553be3547dfbe9f;hp=6acdbcd2982479407e545569b37ea1ef833ffe9e;hpb=484b2a0cbefcf0c7072622a5a411ea5ed849da28;p=lttng-tools.git diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 6acdbcd29..94efe497c 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -1,6 +1,6 @@ lttng-enable-event(1) ===================== -:revdate: 13 April 2021 +:revdate: 14 June 2021 NAME @@ -24,7 +24,7 @@ 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:--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: @@ -50,98 +50,45 @@ The `lttng enable-event` command does one of: * 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 <> section +See the ``<>'' 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 -<> 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 - <> section below). -* The instrumentation point name (or event name) - (see the <> section below). -* The instrumentation point log level (see the - <> - 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 ``<>'' 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: @@ -154,25 +101,25 @@ Explicit conditions:: * The instrumentation point type from which LTTng creates{nbsp}__E__ has a specific type. + -See the <> -section below. +See the ``<>'' section below. * A pattern matches the name of{nbsp}__E__ while another pattern doesn't. + -See the <> section below. +See the ``<>'' 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 <> -section below. +See the ``<>'' section below. * The fields of the payload of{nbsp}__E__ and the current context fields satisfy a filter expression. + -See the <> +See the ``<>'' section below. -- @@ -183,26 +130,24 @@ Implicit conditions:: + 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 @@ -248,7 +193,7 @@ List the available Linux kernel system call instrumentation points with 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 <> section below). +of{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux kprobe event is empty. @@ -270,7 +215,7 @@ are :not: reference-counted. -- + 'RECORDNAME' is the name of the record of{nbsp}__E__ (see the -<> section below). +``<>'' section below). + The payload of a Linux user space probe event is empty. @@ -281,7 +226,7 @@ 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 <> section below). +of{nbsp}__E__ (see the ``<>'' section below). + The payload of a Linux kretprobe event is empty. @@ -319,8 +264,8 @@ 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 - <> section - above) of{nbsp}__ER__, 'NAME' matches: + ``<>'' + section above) of{nbsp}__ER__, 'NAME' matches: + -- LTTng tracepoint:: @@ -392,58 +337,54 @@ 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) ++ +* `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]] @@ -453,6 +394,10 @@ 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. @@ -608,8 +553,8 @@ 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 -<> section) -of the recording event rule which matched{nbsp}__E__: +``<>'' +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__. @@ -663,11 +608,11 @@ Linux kretprobe (option:--kernel and option:--function options):: [[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` @@ -676,7 +621,7 @@ 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-cmd-options-head.txt[] +include::common-lttng-cmd-options-head.txt[] Tracing domain @@ -710,14 +655,14 @@ option:-c 'CHANNEL', option:--channel='CHANNEL':: '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 <> -section above. +See the ``<>'' section above. At most one of: @@ -736,7 +681,7 @@ Only available with the option:--kernel option. -- + You must specify the event record name with 'RECORDNAME'. See the -<> section above to learn more. +``<>'' section above to learn more. option:--probe='LOC':: Only match Linux kprobe events. @@ -752,7 +697,7 @@ Only available with the option:--kernel option. -- + You must specify the event record name with 'RECORDNAME'. See the -<> section above to learn more. +``<>'' section above to learn more. option:--userspace-probe='LOC':: Only match Linux user space probe events. @@ -828,7 +773,7 @@ Example: `--userspace-probe=sdt:./build/server:server:accept_request` -- + You must specify the event record name with 'RECORDNAME'. See the -<> section above to learn more. +``<>'' section above to learn more. option:--syscall:: Only match Linux system call events. @@ -855,7 +800,7 @@ future. Event name condition ~~~~~~~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. option:-a, option:--all:: Equivalent to a single 'NAME' argument (LTTng tracepoint or logger @@ -876,8 +821,8 @@ a literal `,` character, use :esccomma:. Instrumentation point log level condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> section above. +See the ``<>'' section above. At most one of: @@ -895,18 +840,103 @@ with the option:--kernel option. Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> +See the ``<>'' 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 ``<>'' 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 @@ -916,4 +946,5 @@ man:lttng-disable-event(1), 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)