diff --git a/src/site/antora/modules/ROOT/nav.adoc b/src/site/antora/modules/ROOT/nav.adoc index ed71cea132b..3fe3771e513 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 00000000000..d7780e64fe5 --- /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///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 91327a9a3b7..f3b8c69578c 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"> - - + - - - - + + + - - - + + ---- @@ -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 1c33e97f32c..233b6fd3226 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:: only - + org.apache.logging.log4j log4j-core @@ -229,9 +247,16 @@ Maven:: - + org.apache.logging.log4j.core.config.plugins.processor.PluginProcessor + + org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor + + + -Alog4j.graalvm.groupId=${project.groupId} + -Alog4j.graalvm.artifactId=${project.artifactId} + @@ -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 8f72eb57528..a1c56803808 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`