ppkarwasz commented on code in PR #2654: URL: https://github.com/apache/logging-log4j2/pull/2654#discussion_r1640136244
########## src/site/antora/modules/ROOT/pages/manual/migration.adoc: ########## @@ -16,5 +16,247 @@ Licensed to the Apache Software Foundation (ASF) under one or more //// = Migrating from Log4j 2 +:sonatype-url: https://central.sonatype.com/artifact/org.apache.logging.log4j -TODO +[NOTE] +==== +If you are migrating from Log4j 1, check the +{log4j2-url}/manual/migration.html[Migrating from Log4j 1] +guide in the Log4j 2 manual. +==== + +Since Log4j 3 uses Log4j 2 API as logging API, no code changes should be necessary for most users. + +In order to migrate to Log4j 3, you only need to: + +* <<runtime-dependencies,update your dependencies>>, +* if you use +xref:manual/systemproperties.adoc[configuration properties] +to fine tune the Log4j 3 backend, +<<properties-configuration-file,check your configuration properties>>, +* if you used the Java properties configuration format, <<properties-configuration-file,migrate your configuration file>>, + +[#runtime-dependencies] +== Runtime dependencies + +Log4j 2 Core contains many features that depend on optional runtime dependencies. +In order to comply with the Java Platform Module System and help users managing those dependencies, some features were moved to separate Maven modules. +This change has the following advantages: + +* you don't need to consult the documentation to find out, which third-party libraries are necessary to use a specific feature: adding the appropriate Log4j 3 artifact is enough. +* Log4j 3 does not have optional dependencies, so third-party libraries used by Log4j will be upgraded **automatically** by your dependency management tool, when you upgrade Log4j. + +The following `log4j-core` features were moved to their own modules or were removed: + +.New Log4j 3 modules +[cols="1,1"] +|=== +| Log4j 2 feature | Log4j 3 module + +| xref:manual/appenders.adoc#BlockingQueueFactory[Asynchronous appender: JCTools-based queue] +| {sonatype-url}/log4j-jctools[`log4j-jctools`] + +| xref:manual/async.adoc[Asynchronous logger] +| {sonatype-url}/log4j-async-logger[`log4j-async-logger`] + +| {log4j2-url}/manual/appenders.html#CassandraAppender[Cassandra appender] +| _removed without replacement_ +footnote:removal[If you are using these components, and you can help us to maintain them, please contact us on our link:/support.html[support channels].] + +| {log4j2-url}/manual/appenders.html#NoSQLAppenderApacheCouchDB[CouchDB appender] +| _removed without replacement_ footnote:removal[] + +| xref:manual/configuration.adoc#configuration-with-properties[Configuration file: Java properties format] +| {sonatype-url}/log4j-config-properties[`log4j-config-properties`] + +| xref:manual/configuration.adoc#configuration-with-yaml[Configuration file: YAML format] +| {sonatype-url}/log4j-config-yaml[`log4j-config-yaml`] + +| xref:manual/layouts.adoc#CSVLayouts[CSV layouts] +| {sonatype-url}/log4j-csv[`log4j-csv`] + +| {log4j2-url}/manual/layouts.html#GELFLayout[GELF layout] +| _removed without replacement_ footnote:removal[] + +| xref:manual/appenders.adoc#JDBCAppender[JDBC appender] +| {sonatype-url}/log4j-jdbc[`log4j-jdbc`] + +| xref:manual/appenders.adoc#JDBCPoolingDriver[JDBC appender: DBCP 2 connection source] +| {sonatype-url}/log4j-jdbc-dbcp2[`log4j-jdbc-dbcp2`] + +| xref:manual/appenders.adoc#JDBCDataSource[JDBC appender: JNDI connection source] +| {sonatype-url}/log4j-jndi[`log4j-jndi`] + +| {log4j2-url}/manual/appenders.html#JeroMQAppender[JeroMQ appender] +| external +https://github.com/fbacchella/loghublog4j2#zmqappender[`loghublog4j2` maintained by Fabrice Bacchella] + +| {log4j2-url}/manual/appenders.html#JMSAppender[JMS appender: Java EE version] +| _removed without replacement_ footnote:removal[] + +| xref:manual/lookups.adoc#JndiLookup[JNDI lookup] +| {sonatype-url}/log4j-jndi[`log4j-jndi`] + +| {log4j2-url}/manual/appenders.html#JPAAppender[JPA appender] +| _removed without replacement_ footnote:removal[] + +| {log4j2-url}/log4j-taglib.html[JSP Tag library] +| _removed without replacement_ footnote:removal[] + +| {log4j2-url}/manual/appenders.html#KafkaAppender[Kafka appender] +| _removed without replacement_ footnote:removal[] + +| xref:manual/lookups.adoc#KubernetesLookup[Kubernetes lookup] +| external +https://github.com/fabric8io/kubernetes-client/blob/main/doc/KubernetesLog4j.md[`kubernetes-log4j` maintained by Fabric8] + +| xref:manual/scripts.adoc[Scripting support] +| {sonatype-url}/log4j-script[`log4j-script`] + +| {log4j2-url}/manual/webapp.html[Servlet application support: Java EE version] +| _removed without replacement_ footnote:removal[] + +| {log4j2-url}/manual/appenders.html#SMTPAppender[SMTP appender: Java EE version] +| _removed without replacement_ footnote:removal[] + +| {log4j2-url}/manual/lookups.html#_spring_boot_lookup[Spring Boot lookup] +| integrated into +https://central.sonatype.com/artifact/org.springframework.boot/spring-boot[`spring-boot`] +version 3.0.0 or later + +|=== + +[#system-properties] +== Migrate configuration properties + +In order to support per-logger context configuration properties, the configuration properties sub-system of Log4j has been rewritten and the naming convention of properties have changed. +To help you with the migration process a backward compatibility system has been implemented, which translates Log4j 2 property names to their Log4j 3 equivalents. + +If you use configuration properties to finely tune Log4j Core, make sure that: + +* either you use the naming convention from the +xref:manual/systemproperties.adoc[Log4j 3 configuration properties] +page (recommended), +* or you use the naming convention from the +{log4j2-url}/manual/systemproperties.html[Log4j 2 configuration properties] +page. Review Comment: Fixed in dbe9112e31ea5e41a910b408936b79dc507c8c3f -- 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]
