This is an automated email from the ASF dual-hosted git repository. vy pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
commit ffea01f0e075a97e327aea5fa93e92fc17749b03 Author: Volkan Yazıcı <[email protected]> AuthorDate: Wed Jun 19 13:30:42 2024 +0200 Fix `flowtracing.adoc` examples (#2662) Co-authored-by: Piotr P. Karwasz <[email protected]> --- src/site/antora/antora.tmpl.yml | 2 + src/site/antora/antora.yml | 2 + .../ROOT/examples/manual/flowtracing/log4j2.json | 43 ++++++++++++ .../examples/manual/flowtracing/log4j2.properties | 36 ++++++++++ .../ROOT/examples/manual/flowtracing/log4j2.xml | 43 ++++++++++++ .../ROOT/examples/manual/flowtracing/log4j2.yaml | 40 +++++++++++ .../ROOT/examples/manual/flowtracing/logback.xml | 78 ++++++++++++++++++++++ src/site/antora/modules/ROOT/pages/faq.adoc | 2 +- .../modules/ROOT/pages/manual/architecture.adoc | 4 +- .../modules/ROOT/pages/manual/getting-started.adoc | 4 +- .../modules/ROOT/pages/manual/installation.adoc | 11 ++- .../modules/ROOT/pages/manual/pattern-layout.adoc | 8 +-- .../ROOT/pages/manual/systemproperties.adoc | 9 +++ .../modules/ROOT/pages/migrate-from-logback.adoc | 5 +- .../modules/ROOT/pages/migrate-from-slf4j.adoc | 12 ++-- .../antora/modules/ROOT/partials/concepts.adoc | 6 +- 16 files changed, 272 insertions(+), 33 deletions(-) diff --git a/src/site/antora/antora.tmpl.yml b/src/site/antora/antora.tmpl.yml index 872b271c3d..026a4b8843 100644 --- a/src/site/antora/antora.tmpl.yml +++ b/src/site/antora/antora.tmpl.yml @@ -45,9 +45,11 @@ asciidoc: project-id: "log4j" java-target-version: "${maven.compiler.target}" java-compiler-version: "${minimalJavaBuildVersion}" + logback-url: "https://logback.qos.ch"; logging-services-url: "https://logging.apache.org"; log4j2-url: "https://logging.apache.org/log4j/2.x"; lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor"; + slf4j-url: "https://www.slf4j.org"; # Dependency versions commons-csv-version: "${site-commons-csv.version}" commons-logging-version: "${site-commons-logging.version}" diff --git a/src/site/antora/antora.yml b/src/site/antora/antora.yml index b88f303616..cebad04aa2 100644 --- a/src/site/antora/antora.yml +++ b/src/site/antora/antora.yml @@ -45,9 +45,11 @@ asciidoc: project-id: "log4j" java-target-version: "8" java-compiler-version: "[17,18)" + logback-url: "https://logback.qos.ch"; logging-services-url: "https://logging.apache.org"; log4j2-url: "https://logging.apache.org/log4j/2.x"; lmax-disruptor-url: "https://lmax-exchange.github.io/disruptor/"; + slf4j-url: "https://www.slf4j.org"; # Dependency versions commons-csv-version: "1.2.3-commons-csv" commons-logging-version: "1.2.3-commons-logging" diff --git a/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.json b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.json new file mode 100644 index 0000000000..d20f770f85 --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.json @@ -0,0 +1,43 @@ +{ + "Configuration": { + + "MarkerFilter": { //<1> + "marker": "FLOW", + "onMatch": "ACCEPT", + "onMismatch": "NEUTRAL" + }, + + "Appenders": { + "Console": { + "name": "CONSOLE", + "PatternLayout": { + "MarkerPatternSelector": { + "defaultPattern": "%d %5p [%t] %c{1} -- %m%n",//<2> + "PatternMatch": [ + {//<3> + "key": "ENTER", + "pattern": "%d %5p [%t] %c{1} => %m%n" + }, + {//<4> + "key": "EXIT", + "pattern": "%d %5p [%t] %c{1} <= %m%n" + } + ] + } + } + } + }, + + "Loggers": { + "Root": { + "level": "WARN", + "AppenderRef": [ + { + "ref": "CONSOLE" + } + ] + } + } + + } +} diff --git a/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.properties b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.properties new file mode 100644 index 0000000000..edecbf818b --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.properties @@ -0,0 +1,36 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to you under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +filter.0.type = MarkerFilter #<1> +filter.0.marker = FLOW +filter.0.onMatch = ACCEPT +filter.0.onMismatch = NEUTRAL + +appender.0.type = Console +appender.0.name = CONSOLE +appender.0.layout.type = PatternLayout +appender.0.layout.patternSelector.type = MarkerPatternSelector +appender.0.layout.patternSelector.defaultPattern = "%d %5p [%t] %c{1} -- %m%n #<2> +appender.0.layout.patternSelector.properties.0.type = PatternMatch +appender.0.layout.patternSelector.properties.0.key = ENTER +appender.0.layout.patternSelector.properties.0.pattern = %d %5p [%t] %c{1} => %m%n #<3> +appender.0.layout.patternSelector.properties.1.type = PatternMatch +appender.0.layout.patternSelector.properties.1.key = EXIT +appender.0.layout.patternSelector.properties.1.pattern = %d %5p [%t] %c{1} <= %m%n #<4> + +rootLogger.level = WARN +rootLogger.appenderRef.0.ref = CONSOLE diff --git a/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.xml b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.xml new file mode 100644 index 0000000000..9c53bb7dda --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to you under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. + --> +<Configuration xmlns="https://logging.apache.org/xml/ns"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation=" + https://logging.apache.org/xml/ns + https://logging.apache.org/xml/ns/log4j-config-2.xsd";> + + <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/><!--1--> + + <Appenders> + <Console name="CONSOLE"> + <PatternLayout> + <MarkerPatternSelector defaultPattern="%d %5p [%t] %c{1} -- %m%n"><!--2--> + <PatternMatch key="ENTER" pattern="%d %5p [%t] %c{1} => %m%n"/><!--3--> + <PatternMatch key="EXIT" pattern="%d %5p [%t] %c{1} <= %m%n"/><!--4--> + </MarkerPatternSelector> + </PatternLayout> + </Console> + </Appenders> + + <Loggers> + <Root level="WARN"> + <AppenderRef ref="CONSOLE"/> + </Root> + </Loggers> + +</Configuration> diff --git a/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.yaml b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.yaml new file mode 100644 index 0000000000..89dea1393a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/flowtracing/log4j2.yaml @@ -0,0 +1,40 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to you under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +Configuration: + + MarkerFilter: #<1> + marker: "FLOW" + onMatch: "ACCEPT" + onMismatch: "NEUTRAL" + + Appenders: + Console: + name: "CONSOLE" + PatternLayout: + MarkerPatternSelector: + defaultPattern: "%d %5p [%t] %c{1} -- %m%n" #<2> + PatternMatch: + - key: "ENTER" #<3> + pattern: "%d %5p [%t] %c{1} => %m%n" + - key: "EXIT" #<4> + pattern: "%d %5p [%t] %c{1} <= %m%n" + + Loggers: + Root: + level: "WARN" + AppenderRef: + - ref: "CONSOLE" diff --git a/src/site/antora/modules/ROOT/examples/manual/flowtracing/logback.xml b/src/site/antora/modules/ROOT/examples/manual/flowtracing/logback.xml new file mode 100644 index 0000000000..c14f27370a --- /dev/null +++ b/src/site/antora/modules/ROOT/examples/manual/flowtracing/logback.xml @@ -0,0 +1,78 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + ~ Licensed to the Apache Software Foundation (ASF) under one or more + ~ contributor license agreements. See the NOTICE file distributed with + ~ this work for additional information regarding copyright ownership. + ~ The ASF licenses this file to you under the Apache License, Version 2.0 + ~ (the "License"); you may not use this file except in compliance with + ~ the License. You may obtain a copy of the License at + ~ + ~ http://www.apache.org/licenses/LICENSE-2.0 + ~ + ~ Unless required by applicable law or agreed to in writing, software + ~ distributed under the License is distributed on an "AS IS" BASIS, + ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + ~ See the License for the specific language governing permissions and + ~ limitations under the License. + --> +<!DOCTYPE configuration> +<configuration> + + <import class="ch.qos.logback.core.ConsoleAppender"/> + <import class="ch.qos.logback.core.filter.EvaluatorFilter"/> + <import class="ch.qos.logback.classic.boolex.OnMarkerEvaluator"/> + <import class="ch.qos.logback.classic.encoder.PatternLayoutEncoder"/> + <import class="ch.qos.logback.classic.turbo.MarkerFilter"/> + + <turboFilter class="MarkerFilter"><!--1--> + <Marker>FLOW</Marker> + <OnMatch>ACCEPT</OnMatch> + </turboFilter> + + <appender name="CONSOLE_DEFAULT" class="ConsoleAppender"> + <filter class="EvaluatorFilter"><!--2--> + <evaluator class="OnMarkerEvaluator"> + <marker>ENTER</marker> + <marker>EXIT</marker> + </evaluator> + <onMismatch>ACCEPT</onMismatch> + <onMatch>DENY</onMatch> + </filter> + <encoder class="PatternLayoutEncoder"><!--3--> + <pattern><![CDATA[%d %5p [%t] %c{1} -- %m%n]]></pattern> + </encoder> + </appender> + + <appender name="CONSOLE_FLOW_ENTER" class="ConsoleAppender"> + <filter class="EvaluatorFilter"><!--4--> + <evaluator class="OnMarkerEvaluator"> + <marker>ENTER</marker> + </evaluator> + <onMismatch>DENY</onMismatch> + <onMatch>ACCEPT</onMatch> + </filter> + <encoder class="PatternLayoutEncoder"><!--5--> + <pattern><![CDATA[%d %5p [%t] %c{1} => %m%n]]></pattern> + </encoder> + </appender> + + <appender name="CONSOLE_FLOW_EXIT" class="ConsoleAppender"> + <filter class="EvaluatorFilter"><!--6--> + <evaluator class="OnMarkerEvaluator"> + <marker>EXIT</marker> + </evaluator> + <onMismatch>DENY</onMismatch> + <onMatch>ACCEPT</onMatch> + </filter> + <encoder class="PatternLayoutEncoder"><!--7--> + <pattern><![CDATA[%d %5p [%t] %c{1} <= %m%n]]></pattern> + </encoder> + </appender> + + <root level="WARN"> + <appender-ref ref="CONSOLE_DEFAULT"/> + <appender-ref ref="CONSOLE_FLOW_ENTER"/> + <appender-ref ref="CONSOLE_FLOW_EXIT"/> + </root> + +</configuration> diff --git a/src/site/antora/modules/ROOT/pages/faq.adoc b/src/site/antora/modules/ROOT/pages/faq.adoc index 02b738e738..024005ca19 100644 --- a/src/site/antora/modules/ROOT/pages/faq.adoc +++ b/src/site/antora/modules/ROOT/pages/faq.adoc @@ -174,7 +174,7 @@ In contrast, Log4j API has methods for up to ten unrolled parameters. Log4j API lets you log any `CharSequence` or `Object`. Log4j Core can log any `Object` that implements `CharSequence` or `org.apache.logging.log4j.util.StringBuilderFormattable` without creating garbage. -* The https://www.slf4j.org/api/org/slf4j/spi/LocationAwareLogger.html#log(org.slf4j.Marker,java.lang.String,int,java.lang.String,java.lang.Object%5B%5D,java.lang.Throwable)[`org.slf4j.spi.LocationAwareLogger::log`] method is not yet implemented in a garbage-free manner in the `log4j-slf4j-impl` and `log4j-slf4j2-impl` bridges. +* The {slf4j-url}/api/org/slf4j/spi/LocationAwareLogger.html#log(org.slf4j.Marker,java.lang.String,int,java.lang.String,java.lang.Object%5B%5D,java.lang.Throwable)[`org.slf4j.spi.LocationAwareLogger::log`] method is not yet implemented in a garbage-free manner in the `log4j-slf4j-impl` and `log4j-slf4j2-impl` bridges. It creates a new message object for each call. [#gc-free-domain-object] diff --git a/src/site/antora/modules/ROOT/pages/manual/architecture.adoc b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc index 7f9ee76b1b..2ca835f97d 100644 --- a/src/site/antora/modules/ROOT/pages/manual/architecture.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/architecture.adoc @@ -177,8 +177,8 @@ where the event should always be logged regardless of the configuration. However, it is generally recommended that a Marker with a corresponding global Marker Filter be used instead. -http://logging.apache.org/log4j/1.2/manual.html[Log4j 1.x] and -http://logback.qos.ch/manual/architecture.html#effectiveLevel[Logback] +{logging-services-url}/log4j/1.x/manual.html[Log4j 1] and +{logback-url}/manual/architecture.html#effectiveLevel[Logback] both have the concept of "Level Inheritance". In Log4j 2, Loggers and LoggerConfigs are two different objects so this concept is implemented differently. Each Logger references the appropriate LoggerConfig which diff --git a/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc b/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc index 0f57f38d19..65b628c180 100644 --- a/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/getting-started.adoc @@ -218,7 +218,7 @@ dependencies { If your application has (direct or transitive!) dependencies that use another logging API, you need to <<logging-bridge,bridge>> that to Log4j. This way the foreign logging API calls will effectively be consumed by Log4j too. -{slf4j-link} is another logging API used pretty common in the wild. +{slf4j-url}[SLF4J] is another logging API used pretty common in the wild. (xref:manual/installation.adoc[] covers all supported foreign APIs.) Let's see how you can use the `log4j-slf4j2-impl` bridge to support SLF4J: @@ -374,7 +374,7 @@ dependencies { If your library has (direct or transitive!) dependencies that use another logging API, you need to <<logging-bridge,bridge>> that to Log4j. This way the foreign logging API calls will effectively be consumed by Log4j too. -{slf4j-link} is another logging API used pretty common in the wild. +{slf4j-url}[SLF4J] is another logging API used pretty common in the wild. (xref:manual/installation.adoc[] covers all supported foreign APIs.) Let's see how you can use the `log4j-slf4j2-impl` bridge to support SLF4J: diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index 82462b645a..c1de6d46d7 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -17,7 +17,6 @@ :jpl-link: https://openjdk.org/jeps/264[JPL (Java Platform Logging)] :jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)] -:slf4j-link: https://www.slf4j.org/[SLF4J] = Installation @@ -186,9 +185,9 @@ The bridge that translates Log4j API calls to {jul-link}. See <<impl-jul>> for the installation instructions. `log4j-to-slf4j`:: -The bridge that translates Log4j API calls to {slf4j-link}. +The bridge that translates Log4j API calls to {slf4j-url}[SLF4J]. Since currently only -https://logback.qos.ch/[Logback] implements SLF4J natively, refer to <<impl-logback>> for the installation instructions. +{logback-url}[Logback] implements SLF4J natively, refer to <<impl-logback>> for the installation instructions. [IMPORTANT] ==== @@ -275,7 +274,7 @@ The following sections explain the installation of Log4j-provided bridges. [#impl-core-bridge-slf4j] ===== Installing SLF4J-to-Log4j bridge -You can translate {slf4j-link} calls to Log4j API using the `log4j-slf4j2-impl` artifact: +You can translate {slf4j-url}[SLF4J] calls to Log4j API using the `log4j-slf4j2-impl` artifact: [tabs,opts=sync] ==== @@ -602,7 +601,7 @@ To configure JUL, see https://docs.oracle.com/en/java/javase/{java-target-versio [#impl-logback] === Installing Logback -To install https://logback.qos.ch/[Logback] as the logging implementation, you only need to add a Log4j-to-SLF4J bridge: +To install {logback-url}[Logback] as the logging implementation, you only need to add a Log4j-to-SLF4J bridge: [tabs,opts=sync] ==== @@ -641,4 +640,4 @@ runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j' // Log4j-to-SLF4J bridge ==== -To configure Logback, see https://logback.qos.ch/manual/configuration.html[Logback's configuration documentation]. +To configure Logback, see {logback-url}/manual/configuration.html[Logback's configuration documentation]. diff --git a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc index 3444c79423..ce0b01b7c1 100644 --- a/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/pattern-layout.adoc @@ -732,14 +732,10 @@ The `style` parameter is a comma-separated list of the following directives: See <<ansi-modifiers>> for the syntax of `<style_expression>`. | STYLE=default -| Sets the default style, which is equivalent to the following sequence of directives: -`FATAL=bold red, ERROR=bold red, WARN=yellow, INFO=green, DEBUG=cyan, TRACE=black`. +| Sets the default style, which is equivalent to the following sequence of directives: `FATAL=bold red, ERROR=bold red, WARN=yellow, INFO=green, DEBUG=cyan, TRACE=black`. | STYLE=logback -| Applies the style used by -https://logback.qos.ch/manual/layouts.html#coloring[Logback's `%highlight` converter], -which is equivalent to the following sequence of directives: -`FATAL=blink bold red, ERROR=bold red, WARN=red, INFO=blue, DEBUG=normal, TRACE=normal`. +| Applies the style used by {logback-url}/manual/layouts.html#coloring[Logback's `%highlight` converter], which is equivalent to the following sequence of directives: `FATAL=blink bold red, ERROR=bold red, WARN=red, INFO=blue, DEBUG=normal, TRACE=normal`. |=== You can use the default colors with: diff --git a/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc b/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc index 6e0f5e74c5..c133f7c0a8 100644 --- a/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/systemproperties.adoc @@ -182,6 +182,15 @@ include::partial$manual/systemproperties/properties-jansi.adoc[leveloffset=+2] To configure the thread context used by Log4j Core, you can use the following properties: +[WARNING] +==== +These configuration properties are only used by Log4j Core and {log4j2-url}/manual/simple-logger.html[Simple Logger] of Log4j API. + +The `log4j-to-slf4j` logging bridge delegates `ThreadContext` calls to {slf4j-url}/api/org/slf4j/MDC.html[the SLF4J `MDC` class]. + +The `log4j-to-jul` logging bridge ignores all `ThreadContext` method calls. +==== + include::partial$manual/systemproperties/properties-thread-context.adoc[leveloffset=+2] [id=properties-transport-security] diff --git a/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc b/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc index a9662347d9..9d2ac5cd24 100644 --- a/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc +++ b/src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc @@ -15,12 +15,9 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -:logback-link: https://logback.qos.ch/[Logback] -:slf4j-link: https://www.slf4j.org/[SLF4J] - = Migrating from Logback -{logback-link} is a logging implementation for the {slf4j-link} logging API, just like Log4j Core is a logging implementation for the xref:manual/api.adoc[Log4j API]. +{logback-url}[Logback] is a logging implementation for the {slf4j-url}[SLF4J] logging API, just like Log4j Core is a logging implementation for the xref:manual/api.adoc[Log4j API]. In this page we will guide you through migrating from Logback to Log4j Core as your logging implementation. [TIP] diff --git a/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc b/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc index ab0f9e0572..2f389f6787 100644 --- a/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc +++ b/src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc @@ -15,13 +15,9 @@ Licensed to the Apache Software Foundation (ASF) under one or more limitations under the License. //// -:logback-link: https://logback.qos.ch/[Logback] -:slf4j-link: https://www.slf4j.org/[SLF4J] -:slf4j-javadoc-url: https://www.slf4j.org/api - = Migrating from SLF4J -{slf4j-link} is a logging API whose reference implementation is {logback-link}, just like xref:manual/api.adoc[Log4j API] is a logging API whose reference implementation is Log4j Core. +{slf4j-url}[SLF4J] is a logging API whose reference implementation is {logback-url}[Logback], just like xref:manual/api.adoc[Log4j API] is a logging API whose reference implementation is Log4j Core. In this page we will guide you through migrating from SLF4J to Log4j API as your logging API. [TIP] @@ -56,15 +52,15 @@ This you can use to . or run OpenRewrite to automatically migrate the code. ==== + -{slf4j-javadoc-url}/org/slf4j/LoggerFactory.html[`org.slf4j.LoggerFactory`]:: +{slf4j-url}/api/org/slf4j/LoggerFactory.html[`org.slf4j.LoggerFactory`]:: Replace its usages with link:javadoc/log4j-api/org/apache/logging/log4j/LogManager.html[`org.apache.logging.log4j.LogManager`]. Note that `LogManager.getLogger(Foo.class)` can be simplified as `LogManager.getLogger()`, if `Foo` is the enclosing class of the field. + -{slf4j-javadoc-url}/org/slf4j/Logger.html[`org.slf4j.Logger`]:: +{slf4j-url}/api/org/slf4j/Logger.html[`org.slf4j.Logger`]:: Replace its usages with link:javadoc/log4j-api/org/apache/logging/log4j/Logger.html[`org.apache.logging.log4j.Logger`]. Since SLF4J's `Logger` is almost a parent of Log4j's `Logger`, most methods should work without any changes. + -{slf4j-javadoc-url}/org/slf4j/MDC.html[`org.slf4j.MDC`]:: +{slf4j-url}/api/org/slf4j/MDC.html[`org.slf4j.MDC`]:: Replace its usages with link:javadoc/log4j-api/org/apache/logging/log4j/ThreadContext.html[`org.apache.logging.log4j.ThreadContext`]. . If you use https://projectlombok.org/features/log[`@Slf4j` from Lombok], you need to replace them with `@Log4j2` instead. diff --git a/src/site/antora/modules/ROOT/partials/concepts.adoc b/src/site/antora/modules/ROOT/partials/concepts.adoc index 883b2e5f21..04ef812bab 100644 --- a/src/site/antora/modules/ROOT/partials/concepts.adoc +++ b/src/site/antora/modules/ROOT/partials/concepts.adoc @@ -25,8 +25,6 @@ :jcl-link: https://commons.apache.org/proper/commons-logging/[JCL (Apache Commons Logging)] :jpl-link: https://openjdk.org/jeps/264[JPL (Java Platform Logging)] :jul-link: https://docs.oracle.com/en/java/javase/{java-target-version}/core/java-logging-overview.html[JUL (Java Logging)] -:logback-link: https://logback.qos.ch/[Logback] -:slf4j-link: https://www.slf4j.org/[SLF4J] :jboss-logging-link: https://github.com/jboss-logging/jboss-logging[JBoss Logging] // end::inc[] @@ -38,7 +36,7 @@ Logging API:: A logging API is an interface your code or your dependencies directly logs against. It is required at compile-time. It is implementation agnostic to ensure that your application can write logs, but is not tied to a specific logging implementation. -Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs. +Log4j API, {slf4j-url}[SLF4J], {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-link} are major logging APIs. // end::api[] @@ -47,7 +45,7 @@ Log4j API, {slf4j-link}, {jul-link}, {jcl-link}, {jpl-link} and {jboss-logging-l [#logging-impl] Logging implementation:: A logging implementation is only required at runtime and can be changed without the need to recompile your software. -Log4j Core, {jul-link}, {logback-link} are the most well-known logging implementations. +Log4j Core, {jul-link}, {logback-url}[Logback] are the most well-known logging implementations. // end::impl[]
