Configuration file

Using a configuration file is the most popular and recommended approach for configuring Log4j Core. In this page we will examine the composition of a configuration file and how Log4j Core uses it.

If you are looking for a quick start on using Log4j in your application or library, please refer to Getting started instead.

Configuration file location

Upon initialization of a new logger context, the anchor of the logging implementation, Log4j Core assigns it a context name and scans the following classpath locations for a configuration file in following order:

  1. Files named log4j2-test<contextName>.<extension>

  2. Files named log4j2-test.<extension>

  3. Files named log4j2<contextName>.<extension>

  4. Files named log4j2.<extension>

The <contextName> and <extension> placeholders above have the following meaning

<contextName>

A name derived from the runtime environment:

  • For standalone Java SE applications, it is a random identifier.

  • For web applications, it is an identifier derived from the application descriptor. See Log4j Web application configuration for details.

<extension>

A file extension supported by a ConfigurationFactory. The order in which an extension will be searched for first depends on the order of the associated ConfigurationFactory. See Predefined ConfigurationFactory plugins for details.

If no configuration file is found, Log4j Core uses the DefaultConfiguration and the status logger prints a warning. The default configuration prints all messages less severe than log4j2.level to the console.

You can override the location of the configuration file using the log4j2.configurationFile system property. In such a case, Log4j Core will guess the configuration file format from the provided file name, or use the default configuration factory if the extension is unknown.

There are certain best-practices we strongly recommend you to adapt in your Log4j configuration:

  • Files prefixed by log4j2-test should only be used on the test classpath.

  • If you are developing an application, don’t use multiple Log4j configuration files with same name, but different extensions. That is, don’t provide both log4j2.xml and log4j2.json files.

  • If you are developing a library, only add configuration files to your test classpath.

Predefined ConfigurationFactory plugins

Log4j Core uses plugins extending from ConfigurationFactory to determine which configuration file extensions are supported, in which order, and how to read them. How this works under the hood and how you can introduce your custom implementations is explained in Extending ConfigurationFactory plugins.

Table 1. Supported configuration file formats by predefined ConfigurationFactory plugins
File format Extension Order

XML

xml

5

JSON

json, jsn

6

YAML

yaml, yml

7

Properties

properties

8

Note that ConfigurationFactory plugins will be employed in descending order. That is, for instance, XML file format will be checked last, as a fallback.

Some ConfigurationFactory plugins require additional dependencies on the classpath:

JPMS users need to add:

module foo.bar {
    requires java.xml;
}
java

to their module-info.java descriptor.

Syntax

Starting with Log4j 2, the configuration file syntax has been considered part of the public API and has remained stable across significant version upgrades.

The syntax of the configuration file changed between Log4j 1 and Log4j 2. Files in the Log4j 1 syntax are ignored by default. To enable partial support for old configuration syntax, see configuration compatibility.

The Log4j runtime is composed of plugins, which are like beans in the Spring Framework and Java EE. Appenders, layouts, filters, configuration loaders, and similar components are all accessed as plugins.

All configuration files are represented internally as a tree of Nodes, which is translated into a tree of Log4j plugins. The tree’s root creates a Configuration object.

A node is a relatively simple structure representing a single Log4j plugin (see Plugin reference for a complete list), such as an appender, layout, or logger configuration.

Each node has:

  • a set of simple string key-value pairs called attributes. Attributes are matched by name against the list of available configuration options of a Log4j plugin.

  • The plugin type attribute specifies the kind of Log4j plugin we want to instantiate.

  • A set of child nodes called nested elements. They are matched by type against the list of nested components a plugin accepts.

Log4j maps the concepts above to the specifics of the configuration format as follows:

Since XML was the original configuration format developed, the mapping from configuration nodes and XML elements is trivial:

  • Each configuration node is represented by an XML element.

  • Each configuration attribute is represented by an XML attribute.

  • The plugin type of a node is equal to the name of the XML tag.

  • Each configuration nested element is represented by a nested XML element.

    There is an alternative XML configuration format called "XML strict format" that is activated by setting the strict attribute of the main <Configuration> element to true. It allows users to use any tag names as long as they provide the plugin type using a type property.

    The XML strict format was conceived as a simplified XML format that can be validated by an XML schema but has fallen into disuse: nowadays, the automatically generated schemas published at https://logging.apache.org/xml/ns/ offer a better alternative and allow users to use a more concise syntax.

See also Format specific notes for exceptions to the rules above.

Main configuration elements

Log4j Core’s logging pipeline is quite complex (see Architecture), but most users only require these elements:

Loggers

Loggers are the entry point of the logging pipeline, which is directly used in the code. Their configuration must specify which level of messages they log and to which appenders they send the messages. We will cover them while configuring loggers.

Appenders

Appenders are the exit point of the logging pipeline. They decide which resource (console, file, database, or similar) the log event is sent to. In the examples of this chapter, we will only use the console appender and the file appender.

Layouts

Layouts tell appenders how to format the log event: text, JSON, XML, or similar. In the examples of this chapter, we will only use Pattern Layout and JSON Template Layout.

A moderately complex configuration might look like this:

Snippet from an example log4j2.xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="https://logging.apache.org/xml/ns"
               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">
  <Appenders>
    <Console name="CONSOLE"> (1)
      <PatternLayout pattern="%p - %m%n"/>
    </Console>
    <File name="MAIN" fileName="logs/main.log"> (2)
      <JsonTemplateLayout/>
    </File>
    <File name="DEBUG_LOG" fileName="logs/debug.log"> (3)
      <PatternLayout pattern="%d [%t] %p %c - %m%n"/>
    </File>
  </Appenders>
  <Loggers>
    <Root level="INFO"> (4)
      <AppenderRef ref="CONSOLE" level="WARN"/>
      <AppenderRef ref="MAIN"/>
    </Root>
    <Logger name="org.example" level="DEBUG"> (5)
      <AppenderRef ref="DEBUG_LOG"/>
    </Logger>
  </Loggers>
</Configuration>
xml
1 Configures a console appender named CONSOLE with a pattern layout.
2 Configures a file appender named MAIN with a JSON template layout.
3 Configures a file appender named DEBUG_LOG with a pattern layout.
4 Configures the root logger at level INFO and connects it to the CONSOLE and MAIN appenders. The CONSOLE appender will only log messages at least as severe as WARN.
5 Configures a logger named "org.example" at level DEBUG and connects it to the DEBUG_LOG appender. The logger is configured to forward messages to its parent (the root appender).

Using the above configuration, the list of appenders that will be used for each log event depends only on the level of the event and the name of the logger, as in the table below:

Logger name Log event level Appenders

org.example.foo

WARN

CONSOLE, MAIN, DEBUG_LOG

org.example.foo

DEBUG

MAIN, DEBUG_LOG

org.example.foo

TRACE

none

com.example

WARN

CONSOLE, MAIN

com.example

INFO

MAIN

com.example

DEBUG

none

Additional configuration elements

A Log4j Core configuration file can also contain these configuration elements:

CustomLevels

Log4j allows the configuration of custom log-level names.

Filters

Users can add Components to loggers, appender references, appenders, or the global configuration object to provide additional filtering of log events.

See Filter configuration for details.

Properties

Represent a set of reusable configuration values for property substitution.

See Property substitution for details.

Scripts

Scripts are a container for JSR 223 scripts that users can use in other Log4j components.

For details, see Scripts configuration.

Global configuration attributes

The main Configuration element has a set of attributes that can be used to tune how the configuration file is used. The principal attributes are listed below. See Plugin reference for a complete list.

monitorInterval

Type

int

Default value

0

Determines the polling interval used by Log4j to check for changes to the configuration file. If a change in the configuration file is detected, Log4j automatically reconfigures the logger context. If set to 0, polling is disabled.

Log4j Core is designed with reliability in mind, which implies that the reconfiguration process can not lose any log event. In order to achieve this Log4j does not stop any appender until the new Configuration is active and reuses resources that are present in both the old and the new Configuration.

In order to guarantee reliability, Log4j may ignore the changes to some appender options, if they would cause log event loss. For example, changing the append option of a file appender, without changing the fileName option is not possible, since it would require closing the underlying file and reopening it with different options. Between the two operations log events might be lost.

status

Type

LEVEL

Status

DEPRECATED

Default value (since 2.24.0)

log4j2.statusLoggerLevel

Default value (before 2.24.0)

value of log4j2.defaultStatusLevel

Overrides the logging level of Status Logger.

Since version 2.24.0, this attribute is deprecated and should be replaced with the log4j2.statusLoggerLevel configuration property instead.

Loggers

Log4j 2 contains multiple types of logger configurations that can be added to the Loggers element of the configuration:

Root

is the logger that receives all events that do not have a more specific logger defined.

See also Plugin reference.

AsyncRoot

is an alternative implementation of the root logger used in the mixed synchronous and asynchronous mode.

See also Plugin reference.

Logger

the most common logger kind, which collects log events from itself and all the children loggers, which do not have an explicit configuration (see logger hierarchy).

See also Plugin Reference.

AsyncLogger

the equivalent of Logger, used in the mixed synchronous and asynchronous mode.

See also Plugin Reference.

There must be at least a Root or AsyncRoot element in every configuration file. Other logger configurations are optional.

Every Logger in your application is assigned to one of these logger configurations (see architecture), which determines the events that will be logged and those that won’t.

Let’s start with an example of logger configuration:

Snippet from an example log4j2.xml
<Loggers>
  <Root level="INFO"> (1)
    <AppenderRef ref="APPENDER1"/>
  </Root>
  <Logger name="org.example.no_additivity" additivity="false"> (2)
    <AppenderRef ref="APPENDER2"/>
  </Logger>
  <Logger name="org.example.no_location" includeLocation="false"> (3)
    <AppenderRef ref="APPENDER3"/>
  </Logger>
  <Logger name="org.example.level" level="DEBUG"> (4)
    <AppenderRef ref="APPENDER4"/>
  </Logger>
</Loggers>
xml

In the example above, we have four logger configurations. They differ from each other regarding the level of log messages that they allow, whether location information will be printed, and which appenders will be used. The table below summarizes the effects of each logger configuration:

Table 2. Logger configurations

Logger name

Level

Additivity

Includes location

Appenders used

1

empty

INFO

N/A

default

APPENDER1

2

org.example.no_additivity

INFO

(inherited)

false

default

APPENDER2

3

org.example.no_location

INFO

(inherited)

true

false

APPENDER1 and APPENDER3

4

org.example.level

DEBUG

true

default

APPENDER1 and APPENDER4

In the following part of this section, we explain in detail all the available options for logger configurations:

name

Type

String

Applies to

Logger and AsyncLogger

Specifies the name of the logger configuration.

Since loggers are usually named using fully qualified class names, this value usually contains the fully qualified name of a class or a package.

additivity

Type

boolean

Default value

true

Applies to

Logger and AsyncLogger

If true (default), all the messages this logger receives will also be transmitted to its parent logger).

level

Type

Level

Default value

It specifies the level threshold that a log event must have to be logged. Log events that are less severe than this setting will be filtered out.

See also Filters if you require additional filtering.

includeLocation

Type

boolean

Default value

  • false, if an asynchronous ContextSelector is used.

  • Otherwise,

    • true for Root and Logger,

    • false for AsyncRoot and AsyncLogger.

See log4j2.contextSelector for more details.

Specifies whether Log4j is allowed to compute location information. If set to false, Log4j will not attempt to infer the location of the logging call unless said location was provided explicitly using one of the available LogBuilder#withLocation() methods.

See Location information for more details.

Appender references

Loggers use appender references to list the appenders to deliver log events.

See Appender references below for more details.

Additional context properties

Loggers can emit additional context data that will be integrated with other context data sources such as ThreadContext.

The value of each property is subject to property substitution twice:

Therefore, if you wish to insert a value that changes in time, you must double the $ sign, as shown in the example below.

Snippet from an example log4j2.xml
<Root>
  <Property name="client.address" value="$${web:request.remoteAddress}"/>
</Root>
<Logger name="org.hibernate">
  <Property name="subsystem" value="Database"/>
</Logger>
<Logger name="io.netty">
  <Property name="subsystem" value="Networking"/>
</Logger>
xml

Filters

See Filters for additional filtering capabilities that can be applied to a logger configuration.

Appender references

Many Log4j components, such as loggers, use appender references to designate which appenders will be used to deliver their events.

Unlike in Log4j 1, where appender references were simple pointers, in Log4j 2, they have additional filtering capabilities.

Appender references can have the following configuration attributes and elements:

ref

Type

String

Specifies the name of the appender to use.

level

Type

Level

It specifies the level threshold that a log event must have to be logged. Log events that are less severe than this setting will be filtered out.

Filters

See Filters for additional filtering capabilities that can be applied to a logger configuration.

Property substitution

Log4j provides a simple and extensible mechanism to reuse values in the configuration file using ${name} expressions, such as those used in Bash, Ant or Maven.

Reusable configuration values can be added directly to a configuration file by using a Properties component.

Snippet from an example log4j2.xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="https://logging.apache.org/xml/ns"
               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">
  <Properties>
    <Property name="log.dir" value="/var/log"/>
  </Properties>
xml

An extensible lookup mechanism can also provide reusable configuration values. See Lookups for more information.

Configuration values defined this way can be used in any configuration attribute by using the following expansion rules:

${name}

If the Properties element of the configuration file has a property named name, its value is substituted. Otherwise, the placeholder is not expanded.

If name contains a : character, it is expanded as in the rule below.

${lookup:name}

If both these conditions hold:

  • lookup is a prefix assigned to a Lookup,

  • the lookup has a value assigned to name,

the value for the lookup is substituted. Otherwise, the expansion of ${name} is substituted.

If name starts with a hyphen - (e.g. -variable), it must be escaped with a backslash \ (e.g. \-variable).

The most common lookup prefixes are:

The above expansions have a version with an additional default value that is expanded if the lookup fails:

${name:-default}

If the Properties element of the configuration file has a property named name, its value is substituted. Otherwise, the expansion of default is substituted.

If name contains a : character, it is expanded as in the rule below.

${lookup:name:-default}

If both these conditions hold:

  • lookup is a prefix assigned to a Lookup,

  • the lookup has a value assigned to name,

the value for the lookup is substituted. Otherwise, the expansion of ${name:-default} is substituted.

To prevent the expansion of one of the expressions above, the initial $ must be doubled as $$.

The same rule applies to the name parameter: if it contains a ${ sequence, it must be escaped as $${.

Example 1. Property substitution example

If your configuration file contains the following definitions:

<Properties>
  <Property name="FOO" value="foo"/>
  <Property name="BAR" value="bar"/>
</Properties>
xml

and the OS environment variable FOO has a value of environment, Log4j will evaluate the expression as follows

Expression Value

${FOO}

foo

${BAZ}

${BAZ}

${BAR:-${FOO}}

bar

${BAZ:-${FOO}}

foo

${env:FOO}

environment

${env:BAR}

bar

${env:BAZ}

${BAZ}

${env:BAR:-${FOO}}

bar

${env:BAZ:-${FOO}}

foo

For security reasons, if the expansion of a ${…​} expression contains other expressions, these will not be expanded.

Properties defined in the Properties container, however, can depend on each other. If your configuration contains, for example:

<Properties>
  <Property name="logging.file" value="${logging.dir}/app.log"/>
  <Property name="logging.dir" value="${env:APP_BASE}/logs"/>
  <Property name="APP_BASE" value="."/>
</Properties>
xml

the logging.dir property will be expanded before the logging.file property, and the expanded value will be substituted in ${logging.dir}/app.log. Therefore, the value of the logging.file property will be:

  • ./logs/app.log if the environment variable APP_BASE is not defined,

  • /var/lib/app/logs/app.log if the environment variable APP_BASE has a value of /var/lib/app.

Runtime property substitution

For most attributes, property substitution is performed only once at configuration time, but there are exceptions to this rule: some attributes are also evaluated when a component-specific event occurs.

In this case:

  • If you want property substitution to happen at configuration time, use one dollar sign, e.g., ${date:HH:mm:ss}.

  • If you want property substitution to happen at runtime, you use two dollar signs, e.g., $${date:HH:mm:ss}

The list of attributes that support runtime property substitution is:

Certain lookups might behave differently when they are expanded at runtime. See lookup evaluation contexts for details.

The Route component of the Routing Appender is a different case altogether. The attributes of its children are expanded at runtime, but are not expanded at configuration time.

Inside the Route component you should not use escaped $${...} expressions, but only unescaped ${...} expressions.

The complete spectrum of behaviors concerning runtime property substitution is given by the routing appender example below:

Snippet from an example log4j2.xml
<Routing name="ROUTING">
  <Routes pattern="$${sd:type}"> (1)
    <Route>
      <File name="ROUTING-${sd:type}"
            fileName="logs/${sd:type}.log"> (2)
        <JsonTemplateLayout>
          <EventTemplateAdditionalField name="type"
                                        value="${sd:type}"/> (2)
        </JsonTemplateLayout>
      </File>
    </Route>
  </Routes>
</Routing>
xml
1 The pattern attribute is evaluated at configuration time, and also each time a log event is routed. Therefore, the dollar $ sign needs to be escaped.
2 All the attributes of children of the Route element have a deferred evaluation. Therefore, they need only one $ sign.

Arbiters

While property substitution allows using the same configuration file in multiple deployment environments, sometimes changing the values of configuration attributes is not enough.

Arbiters are to configuration elements what property substitution is for configuration attributes: they allow to conditionally add a subtree of configuration elements to a configuration file.

Arbiters may occur anywhere an element is allowed in the configuration and can be nested. So, an Arbiter could encapsulate something as simple as a single property declaration or a whole set of appenders, loggers, or other arbiters. The child elements of an arbiter must be valid elements for whatever element is the parent of the arbiter.

For a complete list of available arbiters, see plugin reference. In the examples below, we’ll use the DefaultArbiter, Select and SystemPropertyArbiter.

For example, you might want to use a different layout in a production and development environment:

Snippet from an example log4j2.xml
<Appenders>
  <File name="MAIN" fileName="logs/app.log">
    <SystemPropertyArbiter propertyName="env" propertyValue="dev"> (1)
      <PatternLayout pattern="%d [%t] %p %c - %m%n"/>
    </SystemPropertyArbiter>
    <SystemPropertyArbiter propertyName="env" propertyValue="prod"> (2)
      <JsonTemplateLayout/>
    </SystemPropertyArbiter>
  </File>
</Appenders>
xml
1 If the Java system property env has a value of dev, a pattern layout will be used.
2 If the Java system property env has a value of prod, a JSON template layout will be used.

The above example has a problem: if the Java system property env has a value different from dev or prod, the appender will have no layout.

This is a case when the Select plugin is useful: this configuration element contains a list of arbiters and a DefaultArbiter element. If none of the arbiters match, the configuration from the DefaultArbiter element will be used:

Snippet from an example log4j2.xml
<Select>
  <SystemPropertyArbiter propertyName="env" propertyValue="dev"> (1)
    <PatternLayout/>
  </SystemPropertyArbiter>
  <DefaultArbiter> (2)
    <JsonTemplateLayout/>
  </DefaultArbiter>
</Select>
xml
1 If the Java system property env has a value of dev, a Pattern Layout will be used.
2 Otherwise, a JSON Template Layout will be used.

Composite configuration

There are occasions where multiple configurations might need to be combined. For instance,

  • You have a common Log4j Core configuration that should always be present, and an environment-specific one that extends the common one depending on the environment (test, production, etc.) the application is running on.

  • You develop a framework, and it contains a predefined Log4j Core configuration. Yet you want to allow users to extend it whenever necessary.

  • You collect Log4j Core configurations from multiple sources.

You can provide a list of comma-separated file paths or URLs in the log4j2.configurationFile configuration property, where each resource will get read into a Configuration, and then eventually combined into a single one using CompositeConfiguration.

How does CompositeConfiguration work?

CompositeConfiguration merges multiple configurations into a single one using a MergeStrategy, which can be customized using the log4j2.mergeStrategy configuration property. The default merge strategy works as follows:

  • Global configuration attributes in later configurations replace those in previous configurations. The only exception is the monitorInterval attribute: the lowest positive value from all the configuration files will be used.

  • Properties are aggregated. Duplicate properties override those in previous configurations.

  • Filters are aggregated under CompositeFilter, if more than one filter is defined.

  • Scripts are aggregated. Duplicate definitions override those in previous configurations.

  • Appenders are aggregated. Appenders with the same name are overridden by those in later configurations, including all their elements.

  • Loggers are aggregated. Logger attributes are individually merged, and those in later configurations replace duplicates. Appender references on a logger are aggregated, and those in later configurations replace duplicates. The strategy merges filters on loggers using the rule above.

Format specific notes

XML format

Global configuration attributes

The XML format supports the following additional attributes on the Configuration element.

schema

Type

classpath resource

Default value

null

Specifies the path to a classpath resource containing an XML schema.

strict

Type

boolean

Default value

false

If set to true, all configuration files will be checked against the XML schema provided by the schema.

This setting also enables "XML strict mode" and allows one to specify an element’s plugin type through a type attribute instead of the tag name.

XInclude

XML configuration files can include other files with XInclude.

The list of XInclude and XPath features supported depends upon your JAXP implementation.

Here is an example log4j2.xml file that includes two other files:

Snippet from an example log4j2.xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration xmlns="https://logging.apache.org/xml/ns"
               xmlns:xi="http://www.w3.org/2001/XInclude"
               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">
  <Properties>
    <Property name="filename" value="app.log"/>
  </Properties>
  <xi:include href="xinclude-appenders.xml"/>
  <xi:include href="xinclude-loggers.xml"/>
</Configuration>
xml
Snippet from an example xinclude-appenders.xml
<?xml version="1.0" encoding="UTF-8"?>
<Appenders>
  <Console name="CONSOLE">
    <PatternLayout pattern="%d %m%n"/>
  </Console>
  <File name="FILE" fileName="${filename}">
    <PatternLayout pattern="%d %p %C{1.} [%t] %m%n"/>
  </File>
</Appenders>
xml
Snippet from an example xinclude-loggers.xml
<?xml version="1.0" encoding="UTF-8"?>
<Loggers>
  <Logger name="org.example" level="DEBUG" additivity="false">
    <AppenderRef ref="FILE" />
  </Logger>
  <Root level="ERROR">
    <AppenderRef ref="CONSOLE" />
  </Root>
</Loggers>
xml

Java properties format

The Java properties format is not well suited to represent hierarchical structures.

Switch to XML to avoid additional dependencies, or choose YAML for a format similar to Java properties but less verbose.

The Java properties configuration format is the most verbose of the available formats. To make it more usable, a series of exceptions to the rules in Java properties syntax have been introduced over time:

  1. The following direct children of Configuration have predefined prefixes and do not require to specify a type attribute:

  2. Properties that start with property are used for Property substitution. Their syntax is:

    property.<key> = <value>
    properties
  3. Properties that start with customLevel are used to define custom levels. Their syntax is:

    customLevel.<name> = <intValue>
    properties

    where <name> is the name of the level and <intValue> its numerical value.

  4. The root logger can be configured using properties that start with rootLogger.

  5. A shorthand notation is available that allows users to write:

    rootLogger = INFO, APPENDER
    properties

    instead of:

    rootLogger.level = INFO
    rootLogger.appenderRef.0.ref = APPENDER
    properties
  6. All the keys of the form logger.<name>.appenderRef.<id>, where <name> and <id> are arbitrary, are considered appender references.

  7. To add a filter to a component use a filter.<id> prefix instead of just <id>.

Extending

Log4j Core uses plugins to inject necessary components while reading a configuration file. In this section, we will explore extension points users can hook into to customize the way Log4j Core reads configuration files.

Plugin preliminaries

Log4j plugin system is the de facto extension mechanism embraced by various Log4j components. Plugins provide extension points to components, that can be used to implement new features, without modifying the original component. It is analogous to a dependency injection framework, but curated for Log4j-specific needs.

In a nutshell, you annotate your classes with @Plugin and their (static) factory methods with @PluginFactory. Last, you inform the Log4j plugin system to discover these custom classes. This is done using running the PluginProcessor annotation processor while building your project. Refer to Plugins for details.

Extending ConfigurationFactory plugins

Under the hood, Log4j Core uses plugins extending from ConfigurationFactory to load configuration files. This procedure can be summarized as follows:

  1. Load plugins which extend from ConfigurationFactory and whose plugin category is set to ConfigurationFactory.CATEGORY

  2. Sort them by @Order annotation (in decreasing value order), if present

  3. Feed found configuration files to ConfigurationFactory instances in order, if the file extension is contained by String[] returned from ConfigurationFactory#getSupportedTypes()

If the log4j2.configurationFactory system property is defined, it will be used before any other factory implementations.

For an example, see JsonConfigurationFactory.java on how Log4j Core implements JSON-formatted configuration file read.

Next to introducing new configuration file formats, ConfigurationFactory can be used for programmatic configuration too.

Plugins represented in a configuration file

As explained in Syntax, a configuration file gets parsed into a tree of plugins. If your plugin needs to be represented in a configuration file element, some extra plugin configuration needs to be administered.