log4j-samples-graalvm/README.adoc

////
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

    https://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.
////
= Apache Log4j Samples: GraalVM native image
:log4j-version: 2.24.0-SNAPSHOT

This project shows how to generate a native image using GraalVM.

To use it:

. Set the `JAVA_HOME` environment variable to the path of a GraalVM installation,
. Set the current working directory to the folder containing this file,
. Generate the artifact locally with:
+
[source,shell]
----
../mvnw clean verify -Puse-<backend>
----
+
where `<backend>` can be:

`simple`::
This profile uses `SimpleLogger` as logging backend.

`jul`::
This profile uses `java.util.logging` as logging backend.

`logback`::
This profile uses Logback as logging backend.

`log4j-core`::
This profile uses Log4j Core as logging backend with its out-of-the-box reachability metadata.
It uses
https://logging.apache.org/log4j/2.x/manual/pattern-layout.html[Pattern Layout]
to format log events.

`log4j-core-jtl`::
This profile uses Log4j Core as logging backend with its out-of-the-box reachability metadata.
It uses
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html[JSON Template Layout]
to format log events.

[#log4j-core-minimal]
`log4j-core-minimal`::
This profile uses Log4j Core a logging backend with an external reachability metadata source optimized for size.
It uses
https://logging.apache.org/log4j/2.x/manual/pattern-layout.html[Pattern Layout]
to format log events.

[#log4j-core-jtl-minimal]
`log4j-core-jtl-minimal`::
This profile uses Log4j Core a logging backend with an external reachability metadata source optimized for size.
It uses
https://logging.apache.org/log4j/2.x/manual/json-template-layout.html[JSON Template Layout]
to format log events.

. Run the application with
+
[source,shell]
----
target/log4j-samples-graalvm
----

== Reachability metadata

Log4j, as many other Java libraries, relies heavily on reflection to convert the configuration file into an instance of a
https://logging.apache.org/log4j/2.x/javadoc/log4j-core/org/apache/logging/log4j/core/config/Configuration.html[Configuration]
object.
The classes that are accessed through reflection are called Log4j plugins and GraalVM must be aware of their existence through the usage of reachability metadata.

See
https://logging.apache.org/log4j/2.x/manual/plugins.html[Log4j plugins]
and
https://www.graalvm.org/latest/reference-manual/native-image/metadata/[GraalVM reachability metadata]
for more details.

The
https://logging.apache.org/log4j/2.x/manual/plugins.html#plugin-registry[Log4j plugin descriptors]
and
GraalVM reachability metadata used in the customized
<<log4j-core-minimal,`use-log4j-core-minimal`>>
and
<<log4j-core-jtl-minimal,`use-log4j-core-jtl-minimal`>>
profiles were generated using the procedure described in the documentation of the
https://logging.apache.org/log4j/transform/cli.html#log4j-converter-plugin-descriptor[`log4j-converter-plugin-descriptor` tool].

== Native binary size

Using GraalVM 21.0.4 on Linux x64, the native binaries have the following size:

[CAUTION]
====
Since this is a trivial Java application, the difference between the binary size without and with Log4j is large: when Log4j is added GraalVM must compile many additional `java.base` classes.

In a typical application, those classes are already required, so the difference should be smaller.
====

[cols="3,1"]
|===
| Configuration | Size

| With `SimpleLogger`
| 13.90 MiB

| With `java.util.logging`
| 14.10 MiB

| With Logback
| 30.62 MiB

| With Log4j Core (manually optimized reachability metadata)
| 36.19 MiB

| With Log4j Core + JSON Template Layout (manually optimized reachability metadata)
| 37.40 MiB

| With Log4j Core (embedded full reachability metadata)
| 46.80 MiB

| With Log4j Core + JSON Template Layout (embedded full reachability metadata)
| 47.37 MiB

|===