Skip to content

Commit c9bc2d4

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 aad01a7 commit c9bc2d4

File tree

6 files changed

+253
-6
lines changed

6 files changed

+253
-6
lines changed

‎antora-playbook.yaml

+3-1
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,9 @@ content:
3030

3131
runtime:
3232
log:
33-
failure_level: error
33+
# The JavaDoc of `org.apache.logging.log4j.core.net.Facility` does not compile
34+
# Switch to `error` after `log4j-docgen` 0.10.0 is released.
35+
failure_level: fatal
3436

3537
asciidoc:
3638
attributes:

‎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
@@ -42,14 +42,14 @@
4242
* xref:manual/performance.adoc[]
4343
** xref:manual/async.adoc[]
4444
** xref:manual/garbagefree.adoc[]
45+
* xref:manual/migration.adoc[]
4546
4647
.References
4748
* xref:plugin-reference.adoc[Plugin reference]
4849
* xref:javadoc.adoc[Java API reference]
4950
5051
.Resources
5152
* xref:faq.adoc[F.A.Q.]
52-
* xref:manual/migration.adoc[]
5353
* xref:migrate-from-logback.adoc[]
5454
* xref:migrate-from-slf4j.adoc[]
5555
* xref:hibernate.adoc[]

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

+2-2
Original file line numberDiff line numberDiff line change
@@ -792,11 +792,11 @@ will be used as is in the `INSERT` query without any escaping.
792792
Otherwise, the layout or pattern specified will be converted into the
793793
configured type and stored in that column.
794794
795-
|immediateFail |boolean |false |When set to true, log events will not
795+
|immediateFail |boolean | When set to true, log events will not
796796
wait to try to reconnect and will fail immediately if the JDBC resources
797797
are not available. New in 2.11.2.
798798
799-
|reconnectIntervalMillis |long |5000 |If set to a value greater than 0,
799+
|reconnectIntervalMillis |long |If set to a value greater than 0,
800800
after an error, the JDBCDatabaseManager will attempt to reconnect to the database
801801
after waiting the specified number of milliseconds. If the reconnect
802802
fails then an exception will be thrown (which can be caught by the

‎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)