Document GraalVM usage with Log4j

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[]

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]

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.

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,17 +237,26 @@ 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>
             <version>{log4j-core-version}</version>
           </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}')
 }
 ----

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`