X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=doc%2Fman%2Flttng-enable-event.1.txt;h=433fa2341f20f65387244d68c4ca565f581242f2;hb=7964b8ba91c12050f2133b6d070ad09eb9ed9209;hp=526266fe145cf2ee46db1fe94ca7a01388e6b748;hpb=55e0699466ecc7e7a52b3ca54a806f2faf9bb59e;p=lttng-tools.git diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 526266fe1..433fa2341 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: 3 May 2021 +:revdate: 25 May 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: @@ -73,8 +73,11 @@ With the option:--channel='CHANNEL' option:: 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 <> 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) @@ -334,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]] @@ -395,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. @@ -843,6 +846,9 @@ 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-lttng-cmd-help-options.txt[] @@ -851,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 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 <> 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[]