Skip to content

Commit 7b53c64

Browse files
ppkarwaszppkarwasz
committed
Create "Migrate from Log4j 2" page
We create a "Migrate from Log4j 2" that specifies: - the required changes in the runtime classpath due to the splitting of modules, - a warning about the change of the naming convention for configuration properties, - a list of migration rules for users that love the Java properties configuration format. Part of #2540.
1 parent fc905bc commit 7b53c64

File tree

4 files changed

+248
-3
lines changed

4 files changed

+248
-3
lines changed

‎log4j-core/src/main/java/org/apache/logging/log4j/core/net/Facility.java

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222
* The facility codes used by the Syslog system.
2323
*
2424
* <table>
25-
* <caption>Facilities</caption>
25+
* <caption>Facility and corresponding numerical codes</caption>
2626
* <tr>
2727
* <th>Numerical Code</th>
2828
* <th>Facility</th>

‎src/site/antora/modules/ROOT/nav.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -43,14 +43,14 @@
4343
* xref:manual/performance.adoc[]
4444
** xref:manual/async.adoc[]
4545
** xref:manual/garbagefree.adoc[]
46+
* xref:manual/migration.adoc[]
4647
4748
.References
4849
* xref:plugin-reference.adoc[Plugin reference]
4950
* xref:javadoc.adoc[Java API reference]
5051
5152
.Resources
5253
* xref:faq.adoc[F.A.Q.]
53-
* xref:manual/migration.adoc[]
5454
* xref:migrate-from-logback.adoc[]
5555
* xref:migrate-from-slf4j.adoc[]
5656
* xref:hibernate.adoc[]

‎src/site/antora/modules/ROOT/pages/manual/configuration.adoc

+3
Original file line numberDiff line numberDiff line change
@@ -145,10 +145,13 @@ XML::
145145
+
146146
Since XML was the original configuration format developed, the mapping from configuration nodes and XML elements is trivial:
147147
+
148+
[id=configuration-with-xml]
149+
====
148150
* Each configuration node is represented by an XML element.
149151
* Each configuration attribute is represented by an XML attribute.
150152
* The **plugin type** of a node is equal to the name of the XML tag.
151153
* Each configuration nested element is represented by a nested XML element.
154+
====
152155
+
153156
[NOTE]
154157
====

‎src/site/antora/modules/ROOT/pages/manual/migration.adoc

+243-1
Original file line numberDiff line numberDiff line change
@@ -16,5 +16,247 @@ Licensed to the Apache Software Foundation (ASF) under one or more
1616
////
1717
1818
= Migrating from Log4j 2
19+
:sonatype-url: https://central.sonatype.com/artifact/org.apache.logging.log4j
1920
20-
TODO
21+
[NOTE]
22+
====
23+
If you are migrating from Log4j 1, check the
24+
{log4j2-url}/manual/migration.html[Migrating from Log4j 1]
25+
guide in the Log4j 2 manual.
26+
====
27+
28+
Since Log4j 3 uses Log4j 2 API as logging API, no code changes should be necessary for most users.
29+
30+
In order to migrate to Log4j 3, you only need to:
31+
32+
* <<runtime-dependencies,update your dependencies>>,
33+
* if you use
34+
xref:manual/systemproperties.adoc[configuration properties]
35+
to fine tune the Log4j 3 backend,
36+
<<properties-configuration-file,check your configuration properties>>,
37+
* if you used the Java properties configuration format, <<properties-configuration-file,migrate your configuration file>>,
38+
39+
[#runtime-dependencies]
40+
== Runtime dependencies
41+
42+
Log4j 2 Core contains many features that depend on optional runtime dependencies.
43+
In order to comply with the Java Platform Module System and help users managing those dependencies, some features were moved to separate Maven modules.
44+
This change has the following advantages:
45+
46+
* 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.
47+
* 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.
48+
49+
The following `log4j-core` features were moved to their own modules or were removed:
50+
51+
.New Log4j 3 modules
52+
[cols="1,1"]
53+
|===
54+
| Log4j 2 feature | Log4j 3 module
55+
56+
| xref:manual/appenders.adoc#BlockingQueueFactory[Asynchronous appender: JCTools-based queue]
57+
| {sonatype-url}/log4j-jctools[`log4j-jctools`]
58+
59+
| xref:manual/async.adoc[Asynchronous logger]
60+
| {sonatype-url}/log4j-async-logger[`log4j-async-logger`]
61+
62+
| {log4j2-url}/manual/appenders.html#CassandraAppender[Cassandra appender]
63+
| _removed without replacement_
64+
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].]
65+
66+
| {log4j2-url}/manual/appenders.html#NoSQLAppenderApacheCouchDB[CouchDB appender]
67+
| _removed without replacement_ footnote:removal[]
68+
69+
| xref:manual/configuration.adoc#configuration-with-properties[Configuration file: Java properties format]
70+
| {sonatype-url}/log4j-config-properties[`log4j-config-properties`]
71+
72+
| xref:manual/configuration.adoc#configuration-with-yaml[Configuration file: YAML format]
73+
| {sonatype-url}/log4j-config-yaml[`log4j-config-yaml`]
74+
75+
| xref:manual/layouts.adoc#CSVLayouts[CSV layouts]
76+
| {sonatype-url}/log4j-csv[`log4j-csv`]
77+
78+
| {log4j2-url}/manual/layouts.html#GELFLayout[GELF layout]
79+
| _removed without replacement_ footnote:removal[]
80+
81+
| xref:manual/appenders.adoc#JDBCAppender[JDBC appender]
82+
| {sonatype-url}/log4j-jdbc[`log4j-jdbc`]
83+
84+
| xref:manual/appenders.adoc#JDBCPoolingDriver[JDBC appender: DBCP 2 connection source]
85+
| {sonatype-url}/log4j-jdbc-dbcp2[`log4j-jdbc-dbcp2`]
86+
87+
| xref:manual/appenders.adoc#JDBCDataSource[JDBC appender: JNDI connection source]
88+
| {sonatype-url}/log4j-jndi[`log4j-jndi`]
89+
90+
| {log4j2-url}/manual/appenders.html#JeroMQAppender[JeroMQ appender]
91+
| external
92+
https://github.com/fbacchella/loghublog4j2#zmqappender[`loghublog4j2` maintained by Fabrice Bacchella]
93+
94+
| {log4j2-url}/manual/appenders.html#JMSAppender[JMS appender: Java EE version]
95+
| _removed without replacement_ footnote:removal[]
96+
97+
| xref:manual/lookups.adoc#JndiLookup[JNDI lookup]
98+
| {sonatype-url}/log4j-jndi[`log4j-jndi`]
99+
100+
| {log4j2-url}/manual/appenders.html#JPAAppender[JPA appender]
101+
| _removed without replacement_ footnote:removal[]
102+
103+
| {log4j2-url}/log4j-taglib.html[JSP Tag library]
104+
| _removed without replacement_ footnote:removal[]
105+
106+
| {log4j2-url}/manual/appenders.html#KafkaAppender[Kafka appender]
107+
| _removed without replacement_ footnote:removal[]
108+
109+
| xref:manual/lookups.adoc#KubernetesLookup[Kubernetes lookup]
110+
| external
111+
https://github.com/fabric8io/kubernetes-client/blob/main/doc/KubernetesLog4j.md[`kubernetes-log4j` maintained by Fabric8]
112+
113+
| xref:manual/scripts.adoc[Scripting support]
114+
| {sonatype-url}/log4j-script[`log4j-script`]
115+
116+
| {log4j2-url}/manual/webapp.html[Servlet application support: Java EE version]
117+
| _removed without replacement_ footnote:removal[]
118+
119+
| {log4j2-url}/manual/appenders.html#SMTPAppender[SMTP appender: Java EE version]
120+
| _removed without replacement_ footnote:removal[]
121+
122+
| {log4j2-url}/manual/lookups.html#_spring_boot_lookup[Spring Boot lookup]
123+
| integrated into
124+
https://central.sonatype.com/artifact/org.springframework.boot/spring-boot[`spring-boot`]
125+
version 3.0.0 or later
126+
127+
|===
128+
129+
[#system-properties]
130+
== Migrate configuration properties
131+
132+
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.
133+
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.
134+
135+
If you use configuration properties to finely tune Log4j Core, make sure that:
136+
137+
* either you use the naming convention from the
138+
xref:manual/systemproperties.adoc[Log4j 3 configuration properties]
139+
page (recommended),
140+
* or you use the naming convention from the
141+
{log4j2-url}/manual/systemproperties.html[Log4j 2 configuration properties]
142+
page.
143+
144+
Most Log4j 3 configuration properties sources are **case-sensitive** and fuzzy matching is not applied to those sources.
145+
146+
[#properties-configuration-file]
147+
== Java properties configuration file format
148+
149+
The Java properties configuration file format in Log4j 3 has been rewritten to use
150+
https://github.com/FasterXML/jackson-dataformats-text/blob/2.18/properties/README.md[`jackson-dataformat-properties`]
151+
to convert Java properties into the native JSON configuration file format.
152+
See
153+
https://github.com/FasterXML/jackson-dataformats-text/blob/2.18/properties/README.md[Jackson documentation]
154+
for more details on the conversion.
155+
156+
The only significant changes between the Log4j 2 and Log4j 3 properties format are:
157+
158+
. As an alternative to using the `type` configuration attribute to specify the **plugin type** of a Log4j component, you can append the plugin type to the prefix of the parent component.
159+
For example, instead of:
160+
+
161+
[source,properties]
162+
----
163+
appender.0.type = Console
164+
appender.0.name = CONSOLE
165+
appender.1.type = File
166+
appender.1.name = MAIN
167+
appender.1.fileName = logs/main.log
168+
appender.2.type = File
169+
appender.2.name = DEBUG_LOG
170+
appender.2.fileName = logs/debug.log
171+
----
172+
+
173+
you can write:
174+
+
175+
[source,properties]
176+
----
177+
Appenders.Console.name = CONSOLE
178+
Appenders.File[1].name = MAIN
179+
Appenders.File[1].fileName = logs/main.log
180+
Appenders.File[2].name = DEBUG_LOG
181+
Appenders.File[2].fileName = logs/debug.log
182+
----
183+
184+
. The
185+
{log4j2-url}/manual/configuration.html#java-properties-features[Java properties format specific quirks]
186+
are no longer recognized, which means that:
187+
188+
* The following direct children of `Configuration` need to use the same prefix as the other formats:
189+
+
190+
--
191+
** You need to replace the `appender` prefix with `Appenders`,
192+
** You need to replace the `logger` prefix with `Loggers`,
193+
** You need to replace the `script` prefix with `Scripts`.
194+
--
195+
196+
* Properties that start with `property`, which are used for
197+
xref:manual/configuration.adoc#property-substitution[property substitution],
198+
need to be rewritten from:
199+
+
200+
[source,properties]
201+
----
202+
property.<key> = <value>
203+
----
204+
+
205+
to
206+
+
207+
[source,properties]
208+
----
209+
Properties.Property[<n>].key = <key>
210+
Properties.Property[<n>].value = <value>
211+
----
212+
+
213+
where `<n>` is an increasing positive integer.
214+
215+
* Properties that start with `customLevel`, which are used to define custom levels, need to be rewritten from:
216+
+
217+
[source,properties]
218+
----
219+
customLevel.<name> = <intLevel>
220+
----
221+
+
222+
to
223+
+
224+
[source,properties]
225+
----
226+
CustomLevels.CustomLevel[<n>].name = <name>
227+
CustomLevels.CustomLevel[<n>].intLevel = <intLevel>
228+
----
229+
+
230+
where `<n>` is an increasing positive integer.
231+
232+
* You need to replace the `rootLogger` prefix with `Loggers.Root`.
233+
234+
* The shorthand notation:
235+
+
236+
[source,properties]
237+
----
238+
rootLogger = INFO, APPENDER1, APPENDER2
239+
----
240+
+
241+
must be rewritten into:
242+
+
243+
[source,properties]
244+
----
245+
Loggers.Root.level = INFO
246+
Loggers.Root.AppenderRef[1] = APPENDER1
247+
Loggers.Root.AppenderRef[2] = APPENDER2
248+
----
249+
250+
* All the prefixes of the form:
251+
+
252+
[source]
253+
----
254+
logger.<name>.appenderRef.<id>
255+
----
256+
where `<name>` and `<id>` are arbitrary, must be rewritten to
257+
+
258+
[source]
259+
----
260+
Loggers.Logger[<n>].AppenderRef[<m>]
261+
----
262+
where `<n>` and `<m>` are increasing positive integers.

0 commit comments

Comments
 (0)