ppkarwasz commented on code in PR #2625: URL: https://github.com/apache/logging-log4j2/pull/2625#discussion_r1618750171
########## src/site/antora/modules/ROOT/pages/migrate-from-logback.adoc: ########## @@ -0,0 +1,65 @@ +//// +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. +//// + +: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]. +In this page we will guide you through migrating from Logback to Log4j Core as your logging implementation. + +[TIP] +==== +Instead of migrating your logging implementation, Logback, are you looking for migrating your logging API, SLF4J? +Please refer to xref:migrate-from-slf4j.adoc[]. +==== + +.This guide assumes you know the logging API, implementation, and bridge concepts. If not, click for an introduction. +[%collapsible] +==== + +include::partial$concepts.adoc[tag=!software-type] + +==== + +[#migrating] +== Migrating + +You either have an application using Logback at runtime, or have a library using Logback for tests. +In either case, you can replace Logback with Log4j Core as follows: + +. Remove `ch.qos.logback:logback-classic` dependency Review Comment: Users need also to adjust the bridges, so at least they need to replace `log4j-to-slf4j` with `log4j-slf4j-impl`, but other APIs need other replacements too. ########## src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc: ########## @@ -0,0 +1,67 @@ +//// +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. +//// + +:logback-link: https://logback.qos.ch/[Logback] +:slf4j-link: https://www.slf4j.org/[SLF4J] + += 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. +In this page we will guide you through migrating from SLF4J to Log4j API as your logging API. + +[TIP] +==== +Instead of migrating your logging API, SLF4J, are you looking for migrating your logging implementation, Logback? +Please refer to xref:migrate-from-logback.adoc[]. +==== + +.This guide assumes you know the logging API, implementation, and bridge concepts. If not, click for an introduction. +[%collapsible] +==== + +include::partial$concepts.adoc[tag=!software-type] + +==== + +[#migrating] +== Migrating + +If your application or library logs using SLF4J, you can migrate it to Log4j API as follows: + +. Remove `org.slf4j:slf4j-api` dependency +. Follow the instructions shared in the _"Getting started"_ page for xref:manual/getting-started.adoc#using-api[installing `log4j-api` and using it] +. Search for `org.slf4j` usages in your project and replace them with Log4j API equivalents Review Comment: I think we should be more explicit than that. We should explain that SLF4J's `Logger` methods are mostly a subset of Log4j `Logger` methods. In general users should start by: * replacing all occurrences of the Java [`org.slf4j.LoggerFactory`](https://www.slf4j.org/api/org/slf4j/LoggerFactory.html) type with [`org.apache.logging.log4j.LogManager`](https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/LogManager.html), * replacing all occurrences of the Java [`org.slf4j.Logger`](https://www.slf4j.org/api/org/slf4j/Logger.html) type with [`org.apache.logging.log4j.Logger`](https://logging.apache.org/log4j/2.x/javadoc/log4j-api/org/apache/logging/log4j/Logger.html) That should solve 99% of the call sites and it does not modify behavior: either the code behaves in the same way or it fails to compile. Users that use `MDC`, `Marker` and `LoggingEventBuilder`, might require further instructions. ########## src/site/antora/modules/ROOT/pages/migrate-from-slf4j.adoc: ########## @@ -0,0 +1,67 @@ +//// +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. +//// + +:logback-link: https://logback.qos.ch/[Logback] +:slf4j-link: https://www.slf4j.org/[SLF4J] + += 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. +In this page we will guide you through migrating from SLF4J to Log4j API as your logging API. + +[TIP] +==== +Instead of migrating your logging API, SLF4J, are you looking for migrating your logging implementation, Logback? +Please refer to xref:migrate-from-logback.adoc[]. +==== + +.This guide assumes you know the logging API, implementation, and bridge concepts. If not, click for an introduction. +[%collapsible] +==== + +include::partial$concepts.adoc[tag=!software-type] + +==== + +[#migrating] +== Migrating + +If your application or library logs using SLF4J, you can migrate it to Log4j API as follows: + +. Remove `org.slf4j:slf4j-api` dependency +. Follow the instructions shared in the _"Getting started"_ page for xref:manual/getting-started.adoc#using-api[installing `log4j-api` and using it] +. Search for `org.slf4j` usages in your project and replace them with Log4j API equivalents ++ +[TIP] +==== +Even though this search-and-replace is pretty much straight forward, it can be overwhelming. +You can use https://docs.openrewrite.org/recipes/java/logging/log4j/slf4jtolog4j[the SLF4J to Log4j API migration OpenRewrite recipe] to automate this process. +==== + +At this stage, you should have your application or library logging using Log4j API. + +If it is a library that you migrated,:: +then you don't need to take any extra steps. +Unlike applications, libraries should be logging implementation agnostic. +That is, libraries should log through a logging API, but leave the decision of the logging implementation to the application. + +If it is an application that you migrated, and you are not using Log4j Core as your logging implementation,:: +then you can consider doing so. +Certain xref:manual/api.adoc[Log4j API features] (e.g., xref:manual/garbagefree.adoc[garbage-free logging]) require an end-to-end setup which is mostly possible using Log4j API in combination with Log4j Core. ++ +See xref:manual/installation.adoc[] for installing Log4j Core. + +If you are using Logback, refer to xref:migrate-from-logback.adoc[]. Review Comment: Can we add a reference to OpenRewrite at the end: https://docs.openrewrite.org/recipes/java/logging/log4j/slf4jtolog4j The instructions in the recipe are more complete and precise. We should also make a note for Lombok users that replacing `@Slf4j` with `@Log4j2` (or whatever those annotations are) is usually sufficient for the migration. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
