This is an automated email from the ASF dual-hosted git repository.
pkarwasz pushed a commit to branch 2.x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/2.x by this push:
new ab0fdbc517 Document GraalVM usage with Log4j (#3054)
ab0fdbc517 is described below
commit ab0fdbc51742646144f6ad29715f9bd1d9afa985
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Wed Oct 9 21:39:56 2024 +0200
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]>
---
src/site/antora/modules/ROOT/nav.adoc | 1 +
src/site/antora/modules/ROOT/pages/graalvm.adoc | 128 +++++++++++++++++++++
.../modules/ROOT/pages/manual/installation.adoc | 60 ++++++++--
.../antora/modules/ROOT/pages/manual/plugins.adoc | 45 +++++++-
.../antora/modules/ROOT/pages/release-notes.adoc | 6 +
5 files changed, 225 insertions(+), 15 deletions(-)
diff --git a/src/site/antora/modules/ROOT/nav.adoc
b/src/site/antora/modules/ROOT/nav.adoc
index ed71cea132..3fe3771e51 100644
--- a/src/site/antora/modules/ROOT/nav.adoc
+++ b/src/site/antora/modules/ROOT/nav.adoc
@@ -70,6 +70,7 @@
* xref:migrate-from-log4j1.adoc[]
* xref:migrate-from-logback.adoc[]
* xref:migrate-from-slf4j.adoc[]
+* xref:graalvm.adoc[]
* xref:hibernate.adoc[]
* xref:jakarta.adoc[]
* xref:soa.adoc[]
diff --git a/src/site/antora/modules/ROOT/pages/graalvm.adoc
b/src/site/antora/modules/ROOT/pages/graalvm.adoc
new file mode 100644
index 0000000000..d7780e64fe
--- /dev/null
+++ b/src/site/antora/modules/ROOT/pages/graalvm.adoc
@@ -0,0 +1,128 @@
+////
+ 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.
+////
+
+= Building GraalVM native images
+
+Since version
+xref:release-notes.adoc#release-notes-2-25-0[`2.25.0`]
+both
+xref:manual/api.adoc[Log4j API]
+and
+xref:manual/implementation.adoc[its reference implementation]
+provide out-of-the-box support for creating native executables using
+https://www.graalvm.org/[GraalVM].
+
+This document complements the
+xref:manual/installation.adoc[Installation Guide]
+and provides additional details on the steps necessary to create native images
that use the Log4j API.
+The information is split depending on which Log4j API implementation you are
using.
+
+.Struggling with the logging API, implementation, and bridge concepts? Click
for an introduction.
+[%collapsible]
+====
+include::partial$concepts.adoc[tag=!software-type]
+====
+
+[TIP]
+====
+Are you looking for an example of GraalVM application that uses the Log4j API?
+Check out
+the
https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-graalvm[`log4j-samples-graalvm`]
+project.
+====
+
+[#impl-simple]
+== Using Simple Logger
+
+If you use
+xref:manual/simple-logger.adoc[Simple Logger] shipped with
xref:manual/api.adoc[Log4j API]
+in your application, no additional steps are required to compile a GraalVM
native image.
+
+[#impl-core]
+== Using Log4j Core
+
+Since version
+xref:release-notes.adoc#release-notes-2-25-0[`2.25.0`],
+xref:manual/implementation.adoc[Log4j Core]
+and
+xref:components.adoc[all its official extensions]
+are bundled with the necessary
+https://www.graalvm.org/latest/reference-manual/native-image/metadata/[GraalVM
reachability metadata]
+to help GraalVM with the creation of native images.
+Additional steps are only required:
+
+* If you use a configuration file, which is not in a
+xref:manual/configuration.adoc#automatic-configuration[standard location], you
need to create a
+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:
++
+[source,json]
+----
+{
+ "resources": {
+ "includes": [
+ {
+ "pattern": "path/to/your/configuration/file"
+ }
+ ]
+ }
+}
+----
+
+* If you use **third-party**
+xref:manual/plugins.adoc[Log4j Plugin JARs]
+you need to make sure they contain a
+https://www.graalvm.org/jdk17/reference-manual/native-image/metadata/#specifying-reflection-metadata-in-json[`reflect-config.json`]
metadata file.
+If that is not the case, please point the maintainer to the
+xref:manual/plugins.adoc#plugin-registry[Log4j Plugin registration
documentation].
+
+[#impl-jul]
+== Using JUL
+
+Since version `2.24.0` the
+xref:manual/installation.adoc#impl-jul[Log4j API to JUL bridge]
+is tested for compatibility with GraalVM.
+
+Although `java.util.logging` is embedded into the JRE, currently not all
+https://docs.oracle.com/en/java/javase/17/docs/api/java.logging/java/util/logging/Formatter.html[`j.u.l.Formatter`]
+and
+https://docs.oracle.com/en/java/javase/17/docs/api/java.logging/java/util/logging/Handler.html[`j.u.l.Handler`]
+implementations have the required GraalVM metadata.
+See the official
+https://www.graalvm.org/latest/reference-manual/native-image/guides/add-logging-to-native-executable/[Add
Logging to a Native Executable]
+guide for more information on how to add additional elements to your
configuration.
+
+[TIP]
+====
+See
+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]
+for an example on how to enable `j.u.l.FileHandler`.
+====
+
+[#impl-logback]
+== Using Logback
+
+Since version `2.24.0` the
+xref:manual/installation.adoc#impl-logback[Log4j API to SLF4J bridge]
+is tested for compatibility with GraalVM.
+
+While Logback itself does not provide any GraalVM metadata, the data is
available in the third-party
+https://github.com/oracle/graalvm-reachability-metadata/[GraalVM reachability
metadata repository].
+
+See the GraalVM Reachability Metadata Support documentation appropriate for
your build tool for more information:
+
+*
https://graalvm.github.io/native-build-tools/latest/gradle-plugin.html#metadata-support[Gradle
Plugin documentation]
+*
https://graalvm.github.io/native-build-tools/latest/maven-plugin.html#metadata-support[Maven
Plugin documentation]
\ No newline at end of file
diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
index 91327a9a3b..f3b8c69578 100644
--- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc
@@ -169,6 +169,30 @@ h| Gradle
|===
====
+[#impl-simple]
+=== Installing Simple Logger
+
+The
+xref:manual/simple-logger.adoc[Simple Logger]
+implementation is embedded in the Log4j API and does not need any external
dependency.
+It is intended as a convenience for environments where either a fully-fledged
logging implementation is missing, or cannot be included for other reasons.
+The Log4j API will log an error to the
+xref:manual/status-logger.adoc[Status Logger] to avoid its unintentional
usages:
+
+----
+2024-10-03T11:53:34.281462230Z main ERROR Log4j API could not find a logging
provider.
+----
+
+To remove the warning and confirm that you want to use Simple Logger, add a
+xref:manual/systemproperties.adoc#property-sources[`log4j2.component.properties`
file]
+at the root of your class path with content:
+
+[source,properties]
+----
+# Activate Simple Logger implementation
+log4j.provider = org.apache.logging.log4j.simple.internal.SimpleProvider
+----
+
[#impl-core]
=== Installing Log4j Core
@@ -365,6 +389,13 @@ The `spring-boot-starter-log4j2` artifact will
automatically install Log4j Core,
You don't need to add any other dependency or configure JUL anymore.
See https://docs.spring.io/spring-boot/reference/features/logging.html[Spring
Boot Logging documentation] for further information.
+[#impl-core-graalvm]
+==== Installing Log4j Core for GraalVM applications
+
+See
+xref:graalvm.adoc#impl-core[Using Log4j Core]
+in our GraalVM guide for more details on how to create GraalVM native
applications that use Log4j Core.
+
[#impl-core-config]
==== Configuring Log4j Core
@@ -385,19 +416,16 @@ log4j2.xml::
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="https://logging.apache.org/xml/ns
https://logging.apache.org/xml/ns/log4j-config-2.xsd";>
-
- <appenders>
+ <Appenders>
<Console name="CONSOLE">
<PatternLayout pattern="%d [%t] %5p %c{1.} - %m%n"/><!--1-->
</Console>
- </appenders>
-
- <loggers>
- <root level="INFO">
+ </Appenders>
+ <Loggers>
+ <Root level="INFO">
<AppenderRef ref="CONSOLE"/>
- </root>
- </loggers>
-
+ </Root>
+ </Loggers>
</Configuration>
----
@@ -520,6 +548,13 @@ See also:
*
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,
* xref:log4j-to-jul.adoc[] to learn more about the `log4j-to-jul` artifact.
+[#impl-jul-graalvm]
+==== Installing JUL for GraalVM applications
+
+See
+xref:graalvm.adoc#impl-jul[Using JUL]
+in our GraalVM guide for more details on how to create GraalVM native
applications that use JUL.
+
[#impl-logback]
=== Installing Logback
@@ -563,3 +598,10 @@ runtimeOnly 'org.apache.logging.log4j:log4j-to-slf4j' //
Log4j-to-SLF4J bridge
====
To configure Logback, see {logback-url}/manual/configuration.html[Logback's
configuration documentation].
+
+[#impl-jul-logback]
+==== Installing Logback for GraalVM applications
+
+See
+xref:graalvm.adoc#impl-logback[Using Logback]
+in our GraalVM guide for more details on how to create GraalVM native
applications that use Logback.
diff --git a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
index 1c33e97f32..233b6fd322 100644
--- a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
+++ b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc
@@ -197,9 +197,25 @@ This annotation validates that a value corresponds to a
valid port number betwee
[#plugin-registry]
== Registering plugins
-Registering plugins are done by placing a *Log4j plugin descriptor* (i.e.,
`Log4j2Plugins.dat`) into the classpath.
-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.
-You need to configure your build tool as follows to employ `PluginProcessor`
by the Java compiler:
+To properly work, each Log4j plugin needs:
+
+* To be registered in the *Log4j Plugin Descriptor* (i.e.,
`Log4j2Plugins.dat`).
+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.
+* (Optionally) To be registered in the
+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.
+The
+link:../javadoc/log4j-core/org/apache/logging/log4j/core/config/plugins/processor/GraalVmProcessor.html[`GraalVmProcessor`]
+annotation processor creates such a file at compile-time.
+
+[WARNING]
+====
+The `GraalVmProcessor` needs to know the `groupId` and `artifactId`
coordinates of your project.
+These must be supplied to the processor using the `log4j.graalvm.groupId` and
`log4j.graalvm.artifactId` annotation processor options.
+====
+
+You need to configure your build tool as follows to use both plugin processors:
[tabs]
====
@@ -221,7 +237,9 @@ Maven::
<configuration>
<proc>only</proc>
<annotationProcessorPaths>
- <!-- Include `log4j-core` providing
`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that
generates `Log4j2Plugins.dat` -->
+ <!-- Include `log4j-core` providing
+ 1.
`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that
generates `Log4j2Plugins.dat`
+ 2.
`org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor` that
generates the GraalVM reachability metadata file -->
<path>
<groupId>org.apache.logging.log4j</groupId>
<artifactId>log4j-core</artifactId>
@@ -229,9 +247,16 @@ Maven::
</path>
</annotationProcessorPaths>
<annotationProcessors>
- <!-- Process sources using
`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` to
generate `Log4j2Plugins.dat` -->
+ <!-- Process sources using `PluginProcessor` to generate
`Log4j2Plugins.dat` -->
<processor>org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor</processor>
+ <!-- Process sources using `GraalVmProcessor` to generate a GraalVM
reachability metadata file -->
+
<processor>org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor</processor>
</annotationProcessors>
+ <compilerArgs>
+ <!-- Provide the project coordinates to `GraalVmProcessor`: -->
+ <arg>-Alog4j.graalvm.groupId=${project.groupId}</arg>
+ <arg>-Alog4j.graalvm.artifactId=${project.artifactId}</arg>
+ </compilerArgs>
</configuration>
</execution>
</executions>
@@ -242,8 +267,16 @@ Gradle::
+
[source,groovy,subs="+attributes"]
----
+compileJava {
+ // Provide the project coordinates to the `GraalVmProcessor`:
+ options.compilerArgs << '-Alog4j.graalvm.groupId=org.example'
+ options.compilerArgs << '-Alog4j.graalvm.artifactId=example'
+}
+
dependencies {
- // Process sources using `log4j-core` providing
`org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor` that
generates `Log4j2Plugins.dat` -->
+ // Process sources using:
+ // * `PluginProcessor` to generate `Log4j2Plugins.dat`
+ // * `GraalVmProcessor` to generate a GraalVM reachability metadata file
annotationProcessor('org.apache.logging.log4j:log4j-core:{log4j-core-version}')
}
----
diff --git a/src/site/antora/modules/ROOT/pages/release-notes.adoc
b/src/site/antora/modules/ROOT/pages/release-notes.adoc
index 8f72eb5752..a1c5680380 100644
--- a/src/site/antora/modules/ROOT/pages/release-notes.adoc
+++ b/src/site/antora/modules/ROOT/pages/release-notes.adoc
@@ -18,3 +18,9 @@ Licensed to the Apache Software Foundation (ASF) under one or
more
This file is a stub.
Its content will be auto-generated during build.
+
+// The following anchors are used in the documentation.
+// We add them here to hide IDE errors.
+
+[#release-notes-2-25-0]
+== `2.25.0`
