Building GraalVM native images

Since version 2.25.0 both Log4j API and its reference implementation provide out-of-the-box support for creating native executables using GraalVM.

This document complements the 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.

Logging API: A logging API is an interface your code or your dependencies directly logs against. It is required at compile-time. It is implementation agnostic to ensure that your application can write logs, but is not tied to a specific logging implementation. Log4j API, SLF4J, JUL (Java Logging), JCL (Apache Commons Logging), JPL (Java Platform Logging) and JBoss Logging are major logging APIs.

Logging implementation: A logging implementation is only required at runtime and can be changed without the need to recompile your software. Log4j Core, JUL (Java Logging), Logback are the most well-known logging implementations.

Logging bridge: Logging implementations accept input from a single logging API of their preference; Log4j Core from Log4j API, Logback from SLF4J, etc. A logging bridge is a simple logging implementation of a logging API that forwards all messages to a foreign logging API. Logging bridges allow a logging implementation to accept input from other logging APIs that are not their primary logging API. For instance, log4j-slf4j2-impl bridges SLF4J calls to Log4 API and effectively enables Log4j Core to accept input from SLF4J.

To make things a little bit more tangible, consider the following visualization of a typical Log4j Core installation with bridges for an application:

Figure 1. Visualization of a typical Log4j Core installation with SLF4J, JUL, and JPL bridges

Are you looking for an example of GraalVM application that uses the Log4j API? Check out the log4j-samples-graalvm project.

Using Simple Logger

If you use Simple Logger shipped with Log4j API in your application, no additional steps are required to compile a GraalVM native image.

Using Log4j Core

Since version 2.25.0, Log4j Core and all its official extensions are bundled with the necessary 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 standard location, you need to create a META-INF/native-image/<groupId>/<artifactId>/resource-config.json file in your classpath with content:
```
{
  "resources": {
    "includes": [
      {
        "pattern": "path/to/your/configuration/file"
      }
    ]
  }
}
```
If you use third-party Log4j Plugin JARs you need to make sure they contain a reflect-config.json metadata file. If that is not the case, please point the maintainer to the Log4j Plugin registration documentation.

Using JUL

Since version 2.24.0 the Log4j API to JUL bridge is tested for compatibility with GraalVM.

Although java.util.logging is embedded into the JRE, currently not all j.u.l.Formatter and j.u.l.Handler implementations have the required GraalVM metadata. See the official Add Logging to a Native Executable guide for more information on how to add additional elements to your configuration.

See reflect-config.json in our log4j-samples-graalvm example project for an example on how to enable j.u.l.FileHandler.

Using Logback

Since version 2.24.0 the 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 GraalVM reachability metadata repository.

See the GraalVM Reachability Metadata Support documentation appropriate for your build tool for more information: