Skip to content

Commit ab0fdbc

Browse files
ppkarwaszvy
ppkarwasz
and
vy
authored
Document GraalVM usage with Log4j (#3054)
We document the usage of GraalVM together with all official Log4j API implementations. Part of #2831. Co-authored-by: Volkan Yazıcı <[email protected]>
1 parent 1e154d4 commit ab0fdbc

File tree

5 files changed

+225
-15
lines changed

5 files changed

+225
-15
lines changed

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

+1
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@
7070
* xref:migrate-from-log4j1.adoc[]
7171
* xref:migrate-from-logback.adoc[]
7272
* xref:migrate-from-slf4j.adoc[]
73+
* xref:graalvm.adoc[]
7374
* xref:hibernate.adoc[]
7475
* xref:jakarta.adoc[]
7576
* xref:soa.adoc[]

‎src/site/antora/modules/ROOT/pages/graalvm.adoc

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
////
2+
Licensed to the Apache Software Foundation (ASF) under one or more
3+
contributor license agreements. See the NOTICE file distributed with
4+
this work for additional information regarding copyright ownership.
5+
The ASF licenses this file to You under the Apache License, Version 2.0
6+
(the "License"); you may not use this file except in compliance with
7+
the License. You may obtain a copy of the License at
8+
9+
http://www.apache.org/licenses/LICENSE-2.0
10+
11+
Unless required by applicable law or agreed to in writing, software
12+
distributed under the License is distributed on an "AS IS" BASIS,
13+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
See the License for the specific language governing permissions and
15+
limitations under the License.
16+
////
17+
18+
= Building GraalVM native images
19+
20+
Since version
21+
xref:release-notes.adoc#release-notes-2-25-0[`2.25.0`]
22+
both
23+
xref:manual/api.adoc[Log4j API]
24+
and
25+
xref:manual/implementation.adoc[its reference implementation]
26+
provide out-of-the-box support for creating native executables using
27+
https://www.graalvm.org/[GraalVM].
28+
29+
This document complements the
30+
xref:manual/installation.adoc[Installation Guide]
31+
and provides additional details on the steps necessary to create native images that use the Log4j API.
32+
The information is split depending on which Log4j API implementation you are using.
33+
34+
.Struggling with the logging API, implementation, and bridge concepts? Click for an introduction.
35+
[%collapsible]
36+
====
37+
include::partial$concepts.adoc[tag=!software-type]
38+
====
39+
40+
[TIP]
41+
====
42+
Are you looking for an example of GraalVM application that uses the Log4j API?
43+
Check out
44+
the https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-graalvm[`log4j-samples-graalvm`]
45+
project.
46+
====
47+
48+
[#impl-simple]
49+
== Using Simple Logger
50+
51+
If you use
52+
xref:manual/simple-logger.adoc[Simple Logger] shipped with xref:manual/api.adoc[Log4j API]
53+
in your application, no additional steps are required to compile a GraalVM native image.
54+
55+
[#impl-core]
56+
== Using Log4j Core
57+
58+
Since version
59+
xref:release-notes.adoc#release-notes-2-25-0[`2.25.0`],
60+
xref:manual/implementation.adoc[Log4j Core]
61+
and
62+
xref:components.adoc[all its official extensions]
63+
are bundled with the necessary
64+
https://www.graalvm.org/latest/reference-manual/native-image/metadata/[GraalVM reachability metadata]
65+
to help GraalVM with the creation of native images.
66+
Additional steps are only required:
67+
68+
* If you use a configuration file, which is not in a
69+
xref:manual/configuration.adoc#automatic-configuration[standard location], you need to create a
70+
https://www.graalvm.org/jdk17/reference-manual/native-image/metadata/#resource-metadata-in-json[`META-INF/native-image/<groupId>/<artifactId>/resource-config.json`] file in your classpath with content:
71+
+
72+
[source,json]
73+
----
74+
{
75+
"resources": {
76+
"includes": [
77+
{
78+
"pattern": "path/to/your/configuration/file"
79+
}
80+
]
81+
}
82+
}
83+
----
84+
85+
* If you use **third-party**
86+
xref:manual/plugins.adoc[Log4j Plugin JARs]
87+
you need to make sure they contain a
88+
https://www.graalvm.org/jdk17/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json[`reflect-config.json`] metadata file.
89+
If that is not the case, please point the maintainer to the
90+
xref:manual/plugins.adoc#plugin-registry[Log4j Plugin registration documentation].
91+
92+
[#impl-jul]
93+
== Using JUL
94+
95+
Since version `2.24.0` the
96+
xref:manual/installation.adoc#impl-jul[Log4j API to JUL bridge]
97+
is tested for compatibility with GraalVM.
98+
99+
Although `java.util.logging` is embedded into the JRE, currently not all
100+
https://docs.oracle.com/en/java/javase/17/docs/api/java.logging/java/util/logging/Formatter.html[`j.u.l.Formatter`]
101+
and
102+
https://docs.oracle.com/en/java/javase/17/docs/api/java.logging/java/util/logging/Handler.html[`j.u.l.Handler`]
103+
implementations have the required GraalVM metadata.
104+
See the official
105+
https://www.graalvm.org/latest/reference-manual/native-image/guides/add-logging-to-native-executable/[Add Logging to a Native Executable]
106+
guide for more information on how to add additional elements to your configuration.
107+
108+
[TIP]
109+
====
110+
See
111+
https://github.com/apache/logging-log4j-samples/blob/main/log4j-samples-graalvm/src/reachability-metadata/jul/reflect-config.json[`reflect-config.json` in our `log4j-samples-graalvm` example project]
112+
for an example on how to enable `j.u.l.FileHandler`.
113+
====
114+
115+
[#impl-logback]
116+
== Using Logback
117+
118+
Since version `2.24.0` the
119+
xref:manual/installation.adoc#impl-logback[Log4j API to SLF4J bridge]
120+
is tested for compatibility with GraalVM.
121+
122+
While Logback itself does not provide any GraalVM metadata, the data is available in the third-party
123+
https://github.com/oracle/graalvm-reachability-metadata/[GraalVM reachability metadata repository].
124+
125+
See the GraalVM Reachability Metadata Support documentation appropriate for your build tool for more information:
126+
127+
* https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html#metadata-support[Gradle Plugin documentation]
128+
* https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#metadata-support[Maven Plugin documentation]

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

+51-9
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,30 @@ h| Gradle
169169
|===
170170
====
171171
172+
[#impl-simple]
173+
=== Installing Simple Logger
174+
175+
The
176+
xref:manual/simple-logger.adoc[Simple Logger]
177+
implementation is embedded in the Log4j API and does not need any external dependency.
178+
It is intended as a convenience for environments where either a fully-fledged logging implementation is missing, or cannot be included for other reasons.
179+
The Log4j API will log an error to the
180+
xref:manual/status-logger.adoc[Status Logger] to avoid its unintentional usages:
181+
182+
----
183+
2024-10-03T11:53:34.281462230Z main ERROR Log4j API could not find a logging provider.
184+
----
185+
186+
To remove the warning and confirm that you want to use Simple Logger, add a
187+
xref:manual/systemproperties.adoc#property-sources[`log4j2.component.properties` file]
188+
at the root of your class path with content:
189+
190+
[source,properties]
191+
----
192+
# Activate Simple Logger implementation
193+
log4j.provider = org.apache.logging.log4j.simple.internal.SimpleProvider
194+
----
195+
172196
[#impl-core]
173197
=== Installing Log4j Core
174198
@@ -365,6 +389,13 @@ The `spring-boot-starter-log4j2` artifact will automatically install Log4j Core,
365389
You don't need to add any other dependency or configure JUL anymore.
366390
See https://docs.spring.io/spring-boot/reference/features/logging.html[Spring Boot Logging documentation] for further information.
367391
392+
[#impl-core-graalvm]
393+
==== Installing Log4j Core for GraalVM applications
394+
395+
See
396+
xref:graalvm.adoc#impl-core[Using Log4j Core]
397+
in our GraalVM guide for more details on how to create GraalVM native applications that use Log4j Core.
398+
368399
[#impl-core-config]
369400
==== Configuring Log4j Core
370401
@@ -385,19 +416,16 @@ log4j2.xml::
385416
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
386417
xsi:schemaLocation="https://logging.apache.org/xml/ns
387418
https://logging.apache.org/xml/ns/log4j-config-2.xsd">
388-
389-
<appenders>
419+
<Appenders>
390420
<Console name="CONSOLE">
391421
<PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/><!--1-->
392422
</Console>
393-
</appenders>
394-
395-
<loggers>
396-
<root level="INFO">
423+
</Appenders>
424+
<Loggers>
425+
<Root level="INFO">
397426
<AppenderRef ref="CONSOLE"/>
398-
</root>
399-
</loggers>
400-
427+
</Root>
428+
</Loggers>
401429
</Configuration>
402430
----
403431
@@ -520,6 +548,13 @@ See also:
520548
* https://docs.oracle.com/javase/{java-target-version}/docs/api/java/util/logging/LogManager.html[`java.util.logging.LogManager`], to learn more about JUL configuration,
521549
* xref:log4j-to-jul.adoc[] to learn more about the `log4j-to-jul` artifact.
522550
551+
[#impl-jul-graalvm]
552+
==== Installing JUL for GraalVM applications
553+
554+
See
555+
xref:graalvm.adoc#impl-jul[Using JUL]
556+
in our GraalVM guide for more details on how to create GraalVM native applications that use JUL.
557+
523558
[#impl-logback]
524559
=== Installing Logback
525560
@@ -563,3 +598,10 @@ runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j' // Log4j-to-SLF4J bridge
563598
====
564599
565600
To configure Logback, see {logback-url}/manual/configuration.html[Logback's configuration documentation].
601+
602+
[#impl-jul-logback]
603+
==== Installing Logback for GraalVM applications
604+
605+
See
606+
xref:graalvm.adoc#impl-logback[Using Logback]
607+
in our GraalVM guide for more details on how to create GraalVM native applications that use Logback.

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

+39-6
Original file line numberDiff line numberDiff line change
@@ -197,9 +197,25 @@ This annotation validates that a value corresponds to a valid port number betwee
197197
[#plugin-registry]
198198
== Registering plugins
199199
200-
Registering plugins are done by placing a *Log4j plugin descriptor* (i.e., `Log4j2Plugins.dat`) into the classpath.
201-
This file is generated using the link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html[`PluginProcessor`] annotation processor at compile-time.
202-
You need to configure your build tool as follows to employ `PluginProcessor` by the Java compiler:
200+
To properly work, each Log4j plugin needs:
201+
202+
* To be registered in the *Log4j Plugin Descriptor* (i.e., `Log4j2Plugins.dat`).
203+
This file is generated using the
204+
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/PluginProcessor.html[`PluginProcessor`]
205+
annotation processor at compile-time.
206+
* (Optionally) To be registered in the
207+
https://www.graalvm.org/latest/reference-manual/native-image/metadata/#specifying-metadata-with-json[GraalVM reachability metadata descriptor], which will allow the plugin to be used in GraalVM native applications.
208+
The
209+
link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/GraalVmProcessor.html[`GraalVmProcessor`]
210+
annotation processor creates such a file at compile-time.
211+
212+
[WARNING]
213+
====
214+
The `GraalVmProcessor` needs to know the `groupId` and `artifactId` coordinates of your project.
215+
These must be supplied to the processor using the `log4j.graalvm.groupId` and `log4j.graalvm.artifactId` annotation processor options.
216+
====
217+
218+
You need to configure your build tool as follows to use both plugin processors:
203219
204220
[tabs]
205221
====
@@ -221,17 +237,26 @@ Maven::
221237
<configuration>
222238
<proc>only</proc>
223239
<annotationProcessorPaths>
224-
<!-- Include `log4j-core` providing `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that generates `Log4j2Plugins.dat` -->
240+
<!-- Include `log4j-core` providing
241+
1. `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that generates `Log4j2Plugins.dat`
242+
2. `org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor` that generates the GraalVM reachability metadata file -->
225243
<path>
226244
<groupId>org.apache.logging.log4j</groupId>
227245
<artifactId>log4j-core</artifactId>
228246
<version>{log4j-core-version}</version>
229247
</path>
230248
</annotationProcessorPaths>
231249
<annotationProcessors>
232-
<!-- Process sources using `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` to generate `Log4j2Plugins.dat` -->
250+
<!-- Process sources using `PluginProcessor` to generate `Log4j2Plugins.dat` -->
233251
<processor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</processor>
252+
<!-- Process sources using `GraalVmProcessor` to generate a GraalVM reachability metadata file -->
253+
<processor>org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor</processor>
234254
</annotationProcessors>
255+
<compilerArgs>
256+
<!-- Provide the project coordinates to `GraalVmProcessor`: -->
257+
<arg>-Alog4j.graalvm.groupId=${project.groupId}</arg>
258+
<arg>-Alog4j.graalvm.artifactId=${project.artifactId}</arg>
259+
</compilerArgs>
235260
</configuration>
236261
</execution>
237262
</executions>
@@ -242,8 +267,16 @@ Gradle::
242267
+
243268
[source,groovy,subs="+attributes"]
244269
----
270+
compileJava {
271+
// Provide the project coordinates to the `GraalVmProcessor`:
272+
options.compilerArgs << '-Alog4j.graalvm.groupId=org.example'
273+
options.compilerArgs << '-Alog4j.graalvm.artifactId=example'
274+
}
275+
245276
dependencies {
246-
// Process sources using `log4j-core` providing `org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that generates `Log4j2Plugins.dat` -->
277+
// Process sources using:
278+
// * `PluginProcessor` to generate `Log4j2Plugins.dat`
279+
// * `GraalVmProcessor` to generate a GraalVM reachability metadata file
247280
annotationProcessor('org.apache.logging.log4j:log4j-core:{log4j-core-version}')
248281
}
249282
----

‎src/site/antora/modules/ROOT/pages/release-notes.adoc

+6
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@ Licensed to the Apache Software Foundation (ASF) under one or more
1818
1919
This file is a stub.
2020
Its content will be auto-generated during build.
21+
22+
// The following anchors are used in the documentation.
23+
// We add them here to hide IDE errors.
24+
25+
[#release-notes-2-25-0]
26+
== `2.25.0`

0 commit comments

Comments
 (0)