Log4j Transform CLI Tools

The Log4j Transform CLI Tools are a set of command line tools to help users with various Log4j-related formats.

`log4j-converter-plugin-descriptor`

The log4j-converter-plugin-descriptor tool helps you to create custom plugin descriptors and align their content with the GraalVM reachability metadata. This can be used to create smaller GraalVM native images by removing the parts of Log4j Core that are not used by the application.

Custom plugin descriptors are not required for applications running in the JVM. If you are shading/shadowing your application, and you need to merge multiple plugin descriptors, use the Log4j Plugin Descriptor Transformer instead.

To create a custom plugin descriptor and reachability metadata descriptor, you need to:

Extract the information contained in the Log4j2Plugins.dat descriptors in your runtime classpath. See Converting from Log4j2Plugins.dat to Log4j2Plugins.json on how to do it.
Select the plugins that you want in your GraalVM application. See Selecting plugins for some tips on how to do it.
Convert your list of plugins back into the Log4j2Plugins.dat format. See Creating a custom Log4j2Plugins.dat file for more information.
Create a custom reflect-config.json using the reduced list of Log4j plugins. See Creating a custom reflect-config.json file for more details.

Converting from `Log4j2Plugins.dat` to `Log4j2Plugins.json`

To convert all the Log4j2Plugins.dat files on your application’s classpath run:

java -jar log4j-converter-plugin-descriptor-0.3.0-SNAPSHOT.jar \
    toJson [-o=<outputDirectory>] <classPathElement>...

where:

<outputDirectory>: The directory, where the command’s output will be saved. Defaults to the current working directory.
<classPathElement>: A list of file paths to the runtime dependencies of your application, separated by either spaces or your system path separator (: for UNIX and ; for Windows).

The command will generate a Log4j2Plugins.json file in the output directory.

Selecting plugins

The Log4j2Plugins.json file contains all the Log4j Plugins contained on your classpath and grouped by category/namespace. A functional Log4j Core installation needs these categories:

configurationfactory: Unless you have a custom ConfigurationFactory you need to include at least the configuration factory for your configuration format.
core: This category contains all the plugins that can be used in a configuration file. You can browse the plugin reference to choose those that you need. A minimal Log4j Core installation will certainly need:

The Appenders and Loggers plugins.
Either the Root and Logger plugins or the AsyncRoot and AsyncLogger plugins.
At least one appender plugin. See Appenders for more information on appenders.
At least one layout plugin. See Layouts for more information on layouts.

If you plan to define properties for property substitution in your configuration file, consider adding the Properties and Property plugins.

converter: If you plan to use Pattern Layout you need to add some pattern converter plugins.
jsontemplateresolverfactory: To use JSON Template Layout you need to add some template resolver factories.
lookup: The lookup category contains lookups that can be used to retrieve configuration values from external sources. See also lookup plugins for a list of options.
typeconverter: This category provides basic conversion capabilities. Unless you know what you are doing, keep all the plugins.

Creating a custom `Log4j2Plugins.dat` file

Once you have chosen the plugins for your Log4j Core custom image, you need to convert the modified Log4j2Plugins.json file back to its original format. To do that run:

java -jar log4j-converter-plugin-descriptor-0.3.0-SNAPSHOT.jar \
    fromJson [-o=<outputDirectory>] <jsonPluginDescriptor>

where:

<outputDirectory>: The directory, where the command’s output will be saved. This parameter should point at the root of your application’s classpath (e.g., the src/main/resources) folder. Defaults to the current working directory.
<jsonPluginDescriptor>: The path to the Log4j2Plugins.json file.

The command will generate a Log4j2Plugins.dat file in the org/apache/logging/log4j/core/config/plugins subfolder of the output directory.

Creating a custom `reflect-config.json` file

The same Log4j2Plugins.json file can be used to trim the GraalVM reachability metadata embedded in Log4j 2.25.0 and later, so that they contain only the classes required by the selected plugins. To extract all the reflect-config.json files from your runtime classpath and remove the unnecessary classes run:

java -jar log4j-converter-plugin-descriptor-0.3.0-SNAPSHOT.jar \
    filterReflectConfig [-o=<outputDirectory>] <jsonPluginDescriptor> <classPathElement>...

where:

<outputDirectory>: The directory, where the command’s output will be saved. This parameter should point at the root of your application’s classpath (e.g., the src/main/resources) folder. Defaults to the current working directory.
<jsonPluginDescriptor>: The path to the Log4j2Plugins.json file.
<classPathElement>: A list of file paths to the runtime dependencies of your application, separated by either spaces or your system path separator (: for UNIX and ; for Windows).

The command will filter and output each reflect-config.json in its original path under the META-INF/native-image subfolder of the output directory.