From c2a89f8368841d9157f7aef8f5a1c4356bdcf931 Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Thu, 3 Oct 2024 14:35:14 +0200 Subject: [PATCH 01/10] Document GraalVM usage with Log4j We document the usage of GraalVM together with all official Log4j API implementations. Part of #2831. --- src/site/antora/modules/ROOT/nav.adoc | 1 + .../antora/modules/ROOT/pages/graalvm.adoc | 111 ++++++++++++++++++ .../ROOT/pages/manual/installation.adoc | 39 ++++-- .../modules/ROOT/pages/manual/plugins.adoc | 41 ++++++- .../modules/ROOT/pages/release-notes.adoc | 6 + 5 files changed, 184 insertions(+), 14 deletions(-) create mode 100644 src/site/antora/modules/ROOT/pages/graalvm.adoc 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..9ebe281c06f --- /dev/null +++ b/src/site/antora/modules/ROOT/pages/graalvm.adoc @@ -0,0 +1,111 @@ +//// + 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]. + +Depending on the logging implementation you are using, additional steps might be required to compile a Log4j API application with GraalVM. + +.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 our +https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-graalvm[`log4j-samples-graalvm`] +sample. +==== + +[#impl-simple] +== Using Simple Logger + +If you use +xref:manual/simple-logger.adoc[Simple Logger] +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 + +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 +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 + +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..0534dd3c5e4 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. + +Its usage is, however, opt-in and Log4j API will log an error to the +xref:manual/status-logger.adoc[Status Logger]: + +---- +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 @@ -385,19 +409,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"> - - + - - - - + + + - - - + + ---- diff --git a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc index 1c33e97f32c..7f24b7b0c12 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] ==== @@ -229,9 +245,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 +265,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` From ce2b326842d6a2198b88fb0509f5b9addbc4d37c Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Fri, 4 Oct 2024 15:00:06 +0200 Subject: [PATCH 02/10] Add `resource-config.json` to JTL --- .../log4j-layout-template-json/resource-config.json | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json diff --git a/log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json b/log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json new file mode 100644 index 00000000000..c8afe14794a --- /dev/null +++ b/log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json @@ -0,0 +1,9 @@ +{ + "resources": { + "includes": [ + { + "pattern": "((Ecs|Gcp|Gelf|Json|StackTraceElement)Layout|LogstashJsonEventLayoutV1)\\.json" + } + ] + } +} From 34259920f2b866cecc165ca5edde40cab5b5a6ee Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Fri, 4 Oct 2024 15:01:15 +0200 Subject: [PATCH 03/10] Revert "Add `resource-config.json` to JTL" This reverts commit ce2b326842d6a2198b88fb0509f5b9addbc4d37c. --- .../log4j-layout-template-json/resource-config.json | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json diff --git a/log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json b/log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json deleted file mode 100644 index c8afe14794a..00000000000 --- a/log4j-layout-template-json/src/main/resources/META-INF/native-image/org.apache.logging.log4j/log4j-layout-template-json/resource-config.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "resources": { - "includes": [ - { - "pattern": "((Ecs|Gcp|Gelf|Json|StackTraceElement)Layout|LogstashJsonEventLayoutV1)\\.json" - } - ] - } -} From 0aa0b7090b1ceebf1446a90badc16afffd12e5b5 Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Fri, 4 Oct 2024 15:25:34 +0200 Subject: [PATCH 04/10] Try fixing Dependabot --- .github/dependabot.yaml | 58 ++++++++++++++++++++++++++++++++++------- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml index 987ab509713..ee3d0963323 100644 --- a/.github/dependabot.yaml +++ b/.github/dependabot.yaml @@ -44,7 +44,45 @@ registries: updates: - package-ecosystem: maven - directory: "/" + directories: + - "/" + - "/log4j-1.2-api" + - "/log4j-api-test" + - "/log4j-api" + - "/log4j-appserver" + - "/log4j-cassandra" + - "/log4j-core-fuzz-test" + - "/log4j-core-its" + - "/log4j-core-test" + - "/log4j-core" + - "/log4j-couchdb" + - "/log4j-docker" + - "/log4j-fuzz-test" + - "/log4j-iostreams" + - "/log4j-jakarta-smtp" + - "/log4j-jakarta-web" + - "/log4j-jcl" + - "/log4j-jdbc-dbcp2" + - "/log4j-jpa" + - "/log4j-jpl" + - "/log4j-jul" + - "/log4j-layout-template-json-fuzz-test" + - "/log4j-layout-template-json-test" + - "/log4j-layout-template-json" + - "/log4j-mongodb" + # `log4j-mongodb4` is in a separate run + - "/log4j-osgi-test" + - "/log4j-parent" + - "/log4j-perf-test" + # `log4j-slf4j-impl` is in a separate run + - "/log4j-slf4j2-impl-fuzz-test" + - "/log4j-slf4j2-impl" + - "/log4j-spring-boot" + - "/log4j-spring-cloud-config-client" + - "/log4j-taglib" + - "/log4j-to-jul" + - "/log4j-to-slf4j" + - "/log4j-web" open-pull-requests-limit: 10 schedule: interval: "daily" @@ -54,31 +92,31 @@ updates: ignore: # Jetty 10.x does not have an internal logging API - dependency-name: "org.eclipse.jetty:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[10,)" ] # EclipseLink 3.x is Jakarta EE 9 - dependency-name: "org.eclipse.persistence:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[3,)" ] # Spring 6.x is Jakarta EE 9 - dependency-name: "org.springframework:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[6,)" ] # Spring Boot 3.x is Jakarta EE 9 - dependency-name: "org.springframework.boot:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[3,)" ] # Spring Cloud 2022.x is Jakarta EE 9 - dependency-name: "org.springframework.cloud:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[2021,)" ] # Tomcat Juli 10.1.x requires Java 11 - dependency-name: "org.apache.tomcat:*" - update-types: [ "version-update:semver-major", "version-update:semver-minor" ] + versions: [ "[10.1,)" ] # Keep Logback version 1.2.x - dependency-name: "ch.qos.logback:*" - update-types: [ "version-update:semver-major", "version-update:semver-minor" ] + versions: [ "[1.3,)" ] # Mockito 5.x requires Java 11 - dependency-name: "org.mockito:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[5,)" ] # JUnit Pioneer 2.x requires Java 11 - dependency-name: "org.junit-pioneer:*" - update-types: [ "version-update:semver-major" ] + versions: [ "[2,)" ] # Apache Cassandra: keep version 3.x - dependency-name: "org.apache.cassandra:*" versions: [ "[4,)" ] From 0508ac62eb4cd9ed3c63d30bd9913f2af46f6a46 Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Fri, 4 Oct 2024 15:26:03 +0200 Subject: [PATCH 05/10] Revert "Try fixing Dependabot" This reverts commit 0aa0b7090b1ceebf1446a90badc16afffd12e5b5. --- .github/dependabot.yaml | 58 +++++++---------------------------------- 1 file changed, 10 insertions(+), 48 deletions(-) diff --git a/.github/dependabot.yaml b/.github/dependabot.yaml index ee3d0963323..987ab509713 100644 --- a/.github/dependabot.yaml +++ b/.github/dependabot.yaml @@ -44,45 +44,7 @@ registries: updates: - package-ecosystem: maven - directories: - - "/" - - "/log4j-1.2-api" - - "/log4j-api-test" - - "/log4j-api" - - "/log4j-appserver" - - "/log4j-cassandra" - - "/log4j-core-fuzz-test" - - "/log4j-core-its" - - "/log4j-core-test" - - "/log4j-core" - - "/log4j-couchdb" - - "/log4j-docker" - - "/log4j-fuzz-test" - - "/log4j-iostreams" - - "/log4j-jakarta-smtp" - - "/log4j-jakarta-web" - - "/log4j-jcl" - - "/log4j-jdbc-dbcp2" - - "/log4j-jpa" - - "/log4j-jpl" - - "/log4j-jul" - - "/log4j-layout-template-json-fuzz-test" - - "/log4j-layout-template-json-test" - - "/log4j-layout-template-json" - - "/log4j-mongodb" - # `log4j-mongodb4` is in a separate run - - "/log4j-osgi-test" - - "/log4j-parent" - - "/log4j-perf-test" - # `log4j-slf4j-impl` is in a separate run - - "/log4j-slf4j2-impl-fuzz-test" - - "/log4j-slf4j2-impl" - - "/log4j-spring-boot" - - "/log4j-spring-cloud-config-client" - - "/log4j-taglib" - - "/log4j-to-jul" - - "/log4j-to-slf4j" - - "/log4j-web" + directory: "/" open-pull-requests-limit: 10 schedule: interval: "daily" @@ -92,31 +54,31 @@ updates: ignore: # Jetty 10.x does not have an internal logging API - dependency-name: "org.eclipse.jetty:*" - versions: [ "[10,)" ] + update-types: [ "version-update:semver-major" ] # EclipseLink 3.x is Jakarta EE 9 - dependency-name: "org.eclipse.persistence:*" - versions: [ "[3,)" ] + update-types: [ "version-update:semver-major" ] # Spring 6.x is Jakarta EE 9 - dependency-name: "org.springframework:*" - versions: [ "[6,)" ] + update-types: [ "version-update:semver-major" ] # Spring Boot 3.x is Jakarta EE 9 - dependency-name: "org.springframework.boot:*" - versions: [ "[3,)" ] + update-types: [ "version-update:semver-major" ] # Spring Cloud 2022.x is Jakarta EE 9 - dependency-name: "org.springframework.cloud:*" - versions: [ "[2021,)" ] + update-types: [ "version-update:semver-major" ] # Tomcat Juli 10.1.x requires Java 11 - dependency-name: "org.apache.tomcat:*" - versions: [ "[10.1,)" ] + update-types: [ "version-update:semver-major", "version-update:semver-minor" ] # Keep Logback version 1.2.x - dependency-name: "ch.qos.logback:*" - versions: [ "[1.3,)" ] + update-types: [ "version-update:semver-major", "version-update:semver-minor" ] # Mockito 5.x requires Java 11 - dependency-name: "org.mockito:*" - versions: [ "[5,)" ] + update-types: [ "version-update:semver-major" ] # JUnit Pioneer 2.x requires Java 11 - dependency-name: "org.junit-pioneer:*" - versions: [ "[2,)" ] + update-types: [ "version-update:semver-major" ] # Apache Cassandra: keep version 3.x - dependency-name: "org.apache.cassandra:*" versions: [ "[4,)" ] From 53043f0367f4fedf8aa965d488fd7ff5944f317c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Volkan=20Yaz=C4=B1c=C4=B1?= Date: Tue, 8 Oct 2024 12:24:11 +0200 Subject: [PATCH 06/10] Fix comments in `plugins.adoc` --- src/site/antora/modules/ROOT/pages/manual/plugins.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc index 7f24b7b0c12..233b6fd3226 100644 --- a/src/site/antora/modules/ROOT/pages/manual/plugins.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/plugins.adoc @@ -237,7 +237,9 @@ Maven:: only - + org.apache.logging.log4j log4j-core @@ -251,7 +253,7 @@ Maven:: org.apache.logging.log4j.core.config.plugins.processor.GraalVmProcessor - + -Alog4j.graalvm.groupId=${project.groupId} -Alog4j.graalvm.artifactId=${project.artifactId} From a8cf315fe2341bd1fd6d10c8017ce23ebbf8b6da Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Tue, 8 Oct 2024 12:43:22 +0200 Subject: [PATCH 07/10] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Volkan Yazıcı --- src/site/antora/modules/ROOT/pages/graalvm.adoc | 12 ++++++------ .../modules/ROOT/pages/manual/installation.adoc | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/site/antora/modules/ROOT/pages/graalvm.adoc b/src/site/antora/modules/ROOT/pages/graalvm.adoc index 9ebe281c06f..0ab32c54cbd 100644 --- a/src/site/antora/modules/ROOT/pages/graalvm.adoc +++ b/src/site/antora/modules/ROOT/pages/graalvm.adoc @@ -37,23 +37,23 @@ include::partial$concepts.adoc[tag=!software-type] [TIP] ==== Are you looking for an example of GraalVM application that uses the Log4j API? -Check our -https://github.com/apache/logging-log4j-samples/tree/main/log4j-samples-graalvm[`log4j-samples-graalvm`] -sample. +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] +xref:manual/simple-logger.adoc[Simple Logger] shipped with xref:manual/api.html[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`] +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] diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index 0534dd3c5e4..e41ef3f9b37 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -175,9 +175,9 @@ h| Gradle 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. Its usage is, however, opt-in and Log4j API will log an error to the -xref:manual/status-logger.adoc[Status Logger]: +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. From 5031b1bd30b78271d3607b7456d22258376becdb Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Tue, 8 Oct 2024 14:26:41 +0200 Subject: [PATCH 08/10] Improve GraalVM guide and add links from Installation page --- .../antora/modules/ROOT/pages/graalvm.adoc | 19 ++++++++++++++++- .../ROOT/pages/manual/installation.adoc | 21 +++++++++++++++++++ 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/src/site/antora/modules/ROOT/pages/graalvm.adoc b/src/site/antora/modules/ROOT/pages/graalvm.adoc index 0ab32c54cbd..1045ec6b4d7 100644 --- a/src/site/antora/modules/ROOT/pages/graalvm.adoc +++ b/src/site/antora/modules/ROOT/pages/graalvm.adoc @@ -26,7 +26,10 @@ xref:manual/implementation.adoc[its reference implementation] provide out-of-the-box support for creating native executables using https://www.graalvm.org/[GraalVM]. -Depending on the logging implementation you are using, additional steps might be required to compile a Log4j API application with 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] @@ -89,19 +92,33 @@ 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]. diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index e41ef3f9b37..d8bd5a3f716 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -389,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 @@ -541,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 @@ -584,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. From 7f71473a2e95cb6c9c2ccca156414026736bcdde Mon Sep 17 00:00:00 2001 From: "Piotr P. Karwasz" Date: Tue, 8 Oct 2024 14:34:43 +0200 Subject: [PATCH 09/10] Improve Simple Logger installation guide --- src/site/antora/modules/ROOT/pages/manual/installation.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/antora/modules/ROOT/pages/manual/installation.adoc b/src/site/antora/modules/ROOT/pages/manual/installation.adoc index d8bd5a3f716..f3b8c69578c 100644 --- a/src/site/antora/modules/ROOT/pages/manual/installation.adoc +++ b/src/site/antora/modules/ROOT/pages/manual/installation.adoc @@ -176,7 +176,7 @@ 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. -Its usage is, however, opt-in and Log4j API will log an error to the +The Log4j API will log an error to the xref:manual/status-logger.adoc[Status Logger] to avoid its unintentional usages: ---- From 792cf877509cb31c3c5ababaf035fcf2cdbbce14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Volkan=20Yaz=C4=B1c=C4=B1?= Date: Wed, 9 Oct 2024 13:38:40 +0200 Subject: [PATCH 10/10] Fix AsciiDoc typo --- src/site/antora/modules/ROOT/pages/graalvm.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/site/antora/modules/ROOT/pages/graalvm.adoc b/src/site/antora/modules/ROOT/pages/graalvm.adoc index 1045ec6b4d7..d7780e64fe5 100644 --- a/src/site/antora/modules/ROOT/pages/graalvm.adoc +++ b/src/site/antora/modules/ROOT/pages/graalvm.adoc @@ -49,7 +49,7 @@ project. == Using Simple Logger If you use -xref:manual/simple-logger.adoc[Simple Logger] shipped with xref:manual/api.html[Log4j API] +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]