X-Git-Url: https://git.lttng.org/?a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-event.1.txt;h=94efe497cc1203d4a9a479bb2c57849f82a47238;hb=bc13dc0f9eaa7742a589ce6d8faece4990f77f75;hp=6a07fb17f52720545b585e2bb4f765ca97538f24;hpb=8d65904aea328caf0c3b8c3895ea148ad9a2b402;p=lttng-tools.git diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 6a07fb17f..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: 12 May 2021 +:revdate: 14 June 2021 NAME @@ -52,7 +52,7 @@ The `lttng enable-event` command does one of: * Enable one or more disabled recording event rules. + -See the <> section +See the ``<>'' section below. See man:lttng-concepts(7) to learn more about instrumentation points, @@ -61,11 +61,11 @@ 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 tracing session named 'SESSION'. + The recording session named 'SESSION'. Without the option:--session option:: - The current tracing session (see man:lttng-concepts(7) to learn more - about the current tracing session). + 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'. @@ -73,11 +73,13 @@ With the option:--channel='CHANNEL' option:: Without the option:--channel option:: The channel named `channel0`. + -If there's already a channel for the selected tracing session and domain -which isn't named `channel0`, the `enable-event` command fails. +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. -List the recording event rules of a specific tracing session +See the ``<>'' 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. @@ -99,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. -- @@ -136,16 +138,16 @@ A channel is enabled on creation. + 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__ 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 @@ -191,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. @@ -213,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. @@ -224,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. @@ -262,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:: @@ -551,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 -above) 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__. @@ -610,7 +612,7 @@ 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` @@ -653,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: @@ -679,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. @@ -695,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. @@ -771,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. @@ -798,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 @@ -819,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: @@ -838,7 +840,7 @@ with the option:--kernel option. Event payload and context filter condition ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -See the <> +See the ``<>'' section above. option:-f 'EXPR', option:--filter='EXPR':: @@ -855,6 +857,85 @@ 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-footer.txt[]