From f1f15c35fcc3c4ebc06afac075054cd2a356aac4 Mon Sep 17 00:00:00 2001 From: Michael Jeanson Date: Wed, 22 May 2024 16:40:29 -0400 Subject: [PATCH] Add 'log4j2' domain to the documentation MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Change-Id: Ie76c686583f10bc09b9769db66e8e079b8472a37 Signed-off-by: Michael Jeanson Signed-off-by: Jérémie Galarneau --- doc/api/liblttng-ctl/dox/groups.dox | 19 ++++++++-- doc/man/lttng-add-context.1.txt | 16 +++++--- doc/man/lttng-concepts.7.txt | 14 ++++--- doc/man/lttng-disable-event.1.txt | 11 ++++-- doc/man/lttng-enable-event.1.txt | 58 ++++++++++++++++++++++------- doc/man/lttng-event-rule.7.txt | 36 ++++++++++++++++-- doc/man/lttng-list.1.txt | 23 ++++++++---- 7 files changed, 134 insertions(+), 43 deletions(-) diff --git a/doc/api/liblttng-ctl/dox/groups.dox b/doc/api/liblttng-ctl/dox/groups.dox index f10de45dd..137d48402 100644 --- a/doc/api/liblttng-ctl/dox/groups.dox +++ b/doc/api/liblttng-ctl/dox/groups.dox @@ -774,8 +774,11 @@ There are currently five available tracing domains: java.util.logging (JUL) #LTTNG_DOMAIN_JUL - Apache log4j + Apache Log4j 1.x #LTTNG_DOMAIN_LOG4J + + Apache Log4j 2 + #LTTNG_DOMAIN_LOG4J2 Python logging #LTTNG_DOMAIN_PYTHON @@ -806,7 +809,8 @@ sub-buffers of one or more channels. A channel is always associated to a \lt_obj_domain. The \link #LTTNG_DOMAIN_JUL java.util.logging\endlink, -\link #LTTNG_DOMAIN_LOG4J Apache log4j\endlink, and +\link #LTTNG_DOMAIN_LOG4J Apache Log4j 1.x\endlink, +\link #LTTNG_DOMAIN_LOG4J2 Apache Log4j 2\endlink, and \link #LTTNG_DOMAIN_PYTHON Python\endlink tracing domains each have a default channel which you can't configure. @@ -2175,7 +2179,16 @@ as well as on the \lt_obj_domain which contains \lt_var{ER}: lttng_log4j:event Such an event record has a string field logger_name - which contains the name of the Apache log4j logger from which + which contains the name of the Apache Log4j 1.x logger from which + LTTng creates \lt_var{E}. + + #LTTNG_DOMAIN_LOG4J2 + #LTTNG_EVENT_TRACEPOINT + + lttng_log4j2:event + + Such an event record has a string field logger_name + which contains the name of the Apache Log4j 2 logger from which LTTng creates \lt_var{E}. #LTTNG_DOMAIN_PYTHON diff --git a/doc/man/lttng-add-context.1.txt b/doc/man/lttng-add-context.1.txt index d8cf42f96..00d39e035 100644 --- a/doc/man/lttng-add-context.1.txt +++ b/doc/man/lttng-add-context.1.txt @@ -15,7 +15,7 @@ channels: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *add-context* - (option:--kernel | option:--userspace | option:--jul | option:--log4j) + (option:--kernel | option:--userspace | option:--jul | option:--log4j | option:--log4j2) [option:--session='SESSION'] [option:--channel='CHANNEL'] option:--type='TYPE' [option:--type='TYPE']... @@ -68,14 +68,14 @@ Only available with the option:--kernel option. Per-thread:: Prefix: `perf:thread:` + -Only available with the option:--userspace, option:--jul, or -option:--log4j option. +Only available with the option:--userspace, option:--jul, +option:--log4j, or option:--log4j2 option. -- + Add Performance Monitoring Unit (PMU) counter context fields by raw ID with the ++perf:cpu:raw:r++__N__++:++__NAME__ (option:--kernel option) or ++perf:thread:raw:r++__N__++:++__NAME__ (option:--userspace, -option:--jul, or option:--log4j option) types, with: +option:--jul, option:--log4j, or option:--log4j2 option) types, with: + -- 'N':: @@ -102,7 +102,7 @@ $app.'PROVIDER':__TYPE__ Context type name. -- + -Only available with the option:--jul and option:--log4j options. +Only available with the option:--jul, option:--log4j and option:--log4j2 options. IMPORTANT: Make sure to **single-quote** 'TYPE' when you run the `add-context` command from a shell, as `$` is a special character for @@ -133,7 +133,11 @@ option:-k, option:--kernel:: option:-l, option:--log4j:: Add context fields to be recorded to the event records of one or - more channels of the Apache log4j tracing domain. + more channels of the Apache Log4j 1.x tracing domain. + +option:--log4j2:: + Add context fields to be recorded to the event records of one or + more channels of the Apache Log4j 2 tracing domain. option:-u, option:--userspace:: Add context fields to be recorded to the event records of one or diff --git a/doc/man/lttng-concepts.7.txt b/doc/man/lttng-concepts.7.txt index a1bea3b9c..68348c8ec 100644 --- a/doc/man/lttng-concepts.7.txt +++ b/doc/man/lttng-concepts.7.txt @@ -200,14 +200,14 @@ User space:: List the available Linux kernel tracepoints with `lttng list --userspace`. See man:lttng-list(1) to learn more. -`java.util.logging`, Apache log4j, and Python:: +`java.util.logging`, Apache Log4j 1.x, Apache Log4j 2, and Python:: Java or Python logging statement::: A method call on a Java or Python logger attached to an LTTng-UST handler. + List the available Java and Python loggers with `lttng list --jul`, -`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1) -to learn more. +`lttng list --log4j`, `lttng list --log4j2`, and `lttng list --python`. See +man:lttng-list(1) to learn more. [[trigger]] @@ -534,10 +534,14 @@ There are currently five available tracing domains: |nloption:--type option starts with `jul:` |nloption:--jul -|Apache log4j +|Apache Log4j 1.x |nloption:--type option starts with `log4j:` |nloption:--log4j +|Apache Log4j 2 +|nloption:--type option starts with `log4j2:` +|nloption:--log4j2 + |Python |nloption:--type option starts with `python:` |nloption:--python @@ -613,7 +617,7 @@ provided tracing domain. A channel is always associated to a tracing domain (see the ``<>'' section below). The `java.util.logging` -(JUL), log4j, and Python tracing domains each have a default channel +(JUL), log4j, log4j2 and Python tracing domains each have a default channel which you can't configure. A channel owns recording event rules. diff --git a/doc/man/lttng-disable-event.1.txt b/doc/man/lttng-disable-event.1.txt index da6eb2d21..610381377 100644 --- a/doc/man/lttng-disable-event.1.txt +++ b/doc/man/lttng-disable-event.1.txt @@ -24,7 +24,7 @@ tracepoint or Java/Python logging events: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *disable-event* - (option:--userspace | option:--jul | option:--log4j | option:--python) [option:--tracepoint] + (option:--userspace | option:--jul | option:--log4j | option:--log4j2 |option:--python) [option:--tracepoint] (option:--all-events | 'NAME'[,'NAME']...) [option:--session='SESSION'] [option:--channel='CHANNEL'] @@ -95,7 +95,10 @@ option:-k, option:--kernel:: Disable recording event rules in the Linux kernel domain. option:-l, option:--log4j:: - Disable recording event rules in the Apache log4j domain. + Disable recording event rules in the Apache Log4j 1.x domain. + +option:--log4j2:: + Disable recording event rules in the Apache Log4j 2 domain. option:-p, option:--python:: Disable recording event rules in the Python domain. @@ -142,7 +145,7 @@ option:--tracepoint:: -- With the option:--kernel or option:--userspace option::: LTTng tracepoint events. -With the option:--jul, option:--log4j, or option:--python option::: +With the option:--jul, option:--log4j, option:--log4j2, or option:--python option::: Logging events. -- @@ -173,7 +176,7 @@ $ lttng disable-event --kernel --tracepoint --all-events ---- ==== -.Disable specific Apache log4j recording event rules in the default channel of a specific recording session. +.Disable specific Apache Log4j 1.x recording event rules in the default channel of a specific recording session. ==== See the option:--session option. diff --git a/doc/man/lttng-enable-event.1.txt b/doc/man/lttng-enable-event.1.txt index 94efe497c..9bcbdb24f 100644 --- a/doc/man/lttng-enable-event.1.txt +++ b/doc/man/lttng-enable-event.1.txt @@ -39,7 +39,7 @@ Create or enable one or more recording event rules to match Java/Python logging events: [verse] -*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--python) +*lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *enable-event* (option:--jul | option:--log4j | option:--log4j2 | option:--python) [option:--tracepoint] (option:--all | 'NAME'[,'NAME']...) [option:--loglevel='LOGLEVEL' | option:--loglevel-only='LOGLEVEL'] [option:--filter='EXPR'] [option:--session='SESSION'] [option:--channel='CHANNEL'] @@ -243,17 +243,17 @@ may change in the future. List the available user space tracepoints with `lttng list --userspace`. See man:lttng-list(1) to learn more. -For the `java.util.logging` (option:--jul option), Apache log4j (option:--log4j option), and Python (option:--python option) tracing domains:: +For the `java.util.logging` (option:--jul option), Apache 1.x log4j (option:--log4j option), Apache 2.x log4j (option:--log4j2 option), and Python (option:--python option) tracing domains:: With or without the option:--tracepoint option::: A logging statement. + As of LTTng{nbsp}{lttng_version}, this is the default and sole -instrumentation point type of the `java.util.logging`, Apache log4j, and -Python tracing domains, but this may change in the future. +instrumentation point type of the `java.util.logging`, Apache Log4j 1.x, Apache +log4j 2.x, and Python tracing domains, but this may change in the future. + List the available Java and Python loggers with `lttng list --jul`, -`lttng list --log4j`, and `lttng list --python`. See man:lttng-list(1) -to learn more. +`lttng list --log4j`, `lttng list --log4j2`, and `lttng list --python`. +See man:lttng-list(1) to learn more. [[event-name-cond]] @@ -366,7 +366,7 @@ User space (option:--userspace option):: * `FINEST` (300) * `ALL` (`INT32_MIN`) -Apache log4j (option:--log4j option):: +Apache Log4j 1.x (option:--log4j option):: + * `OFF` (`INT32_MAX`) * `FATAL` (50000) @@ -377,6 +377,17 @@ Apache log4j (option:--log4j option):: * `TRACE` (5000) * `ALL` (`INT32_MIN`) +Apache Log4j 2 (option:--log4j2 option):: ++ +* `OFF` (`0`) +* `FATAL` (100) +* `ERROR` (200) +* `WARN` (300) +* `INFO` (400) +* `DEBUG` (500) +* `TRACE` (600) +* `ALL` (`INT32_MAX`) + Python (option:--python option):: + * `CRITICAL` (50) @@ -570,11 +581,17 @@ Such an event record has a string field `logger_name` which contains the name of the `java.util.logging` logger from which LTTng creates{nbsp}__E__. -Apache log4j logging statement (option:--log4j and option:--tracepoint options):: +Apache Log4j 1.x logging statement (option:--log4j and option:--tracepoint options):: `lttng_log4j:event` + Such an event record has a string field `logger_name` which contains the -name of the Apache log4j logger from which LTTng creates{nbsp}__E__. +name of the Apache Log4j 1.x logger from which LTTng creates{nbsp}__E__. + +Apache Log4j 2 logging statement (option:--log4j2 and option:--tracepoint options):: + `lttng_log4j2:event` ++ +Such an event record has a string field `logger_name` which contains the +name of the Apache Log4j 2 logger from which LTTng creates{nbsp}__E__. Python logging statement (option:--python and option:--tracepoint options):: `lttng_python:event` @@ -637,7 +654,11 @@ option:-k, option:--kernel:: domain. option:-l, option:--log4j:: - Create or enable recording event rules in the Apache log4j tracing + Create or enable recording event rules in the Apache Log4j 1.x tracing + domain. + +option:--log4j2:: + Create or enable recording event rules in the Apache Log4j 2 tracing domain. option:-p, option:--python:: @@ -785,14 +806,14 @@ option:--tracepoint:: + With the option:--kernel or option:--userspace option::: LTTng tracepoint events. -With the option:--jul, option:--log4j, or option:--python option::: +With the option:--jul, option:--log4j, option:--log4j2, or option:--python option::: Logging events. With the option:--kernel, not specifying any of the instrumentation point type options is equivalent to specifying the option:--tracepoint option, but this default may change in the future. -With the option:--userspace, option:--jul, option:--log4j, and +With the option:--userspace, option:--jul, option:--log4j, option:--log4j2, and option:--python options, not specifying the option:--tracepoint option is equivalent to specifying it, but this default may change in the future. @@ -889,7 +910,7 @@ $ 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). +.Create a recording event rule which matches Apache Log4j 1.x logging events with a specific log level range (current recording session, specific channel). ==== See the option:--channel, option:--all, and option:--loglevel options. @@ -900,6 +921,17 @@ $ lttng enable-event --log4j --channel=my-loggers \ ---- ==== +.Create a recording event rule which matches Apache Log4j 2 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 --log4j2 --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()` diff --git a/doc/man/lttng-event-rule.7.txt b/doc/man/lttng-event-rule.7.txt index 2730996eb..8dd00e64b 100644 --- a/doc/man/lttng-event-rule.7.txt +++ b/doc/man/lttng-event-rule.7.txt @@ -33,7 +33,7 @@ pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='E Specify an event rule to match Java/Python logging events: [verse] -option:--type=(**jul** | **log4j** | **python**)**:logging** [option:--name='NAME'] +option:--type=(**jul** | **log4j** | **log4j2** | **python**)**:logging** [option:--name='NAME'] pass:[[]option:--log-level=('LOGLEVEL' | 'LOGLEVEL'.. | ..)] [option:--filter='EXPR'] @@ -158,9 +158,15 @@ List the available `java.util.logging` loggers with `lttng list --jul` See man:lttng-list(1) to learn more. `log4j:logging`:: - An Apache log4j logging statement. + An Apache Log4j 1.x logging statement. + -List the available Apache log4j loggers with `lttng list --log4j` +List the available Apache Log4j 1.x loggers with `lttng list --log4j` +See man:lttng-list(1) to learn more. + +`log4j2:logging`:: + An Apache Log4j 2 logging statement. ++ +List the available Apache Log4j 2 loggers with `lttng list --log4j2` See man:lttng-list(1) to learn more. `python:logging`:: @@ -192,6 +198,7 @@ name and __NAME__ is the tracepoint name. `jul:logging`:: `log4j:logging`:: +`log4j2:logging`:: `python:logging`:: The name of the Java or Python logger from which LTTng creates{nbsp}__E__. @@ -299,6 +306,17 @@ the option:--type option, from the most to the least severe: * `TRACE` (5000) * `ALL` (`INT32_MIN`) +`log4j2:logging`:: ++ +* `OFF` (`0`) +* `FATAL` (100) +* `ERROR` (200) +* `WARN` (300) +* `INFO` (400) +* `DEBUG` (500) +* `TRACE` (600) +* `ALL` (`INT32_MAX`) + `python:logging`:: + * `CRITICAL` (50) @@ -502,6 +520,9 @@ option:--event-name='RECORDNAME' |nloption:--log4j and nloption:--tracepoint |option:--type=++log4j:logging++ +|nloption:--log4j2 and nloption:--tracepoint +|option:--type=++log4j2:logging++ + |nloption:--python and nloption:--tracepoint |option:--type=++python:logging++ @@ -688,11 +709,17 @@ As of LTTng{nbsp}{lttng_version}, `jul` is an alias, but this may change in the future. `log4j:logging`::: - Apache log4j logging statement. + Apache Log4j 1.x logging statement. + As of LTTng{nbsp}{lttng_version}, `log4j` is an alias, but this may change in the future. +`log4j2:logging`::: + Apache Log4j 2 logging statement. ++ +As of LTTng{nbsp}{lttng_version}, `log4j2` is an alias, but this may +change in the future. + `python:logging`::: Python logging statement. + @@ -715,6 +742,7 @@ option:-n 'NAME', option:--name='NAME':: `jul:logging`:: `log4j:logging`:: +`log4j2:logging`:: `python:logging`:: The Java or Python logger name. diff --git a/doc/man/lttng-list.1.txt b/doc/man/lttng-list.1.txt index 7e6a95b3a..6de96fa4f 100644 --- a/doc/man/lttng-list.1.txt +++ b/doc/man/lttng-list.1.txt @@ -25,14 +25,14 @@ List the channels and recording event rules of a recording session: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--channel='CHANNEL'] 'SESSION' - [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] + [option:--kernel] [option:--userspace] [option:--jul] [option:--log4j] [option:--log4j2] [option:--python] List the available LTTng tracepoints, Linux system calls, and/or Java/Python loggers: [verse] *lttng* ['linkgenoptions:(GENERAL OPTIONS)'] *list* [option:--fields] - [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--python] + [option:--kernel [option:--syscall]] [option:--userspace] [option:--jul] [option:--log4j] [option:--log4j2] [option:--python] DESCRIPTION @@ -64,8 +64,8 @@ With the 'SESSION' argument:: their recording event rules. + Use the dedicated tracing domain options (option:--kernel, -option:--userspace, option:--jul, option:--log4j, and option:--python) -to only show specific channels. +option:--userspace, option:--jul, option:--log4j, option:--log4j2, and +option:--python) to only show specific channels. Without the 'SESSION' argument and with at least one dedicated tracing domain option:: + @@ -77,8 +77,8 @@ With the option:--kernel option:: The available, instrumented Linux system calls. With the option:--userspace option:: The available LTTng user space tracepoints. -With the option:--jul, option:--log4j, and/or option:--python options:: - The available `java.util.logging`, Apache log4j, and/or Python +With the option:--jul, option:--log4j, option:--log4j2, and/or option:--python options:: + The available `java.util.logging`, Apache Log4j 1.x, Apache Log4j 2 and/or Python logger names. -- + @@ -116,9 +116,16 @@ option:-k, option:--kernel:: option:-l, option:--log4j:: Without the 'SESSION' argument::: - List the Apache log4j logger names. + List the Apache Log4j 1.x logger names. With the 'SESSION' argument::: - Only list the Apache log4j channels and their recording event + Only list the Apache Log4j 1.x channels and their recording event + rules. + +option:--log4j2:: + Without the 'SESSION' argument::: + List the Apache Log4j 2 logger names. + With the 'SESSION' argument::: + Only list the Apache Log4j 2 channels and their recording event rules. option:-p, option:--python:: -- 2.34.1