This is an automated email from the ASF dual-hosted git repository.
grobmeier pushed a commit to branch ms12_restructure_website_2x
in repository https://gitbox.apache.org/repos/asf/logging-log4j2.git
The following commit(s) were added to refs/heads/ms12_restructure_website_2x by
this push:
new e904a46f57 transformed config docs to asciidoc, syncing with 3x
e904a46f57 is described below
commit e904a46f571fce3fc8bfe8de59f8ca2ee84a1999
Author: Christian Grobmeier <[email protected]>
AuthorDate: Mon Mar 11 15:29:18 2024 +0100
transformed config docs to asciidoc, syncing with 3x
---
src/site/asciidoc/manual/configuration.adoc | 1 +
src/site/xdoc/manual/configuration.xml.vm | 2999 ---------------------------
2 files changed, 1 insertion(+), 2999 deletions(-)
diff --git a/src/site/asciidoc/manual/configuration.adoc
b/src/site/asciidoc/manual/configuration.adoc
new file mode 100644
index 0000000000..0c770bffb2
--- /dev/null
+++ b/src/site/asciidoc/manual/configuration.adoc
@@ -0,0 +1 @@
+Ralph Goers <[email protected]>
diff --git a/src/site/xdoc/manual/configuration.xml.vm
b/src/site/xdoc/manual/configuration.xml.vm
deleted file mode 100644
index 1497a68cea..0000000000
--- a/src/site/xdoc/manual/configuration.xml.vm
+++ /dev/null
@@ -1,2999 +0,0 @@
-<?xml version="1.0"?>
-<!--
- 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.
--->
-
-#set($dollar = '$')
-
-<document xmlns="http://maven.apache.org/XDOC/2.0";
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
- xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
- <properties>
- <title>Configuring Log4j 2</title>
- <author email="[email protected]">Ralph Goers</author>
- </properties>
-
- <body>
- <section name="Configuration">
- #if (!$alignedFileName)
- #set ($isPDF = true)
- #else
- #set ($isPDF = false)
- #end
- <p>Inserting log requests into the application code requires a fair
- amount of planning and effort. Observation shows that approximately 4
- percent of code is dedicated to logging. Consequently, even
moderately
- sized applications will have thousands of logging statements embedded
- within their code. Given their number, it becomes imperative to
- manage these log statements without the need to modify them manually.
- </p>
- <p>
- Configuration of Log4j 2 can be accomplished in 1 of 4 ways:
- </p>
- <ol>
- <li>Through a configuration file written in XML, JSON, YAML, or
properties format.</li>
- <li>Programmatically, by creating a ConfigurationFactory and
Configuration implementation.</li>
- <li>Programmatically, by calling the APIs exposed in the
Configuration interface to add
- components to the default configuration.</li>
- <li>Programmatically, by calling methods on the internal Logger
class.</li>
- </ol>
- <p>
- This page focuses primarily on configuring Log4j through a
configuration file. Information on
- programmatically configuring Log4j can be found at <a
href="./extending.html">Extending Log4j 2</a>
- and <a href="customconfig.html">Programmatic Log4j Configuration</a>.
- </p>
- <p>
- All available formats are functionally equivalent. For example, a
configuration file in XML can be
- rewritten using the properties format (and the opposite) without any
loss of functionality. However,
- the hierarchical nature of a Log4j configuration can be captured
better in formats which naturally
- support nesting so XML, JSON, and YAML files, are usually easier to
use.
- </p>
- <p>
- Note that unlike Log4j 1.x, the public Log4j 2 API does not expose
methods to add, modify or remove
- appenders and filters or manipulate the configuration in any way.
- </p>
- <a name="Architecture"/>
- <subsection name="Configuration Architecture">
- <p>
- In part because support for XML was added first, Log4j's
configuration is reflected as a tree structure.
- In fact every configuration dialect, including the
ConfigurationBuilder, generates a Node for every
- configuration element. A node is a fairly simple structure that
contains a set of attributes, a set of
- child nodes and a PluginType. It is important to note that every
Node must have a corresponding plugin,
- as the plugin is the component that actually performs the work
represented by the node.
- </p>
- <p>
- Every document type supported by Log4j has a ConfigurationFactory.
The factory itself is a Log4j plugin
- that declares what file extensions it supports and what its
priority is. Properties have the highest
- precedence with a value of 8, followed by yaml, json and xml. When
autoconfiguration is performed Log4j
- will call each of these factories in order to determine which, if
any, support the specified configuration
- file format. If one is found that factory will create the
corresponding Configuration object and pass the
- reference to the configuration data to it.
- </p>
- <p>Every configuration implementation, such as XMLConfiguration,
YamlConfiguration, JsonConfiguration, etc.
- has the primary task of converting the configuration text into the
Node tree, typically by parsing the
- text with whatever tool is available for that document type. It
should be noted that while most of the
- supported document types are inherently tree structured, the Java
properties syntax is not. Because of the
- need to convert the syntax into a Node tree the Java properties
syntax used by Log4j required all properties
- follow a naming pattern that made the tree structure clear. As a
consequence, the Java Properties format
- tends to be more verbose than using a different document type.
- </p>
- <p>
- Once the Node tree is created control is delegated to
AbstractConfiguration, which converts the Nodes into
- their respective Java objects using Log4j's Plugin system and
provides all the common functionality.
- </p>
- </subsection>
- <a name="Arbiters"/>
- <subsection name="Arbiters">
- <p>
- In some situations it is desirable to have a single logging
configuration that can be used in any
- deployment environment. For example, it may be necessary to have a
different default logging level in
- production then in development. Another case might be where one
type of appender is used when running
- natively but another is used when deployed to a docker container.
One way to handle that is to use
- a tool such as Spring Cloud Config Server that can be environment
aware and serve a different file for
- each environment. Another option is to include Arbiters in the
configuration.
- </p>
- <p>
- An Arbiter is a Log4j plugin that has the job of determining
whether other configured elements should be
- included in the generated configuration. While all other "Core"
plugins are designed to execute as part of
- Log4j's runtime logic Arbiters execute after the Node tree has
been constructed but before the tree is
- converted to a configuration. An Arbiter is a Node itself which is
always removed from the Node tree
- before it the tree is processed. All an arbiter really does is
provide a method that returns a boolean
- result that determines whether the child nodes of the arbiter
should remain in the configuration or be
- pruned.
- </p>
- <p>
- Arbiters may occur anywhere an element is allowed in the
configuration. So an Arbiter could encapsulate
- something as simple as a single property declaration or a whole
set of Appenders or Loggers. Arbiters
- may also be nested although Arbiters that are the descendant of
another arbiter will only be evaluated if the
- ancestor returned true. The child elements of an Arbiter must be
valid elements for whatever element is
- the parent of the Arbiter.
- </p>
- <p>
- This example shows two Arbiters configured that will include
either a Console Appender or a List Appender
- depending on whether the value of the env System Property is "dev"
or "prod".
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<Configuration name="ConfigTest" status="ERROR" monitorInterval="5">
- <Appenders>
-
- <SystemPropertyArbiter propertyName="env" propertyValue="dev">
- <Console name="Out">
- <PatternLayout pattern="%m%n"/>
- </Console>
- </SystemPropertyArbiter>
- <SystemPropertyArbiter propertyName="env" propertyValue="prod">
- <List name="Out">
- </List>
- </SystemPropertyArbiter>
-
- </Appenders>
- <Loggers>
- <Logger name="org.apache.test" level="trace" additivity="false">
- <AppenderRef ref="Out"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Out"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>
- Normally Arbiters act in isolation from other Arbiters. That is,
the outcome of one Arbiter will not
- impact any other Arbiters. This can be cumbersome when you simply
want to use one of a set of choices. A
- special plugin named "Select" can be used in this case. Each
element under the Select is required to be
- an Arbiter. The first Arbiter that returns a true value will be
the one used while others are ignored.
- If no Arbiter returns true a DefaultArbiter may be configured with
the default configuration elements.
- The DefaultArbiter is an Arbiter that always returns true, so
using it outside of a Select would result in
- its configured elements always being included just as if it hadn't
been present.
- </p>
- <p>
- This example shows an Arbiter that uses Javascript residing in a
separate file to determine whether to
- include the Console Appender. If the result is false then a List
Appender will be included.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<Configuration name="ConfigTest" status="ERROR" monitorInterval="5">
- <Appenders>
- <Select>
- <ScriptArbiter>
- <ScriptFile language="JavaScript"
path="src/test/resources/scripts/prodtest.js" charset="UTF-8" />
- <Console name="Out">
- <PatternLayout pattern="%m%n"/>
- </Console>
- </ScriptArbiter>
- <DefaultArbiter>
- <List name="Out">
- </List>
- </DefaultArbiter>
- </Select>
- </Appenders>
- <Loggers>
- <Logger name="org.apache.test" level="trace" additivity="false">
- <AppenderRef ref="Out"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Out"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>
- Natively Log4j contains the SystemProperty Arbiter that can
evaluate whether to include elements based on
- whether a SystemProperty is non-null or has a specific value, a
ClassArbiter that makes its decision
- based on whether the specified class is present, and a
ScriptArbiter that makes its decision based
- on the result of the script configured with it.
- </p>
- <p>
- For Spring Boot users an Arbiter named <code>SpringProfile</code>
has been provided. The specified profiles
- are evaluated by Spring's
<code>Environment.acceptsProfiles()</code> method, so any expressions it
supports
- may be used as the name attribute.
- </p>
- <p>This example will use a Console Appender when the Spring profile
is "dev" or "staging" and a List
- Appender when the active profile is "prod".
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<Configuration name="ConfigTest" status="ERROR" monitorInterval="5">
- <Appenders>
-
- <SpringProfile name="dev | staging">
- <Console name="Out">
- <PatternLayout pattern="%m%n"/>
- </Console>
- </SpringProfile>
- <SpringProfile name="prod">
- <List name="Out">
- </List>
- </SpringProfile>
-
- </Appenders>
- <Loggers>
- <Logger name="org.apache.test" level="trace" additivity="false">
- <AppenderRef ref="Out"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Out"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- </subsection>
- <a name="AutomaticConfiguration"/>
- <subsection name="Automatic Configuration">
- <p>
- Log4j has the ability to automatically configure itself during
initialization.
- When Log4j starts it will locate all the ConfigurationFactory
plugins and arrange them in weighted
- order from highest to lowest. As delivered, Log4j contains four
ConfigurationFactory implementations:
- one for JSON, one for YAML, one for properties, and one for XML.
- </p>
- <ol>
- <li>Log4j will inspect the
<code>"log4j2.configurationFile"</code> system property and, if set, will
attempt to
- load the configuration using the
<code>ConfigurationFactory</code> that matches the file
- extension. Note that this is not restricted to a location on
the local file system and may contain
- a URL.</li>
- <li>If no system property is set the properties
ConfigurationFactory will look for
- <code>log4j2-test.properties</code> in the classpath.</li>
- <li>If no such file is found the YAML ConfigurationFactory will
look for
- <code>log4j2-test.yaml</code> or <code>log4j2-test.yml</code>
in the classpath.</li>
- <li>If no such file is found the JSON ConfigurationFactory will
look for
- <code>log4j2-test.json</code> or <code>log4j2-test.jsn</code>
in the classpath.</li>
- <li>If no such file is found the XML ConfigurationFactory will
look for
- <code>log4j2-test.xml</code> in the classpath.</li>
- <li>If a test file cannot be located the properties
ConfigurationFactory will look for
- <code>log4j2.properties</code> on the classpath.</li>
- <li>If a properties file cannot be located the YAML
ConfigurationFactory will look for
- <code>log4j2.yaml</code> or <code>log4j2.yml</code> on the
classpath.</li>
- <li>If a YAML file cannot be located the JSON
ConfigurationFactory will look for
- <code>log4j2.json</code> or <code>log4j2.jsn</code> on the
classpath.</li>
- <li>If a JSON file cannot be located the XML
ConfigurationFactory will try to locate
- <code>log4j2.xml</code> on the classpath.</li>
- <li>If no configuration file could be located the
<code>DefaultConfiguration</code> will
- be used. This will cause logging output to go to the
console.</li>
- </ol>
- <p>An example application named <code>MyApp</code> that uses log4j
can be used to illustrate how
- this is done.
- </p>
-<pre class="prettyprint linenums"><![CDATA[
-import com.foo.Bar;
-
-// Import log4j classes.
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.LogManager;
-
-public class MyApp {
-
- // Define a static logger variable so that it references the
- // Logger instance named "MyApp".
- private static final Logger logger = LogManager.getLogger(MyApp.class);
-
- public static void main(final String... args) {
-
- // Set up a simple configuration that logs on the console.
-
- logger.trace("Entering application.");
- Bar bar = new Bar();
- if (!bar.doIt()) {
- logger.error("Didn't do it.");
- }
- logger.trace("Exiting application.");
- }
-}
-]]></pre>
- <p>
- <code>MyApp</code> begins by importing Log4j related classes. It
- then defines a static logger variable with the name
<code>MyApp</code>
- which happens to be the fully qualified name of the class.
- </p>
- <p>
- <code>MyApp</code> uses the <code>Bar</code> class defined in the
package<code>com.foo</code>.
- </p>
-<pre class="prettyprint linenums"><![CDATA[
-package com.foo;
-import org.apache.logging.log4j.Logger;
-import org.apache.logging.log4j.LogManager;
-
-public class Bar {
- static final Logger logger = LogManager.getLogger(Bar.class.getName());
-
- public boolean doIt() {
- logger.entry();
- logger.error("Did it again!");
- return logger.exit(false);
- }
-}
-]]></pre>
- <p>
- Log4j will provide a default configuration if it cannot locate a
configuration file. The default
- configuration, provided in the DefaultConfiguration class, will
set up:
- </p>
- <ul>
- <li>A <a class="javadoc"
href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/ConsoleAppender.html">ConsoleAppender</a>
- attached to the root logger.</li>
- <li>A <a class="javadoc"
href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html">PatternLayout</a>
- set to the pattern "%d{HH:mm:ss.SSS} [%t] %-5level %logger{36}
- %msg%n" attached to the ConsoleAppender</li>
- </ul>
- <p>
- Note that by default Log4j assigns the root logger to
<code>Level.ERROR</code>.
- </p>
- <p>The output of MyApp would be similar to:
- </p>
-<pre><![CDATA[
-17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-17:13:01.540 [main] ERROR MyApp - Didn't do it.
-]]></pre>
- <p>
- As was described previously, Log4j will first attempt to configure
itself from configuration files. A
- configuration equivalent to the default would look like:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
- <Console name="Console" target="SYSTEM_OUT">
- <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} -
%msg%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Root level="error">
- <AppenderRef ref="Console"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>
- Once the file above is placed into the classpath as log4j2.xml you
will get results identical to
- those listed above. Changing the root level to trace will result
in results similar to:
- </p>
- <pre><![CDATA[
-17:13:01.540 [main] TRACE MyApp - Entering application.
-17:13:01.540 [main] TRACE com.foo.Bar - entry
-17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-17:13:01.540 [main] TRACE com.foo.Bar - exit with (false)
-17:13:01.540 [main] ERROR MyApp - Didn't do it.
-17:13:01.540 [main] TRACE MyApp - Exiting application.
-]]></pre>
- <p>
- Note that status logging is disabled when the default
configuration is used.
- </p>
- </subsection>
- <a name="Configuration From a URI"/>
- <subsection name="Configuration From a URI">
- <p>
- When <code>log4j2.configurationFile</code> references a URL, Log4j
will first determine if the URL reference
- a file using the file protocol. If it does Log4j will validate
that the file URL is valid and continue
- processing as previously described. If it contains a protocol
other than file then Log4j will inspect
- the value of the
<code>log4j2.Configuration.allowedProtocols</code> system property. If the
provided list
- contains the protocol specified then Log4j will use the URI to
locate the specified configuration file. If
- not an exception will be thrown and an error message will be
logged. If no value is provided for the
- system property it will default to "https, file, jar". Use of any
protocol other than "file" can be
- prevented by setting the system property value to "_none". This
value would be an invalid protocol so cannot
- conflict with any custom protocols that may be present.
- </p>
- <p>
- Log4j supports access to remote URLs that require authentication.
Log4j supports basic authentication
- out of the box. If the <code>log4j2.Configuration.username</code>
and <code>log4j2.Configuration.password</code>
- are specified those values will be used to perform the
authentication. If the password is encrypted a custom
- password decryptor may be supplied by specifying the fully
qualified class name in the
- <code>log4j2.Configuration.passwordDecryptor</code> system
property. A custom
- <code>AuthenticationProvider</code> may be used by setting the
- <code>log4j2.Configuration.authenticationProvider</code> system
property to the fully qualified class name
- of the provider.
- </p>
-
- </subsection>
- <a name="Additivity"/>
- <subsection name="Additivity">
- <p>
- Perhaps it is desired to eliminate all the TRACE output from
everything except <code>com.foo.Bar</code>.
- Simply changing the log level would not accomplish the task.
Instead, the solution is to
- add a new logger definition to the configuration:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<Logger name="com.foo.Bar" level="TRACE"/>
-<Root level="ERROR">
- <AppenderRef ref="STDOUT">
-</Root>
-]]></pre>
- <p>
- With this configuration all log events from
<code>com.foo.Bar</code> will be recorded while only error
- events will be recorded from all other components.
- </p>
- <p>
- In the previous example all the events from
<code>com.foo.Bar</code> were still written to the Console. This is
- because the logger for <code>com.foo.Bar</code> did not have any
appenders configured while its parent did. In fact,
- the following configuration
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
- <Console name="Console" target="SYSTEM_OUT">
- <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} -
%msg%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="com.foo.Bar" level="trace">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Console"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>would result in</p>
- <pre><![CDATA[
-17:13:01.540 [main] TRACE com.foo.Bar - entry
-17:13:01.540 [main] TRACE com.foo.Bar - entry
-17:13:01.540 [main] ERROR com.foo.Bar - Did it again!
-17:13:01.540 [main] TRACE com.foo.Bar - exit (false)
-17:13:01.540 [main] TRACE com.foo.Bar - exit (false)
-17:13:01.540 [main] ERROR MyApp - Didn't do it.
-]]></pre>
- <p>Notice that the trace messages from <code>com.foo.Bar</code>
appear twice. This is because the appender associated
- with logger <code>com.foo.Bar</code> is first used, which writes
the first instance to the Console. Next, the parent
- of <code>com.foo.Bar</code>, which in this case is the root
logger, is referenced. The event is then passed to its
- appender, which is also writes to the Console, resulting in the
second instance. This is known as
- additivity. While additivity can be quite a convenient feature (as
in the first previous example where
- no appender reference needed to be configured), in many cases this
behavior is considered undesirable
- and so it is possible to disable it by setting the additivity
attribute on the logger to false:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN">
- <Appenders>
- <Console name="Console" target="SYSTEM_OUT">
- <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} -
%msg%n"/>
- </Console>
- </Appenders>
- <Loggers>
- <Logger name="com.foo.Bar" level="trace" additivity="false">
- <AppenderRef ref="Console"/>
- </Logger>
- <Root level="error">
- <AppenderRef ref="Console"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>
- Once an event reaches a logger with its additivity set to false
the event will not be passed to
- any of its parent loggers, regardless of their additivity setting.
- </p>
- </subsection>
- <a name="AutomaticReconfiguration"/>
- <subsection name="Automatic Reconfiguration">
- <p>
- When configured from a File, Log4j has the ability to
automatically detect changes to the configuration
- file and reconfigure itself. If the <code>monitorInterval</code>
attribute is specified on the configuration
- element and is set to a non-zero value then the file will be
checked the next time a log event is evaluated
- and/or logged and the monitorInterval has elapsed since the last
check. The example below shows how
- to configure the attribute so that the configuration file will be
checked for changes only after at
- least 30 seconds have elapsed. The minimum interval is 5 seconds.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration monitorInterval="30">
-...
-</Configuration>
-]]></pre>
- </subsection>
- <a name="ChainsawSupport"/>
- <subsection name="Chainsaw can automatically process your log files
(Advertising appender configurations)">
- <p>
- Log4j provides the ability to 'advertise' appender configuration
details for all file-based appenders as well
- as socket-based appenders. For example, for file-based appenders,
the file location and the pattern layout in the file
- are included in the advertisement. Chainsaw and other external
systems can discover these advertisements and
- use that information to intelligently process the log file.
- </p>
- <p>
- The mechanism by which an advertisement is exposed, as well as the
advertisement format, is specific to each
- Advertiser implementation. An external system which would like to
work with a specific Advertiser implementation
- must understand how to locate the advertised configuration as well
as the format of the advertisement. For example,
- a 'database' Advertiser may store configuration details in a
database table. An external system can read
- that database table in order to discover the file location and the
file format.
- </p>
- <p>
- Log4j provides one Advertiser implementation, a 'multicastdns'
Advertiser, which advertises appender configuration
- details via IP multicast using the <a
href="https://github.com/jmdns/jmdns";>JmDNS</a> library.
- </p>
- <p>
- Chainsaw automatically discovers log4j's multicastdns-generated
advertisements and displays those discovered
- advertisements in Chainsaw's Zeroconf tab (if the jmdns library is
in Chainsaw's classpath). To begin parsing and tailing
- a log file provided in an advertisement, just double-click the
advertised entry in Chainsaw's Zeroconf tab.
- Currently, Chainsaw only supports FileAppender advertisements.
- </p>
- <p>
- To advertise an appender configuration:
- </p>
- <ul>
- <li>Add the JmDNS library from <a
href="https://github.com/jmdns/jmdns/releases";>JmDNS GitHub Releases</a> to the
application classpath</li>
- <li>Set the 'advertiser' attribute of the configuration element
to 'multicastdns'</li>
- <li>Set the 'advertise' attribute on the appender element to
'true'</li>
- <li>If advertising a FileAppender-based configuration, set the
'advertiseURI' attribute on the appender element to an appropriate URI</li>
- </ul>
- <p>
- FileAppender-based configurations require an additional
'advertiseURI' attribute to be specified on the appender.
- The 'advertiseURI' attribute provides Chainsaw with information on
how the file can be accessed.
- For example, the file may be remotely accessible to Chainsaw via
ssh/sftp by specifying a Commons VFS
- (<a
href="https://commons.apache.org/proper/commons-vfs/";>https://commons.apache.org/proper/commons-vfs/</a>)
sftp:// URI,
- an http:// URI may be used if the file is accessible through a web
server, or a file:// URI can be specified
- if accessing the file from a locally-running instance of Chainsaw.
- </p>
- <p>
- Here is an example advertisement-enabled appender configuration
which can be used by a locally-running Chainsaw to
- automatically tail the log file (notice the file:// advertiseURI):
- </p>
- <p>
- <b>Please note, you must add the JmDNS library mentioned above.</b>
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration advertiser="multicastdns">
-...
-</Configuration>
-<Appenders>
- <File name="File1" fileName="output.log" bufferedIO="false"
advertiseURI="file://path/to/output.log" advertise="true">
- ...
- </File>
-</Appenders>
-]]></pre>
-</subsection>
- <a name="ConfigurationSyntax"/>
- <subsection name="Configuration Syntax">
- <p>
- As of version 2.9, for security reasons, Log4j does not process
DTD in XML files.
- If you want to split the configuration in multiple files, use <a
href="#XInclude">XInclude</a> or
- <a href="#CompositeConfiguration">Composite Configuration</a>.
- </p>
- <p>
- As the previous examples have shown as well as those to follow,
Log4j allows you to easily
- redefine logging behavior without needing to modify your
application. It is possible to
- disable logging for certain parts of the application, log only
when specific criteria are met such
- as the action being performed for a specific user, route output to
Flume or a log reporting system,
- etc. Being able to do this requires understanding the syntax of
the configuration files.
- </p>
- <p>
- The configuration element in the XML file accepts several
attributes:
- </p>
- <table>
- <tr>
- <th>Attribute Name</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>advertiser</td>
- <td>(Optional) The Advertiser plugin name which will be used
to advertise individual
- FileAppender or SocketAppender configurations. The only
Advertiser plugin provided is 'multicastdns".</td>
- </tr>
- <tr>
- <td>dest</td>
- <td>Either "err" for stderr, "out" for stdout, a file path, or
a URL.</td>
- </tr>
-
- <tr>
- <td>monitorInterval</td>
- <td>The minimum amount of time, in seconds, that must elapse
before the file configuration
- is checked for changes.</td>
- </tr>
- <tr>
- <td>name</td>
- <td>The name of the configuration.</td>
- </tr>
- <tr>
- <td>packages</td>
- <td><b>Use of the packages attribute is deprecated and will be
removed in Log4j 3.0.</b> Plugins
- should be processed with the Log4j annotation processor.
-
- A comma separated list of package names to search for
plugins. Plugins are only loaded
- once per classloader so changing this value may not have any
effect upon reconfiguration.</td>
- </tr>
- <tr>
- <td>schema</td>
- <td>Identifies the location for the classloader to located the
XML Schema to use to validate
- the configuration. Only valid when strict is set to true. If
not set no schema validation
- will take place.</td>
- </tr>
- <tr>
- <td>shutdownHook</td>
- <td>Specifies whether or not Log4j should automatically
shutdown when the JVM shuts down. The
- shutdown hook is enabled by default but may be disabled by
setting this attribute to "disable"</td>
- </tr>
- <tr>
- <td>shutdownTimeout</td>
- <td>Specifies how many milliseconds appenders and background
tasks will get to shutdown when the JVM shuts
- down. Default is zero which mean that each appender uses its
default timeout, and don't wait for background
- tasks. Not all appenders will honor this, it is a hint and
not an absolute guarantee that the shutdown
- procedure will not take longer. Setting this too low increase
the risk of losing outstanding log events
- not yet written to the final destination. See <a
class="javadoc"
-
href="../log4j-core/target/site/apidocs/org/apache/logging/log4j/core/LoggerContext.html${esc.hash}stop(long,
java.util.concurrent.TimeUnit)">LoggerContext.stop(long,
- java.util.concurrent.TimeUnit)</a>.
- (Not used if <tt>shutdownHook</tt> is set to "disable".)</td>
- </tr>
- <tr>
- <td>status</td>
- <td><p>The level of internal Log4j events that should be
logged to the console.
- Valid values for this attribute are "off", "trace", "debug",
"info", "warn", "error", "fatal", and
- "all". Log4j will log details about initialization, rollover
and other internal actions to the status
- logger. Setting <tt>status="trace"</tt> is one of the first
tools available to you if you need to
- troubleshoot log4j.
- </p><p>
- (Alternatively, setting system property
<tt>log4j2.debug</tt> will also print internal Log4j2 logging
- to the console, including internal logging that took place
before the configuration file was found.)
- </p></td>
- </tr>
- <tr>
- <td>strict</td>
- <td>Enables the use of the strict XML format. Not supported in
JSON configurations.</td>
- </tr>
- <tr>
- <td>verbose</td>
- <td>Enables diagnostic information while loading plugins.</td>
- </tr>
- </table>
- <a name="XML"/><h3>Configuration with XML</h3>
- <p>
- Log4j can be configured using two XML flavors; concise and strict.
-
- <h5>Concise Syntax</h5>
-
- The concise format makes configuration very easy as the element
names match the components they represent
- however it cannot be validated with an XML schema. For example,
the ConsoleAppender is configured by
- declaring an XML element named Console under its parent appenders
element. However, element
- and attribute names are not case sensitive. In addition,
attributes can either be specified
- as an XML attribute or as an XML element that has no attributes
and has a text value. So
- </p>
- <pre class="prettyprint"><![CDATA[<PatternLayout
pattern="%m%n"/>]]></pre>
- <p>and</p>
- <pre class="prettyprint"><![CDATA[
-<PatternLayout>
- <Pattern>%m%n</Pattern>
-</PatternLayout>]]></pre>
- <p>
- are equivalent.
- </p>
- <p>
- The file below represents the structure of an XML configuration,
but note
- that the elements in italics below represent the concise element
names that would appear in their place.
- </p>
-
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>;
-<Configuration>
- <Properties>
- <Property name="name1">value</property>
- <Property name="name2" value="value2"/>
- </Properties>
- <]]><i>filter</i> ... <![CDATA[/>
- <Appenders>
- <]]><i>appender</i> ... <![CDATA[>
- <]]><i>filter</i> ... <![CDATA[/>
- </]]><i>appender</i><![CDATA[>
- ...
- </Appenders>
- <Loggers>
- <Logger name="name1">
- <]]><i>filter</i> ... <![CDATA[/>
- </Logger>
- ...
- <Root level="level">
- <AppenderRef ref="name"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>
- See the many examples on this page for sample appender, filter and
logger declarations.
- </p>
- <h5>Strict XML</h5>
- <p>
- In addition to the concise XML format above, Log4j allows
configurations to be specified in a
- more "normal" XML manner that can be validated using an XML
Schema. This is accomplished by
- replacing the friendly element names above with their object type
as shown below. For example,
- instead of the ConsoleAppender being configured using an element
named Console it is instead
- configured as an appender element with a type attribute containing
"Console".
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>;
-<Configuration>
- <Properties>
- <Property name="name1">value</property>
- <Property name="name2" value="value2"/>
- </Properties>
- <Filter type="type" ... />
- <Appenders>
- <Appender type="type" name="name">
- <Filter type="type" ... />
- </Appender>
- ...
- </Appenders>
- <Loggers>
- <Logger name="name1">
- <Filter type="type" ... />
- </Logger>
- ...
- <Root level="level">
- <AppenderRef ref="name"/>
- </Root>
- </Loggers>
-</Configuration>
-]]></pre>
- <p>
- Below is a sample configuration using the strict format.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" strict="true" name="XMLConfigTest">
- <Properties>
- <Property name="filename">target/test.log</Property>
- </Properties>
- <Filter type="ThresholdFilter" level="trace"/>
-
- <Appenders>
- <Appender type="Console" name="STDOUT">
- <Layout type="PatternLayout" pattern="%m MDC%X%n"/>
- <Filters>
- <Filter type="MarkerFilter" marker="FLOW" onMatch="DENY"
onMismatch="NEUTRAL"/>
- <Filter type="MarkerFilter" marker="EXCEPTION" onMatch="DENY"
onMismatch="ACCEPT"/>
- </Filters>
- </Appender>
- <Appender type="Console" name="FLOW">
- <Layout type="PatternLayout" pattern="%C{1}.%M %m %ex%n"/><!-- class and
line number -->
- <Filters>
- <Filter type="MarkerFilter" marker="FLOW" onMatch="ACCEPT"
onMismatch="NEUTRAL"/>
- <Filter type="MarkerFilter" marker="EXCEPTION" onMatch="ACCEPT"
onMismatch="DENY"/>
- </Filters>
- </Appender>
- <Appender type="File" name="File" fileName="${dollar}{filename}">
- <Layout type="PatternLayout">
- <Pattern>%d %p %C{1.} [%t] %m%n</Pattern>
- </Layout>
- </Appender>
- </Appenders>
-
- <Loggers>
- <Logger name="org.apache.logging.log4j.test1" level="debug"
additivity="false">
- <Filter type="ThreadContextMapFilter">
- <KeyValuePair key="test" value="123"/>
- </Filter>
- <AppenderRef ref="STDOUT"/>
- </Logger>
-
- <Logger name="org.apache.logging.log4j.test2" level="debug"
additivity="false">
- <AppenderRef ref="File"/>
- </Logger>
-
- <Root level="trace">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-]]></pre>
- <a name="JSON"/>
- <h4>Configuration with JSON</h4>
- <p>
- In addition to XML, Log4j can be configured using JSON. The JSON
format is very similar to the
- concise XML format. Each key represents the name of a plugin and
the key/value pairs associated
- with it are its attributes. Where a key contains more than a
simple value it itself will be a
- subordinate plugin. In the example below, ThresholdFilter,
Console, and PatternLayout are all
- plugins while the Console plugin will be assigned a value of
STDOUT for its name attribute and the
- ThresholdFilter will be assigned a level of debug.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-{ "configuration": { "status": "error", "name": "RoutingTest",
- "packages": "org.apache.logging.log4j.test",
- "properties": {
- "property": { "name": "filename",
- "value" :
"target/rolling1/rollingtest-${dollar}${dollar}{sd:type}.log" }
- },
- "ThresholdFilter": { "level": "debug" },
- "appenders": {
- "Console": { "name": "STDOUT",
- "PatternLayout": { "pattern": "%m%n" },
- "ThresholdFilter": { "level": "debug" }
- },
- "Routing": { "name": "Routing",
- "Routes": { "pattern": "${dollar}${dollar}{sd:type}",
- "Route": [
- {
- "RollingFile": {
- "name": "Rolling-${dollar}{sd:type}", "fileName":
"${dollar}{filename}",
- "filePattern":
"target/rolling1/test1-${dollar}{sd:type}.%i.log.gz",
- "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"},
- "SizeBasedTriggeringPolicy": { "size": "500" }
- }
- },
- { "AppenderRef": "STDOUT", "key": "Audit"}
- ]
- }
- }
- },
- "loggers": {
- "logger": { "name": "EventLogger", "level": "info", "additivity":
"false",
- "AppenderRef": { "ref": "Routing" }},
- "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }}
- }
- }
-}
-]]></pre>
- <p>
- Note that in the RoutingAppender the Route element has been
declared as an array. This is
- valid because each array element will be a Route component. This
won't work for elements such as
- appenders and filters, where each element has a different name in
the concise format. Appenders and
- filters can be defined as array elements if each appender or
filter declares an attribute named "type"
- that contains the type of the appender. The following example
illustrates this as well as how to
- declare multiple loggers as an array.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-{ "configuration": { "status": "debug", "name": "RoutingTest",
- "packages": "org.apache.logging.log4j.test",
- "properties": {
- "property": { "name": "filename",
- "value" :
"target/rolling1/rollingtest-${dollar}${dollar}{sd:type}.log" }
- },
- "ThresholdFilter": { "level": "debug" },
- "appenders": {
- "appender": [
- { "type": "Console", "name": "STDOUT", "PatternLayout": { "pattern":
"%m%n" }, "ThresholdFilter": { "level": "debug" }},
- { "type": "Routing", "name": "Routing",
- "Routes": { "pattern": "${dollar}${dollar}{sd:type}",
- "Route": [
- {
- "RollingFile": {
- "name": "Rolling-${dollar}{sd:type}", "fileName":
"${dollar}{filename}",
- "filePattern":
"target/rolling1/test1-${dollar}{sd:type}.%i.log.gz",
- "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"},
- "SizeBasedTriggeringPolicy": { "size": "500" }
- }
- },
- { "AppenderRef": "STDOUT", "key": "Audit"}
- ]
- }
- }
- ]
- },
- "loggers": {
- "logger": [
- { "name": "EventLogger", "level": "info", "additivity": "false",
- "AppenderRef": { "ref": "Routing" }},
- { "name": "com.foo.bar", "level": "error", "additivity": "false",
- "AppenderRef": { "ref": "STDOUT" }}
- ],
- "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }}
- }
- }
-}
-]]></pre>
- <p>
- Additional <a href="../runtime-dependencies.html">runtime
dependencies</a> are required for using
- JSON configuration files.
- </p>
- <a name="YAML"/>
- <h4>Configuration with YAML</h4>
- <p>
- Log4j also supports using YAML for configuration files. The
structure follows the same pattern as both the
- XML and YAML configuration formats. For example:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-Configuration:
- status: warn
- name: YAMLConfigTest
- properties:
- property:
- name: filename
- value: target/test-yaml.log
- thresholdFilter:
- level: debug
- appenders:
- Console:
- name: STDOUT
- target: SYSTEM_OUT
- PatternLayout:
- Pattern: "%m%n"
- File:
- name: File
- fileName: ${dollar}{filename}
- PatternLayout:
- Pattern: "%d %p %C{1.} [%t] %m%n"
- Filters:
- ThresholdFilter:
- level: error
-
- Loggers:
- logger:
- -
- name: org.apache.logging.log4j.test1
- level: debug
- additivity: false
- ThreadContextMapFilter:
- KeyValuePair:
- key: test
- value: 123
- AppenderRef:
- ref: STDOUT
- -
- name: org.apache.logging.log4j.test2
- level: debug
- additivity: false
- AppenderRef:
- ref: File
- Root:
- level: error
- AppenderRef:
- ref: STDOUT
- ]]></pre>
- <p>
- Additional <a href="../runtime-dependencies.html">runtime
dependencies</a> are required for using
- YAML configuration files.
- </p>
- <a name="Properties"/>
- <h4>Configuration with Properties</h4>
- <p>
- As of version 2.4, Log4j now supports configuration via
properties files. Note that the property
- syntax is NOT the same as the syntax used in Log4j 1. Like the
XML and JSON configurations, properties
- configurations define the configuration in terms of plugins and
attributes to the plugins.
- </p>
- <p>
- Prior to version 2.6,
- the properties configuration requires that you list the
identifiers of the appenders, filters and loggers,
- in a comma separated list in properties with those names. Each
of those components will then be expected
- to be defined in sets of properties that begin with
<i>component.<.identifier>.</i>. The identifier does not
- have to match the name of the component being defined but must
uniquely identify all the attributes and
- subcomponents that are part of the component. If the list of
identifiers is not present the
- identifier must not contain a '.'. Each individual component
MUST have a "type" attribute
- specified that identifies the component's Plugin type.
- </p>
- <p>
- As of version 2.6, this list of identifiers is no longer
required as names are inferred upon first usage,
- however if you wish to use more complex identifies you must
still use the list. If the list is present
- it will be used.
- </p>
- <p>
- Unlike the base components, when creating subcomponents you
cannot specify an element containing a list of
- identifiers. Instead, you must define the wrapper element with
its type as is shown in the policies
- definition in the rolling file appender below. You then define
each of the subcomponents below that
- wrapper element, as the TimeBasedTriggeringPolicy and
SizeBasedTriggeringPolicy are defined below.
- </p>
- <p>
- As of version 2.17.2,
- <tt>rootLogger</tt> and <tt>logger.<var>key</var></tt>
properties can be specified to set the
- level and zero or more appender refs to create for that logger.
The level and appender refs are
- separated by comma <tt>,</tt> characters with optional
whitespace surrounding the comma. The
- following example demonstrates how the shorthand is expanded
when reading properties configurations.
- </p>
- <pre class="prettyprint linenums">
-appender.stdout.type = Console
-# ... other appender properties
-appender.file.type = File
-# ... other appender properties
-logger.app = INFO, stdout, file
-logger.app.name = com.example.app
-
-# is equivalent to:
-# appender.stdout.type = Console
-# appender.stdout.name = stdout
-# ...
-appender.file.type = File
-appender.file.name = file
-# ...
-logger.app.name = com.example.app
-logger.app.level = INFO
-logger.app.appenderRef.$1.ref = stdout
-logger.app.appenderRef.$2.ref = file
- </pre>
- <p>
- Properties configuration files support the advertiser,
monitorInterval, name, packages, shutdownHook,
- shutdownTimeout, status, verbose, and dest attributes. See <a
href="#ConfigurationSyntax">Configuration Syntax</a>
- for the definitions of these attributes.
- </p>
- <pre class="prettyprint linenums">
-status = error
-dest = err
-name = PropertiesConfig
-
-property.filename = target/rolling/rollingtest.log
-
-filter.threshold.type = ThresholdFilter
-filter.threshold.level = debug
-
-appender.console.type = Console
-appender.console.name = STDOUT
-appender.console.layout.type = PatternLayout
-appender.console.layout.pattern = %m%n
-appender.console.filter.threshold.type = ThresholdFilter
-appender.console.filter.threshold.level = error
-
-appender.rolling.type = RollingFile
-appender.rolling.name = RollingFile
-appender.rolling.fileName = ${dollar}{filename}
-appender.rolling.filePattern =
target/rolling2/test1-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz
-appender.rolling.layout.type = PatternLayout
-appender.rolling.layout.pattern = %d %p %C{1.} [%t] %m%n
-appender.rolling.policies.type = Policies
-appender.rolling.policies.time.type = TimeBasedTriggeringPolicy
-appender.rolling.policies.time.interval = 2
-appender.rolling.policies.time.modulate = true
-appender.rolling.policies.size.type = SizeBasedTriggeringPolicy
-appender.rolling.policies.size.size=100MB
-appender.rolling.strategy.type = DefaultRolloverStrategy
-appender.rolling.strategy.max = 5
-
-logger.rolling = debug, RollingFile
-logger.rolling.name = com.example.my.app
-logger.rolling.additivity = false
-
-rootLogger = info, STDOUT
-
-# or using a grouping element:
-# rootLogger.level = info
-# rootLogger.appenderRef.stdout.ref = STDOUT
- </pre>
- <a name="Loggers"/>
- <h4>Configuring Loggers</h4>
- <p>
- An understanding of how loggers work in Log4j is critical before
trying to configure them.
- Please reference the Log4j <a
href="./architecture.html">architecture</a> if more information is
- required. Trying to configure Log4j without understanding those
concepts will lead to frustration.
- </p>
- <p>
- A LoggerConfig is configured using the <code>logger</code>
element. The <code>logger</code> element
- must have a name attribute specified, will usually have a level
attribute specified and may
- also have an additivity attribute specified. The level may be
configured with one of TRACE,
- DEBUG, INFO, WARN, ERROR, ALL or OFF. If no level is specified it
will default to ERROR. The
- additivity attribute may be assigned a value of true or false. If
the attribute is omitted
- the default value of true will be used.
- </p>
- <p>
- Capturing location information (the class name, file name, method
name, and line number of the caller)
- can be slow. Log4j tries to optimize this by reducing the size of
the stack that must be traversed
- to find the caller of the logging method. It does this by
determining if any component that might
- be accessed requires location information. This can cause
performance issues if a logger is configured
- at a level like trace or debug with the expectation that most logs
will be filtered on an Appender
- reference or Appender as Log4j will calculate the location
information even though the log event
- is going to be discarded. To disable this behavior the
<code>includeLocation</code> attribute
- can be set to false on the LoggerConfig. This will cause Log4j to
defer calculating the location
- information until absolutely necessary.
- </p>
- <p>
- A LoggerConfig (including the root LoggerConfig) can be configured
with properties that will be added
- to the properties copied from the ThreadContextMap. These
properties can be referenced from Appenders,
- Filters, Layouts, etc just as if they were part of the
ThreadContext Map. The properties can contain
- variables that will be resolved either when the configuration is
parsed or dynamically when each
- event is logged. See <a href="#PropertySubstitution">Property
Substitution</a> for more information on
- using variables.
- </p>
- <p>
- The LoggerConfig may also be configured with one or more
AppenderRef elements. Each appender
- referenced will become associated with the specified LoggerConfig.
If multiple appenders
- are configured on the LoggerConfig each of them be called when
processing logging events.
- </p>
- <p>
- <b><em>Every configuration must have a root logger</em></b>. If
one is not configured the default root LoggerConfig,
- which has a level of ERROR and has a Console appender attached,
will be used. The main differences
- between the root logger and other loggers are
- </p>
- <ol>
- <li>The root logger does not have a name attribute.</li>
- <li>The root logger does not support the additivity attribute
since it has no parent.</li>
- </ol>
- <a name="Appenders"/>
- <h4>Configuring Appenders</h4>
- <p>
- An appender is configured either using the specific appender
plugin's name or with an appender
- element and the type attribute containing the appender plugin's
name. In addition each appender
- must have a name attribute specified with a value that is unique
within the set of appenders.
- The name will be used by loggers to reference the appender as
described in the previous section.
- </p>
- <p>
- Most appenders also support a layout to be configured (which again
may be specified either
- using the specific Layout plugin's name as the element or with
"layout" as the element name
- along with a type attribute that contains the layout plugin's
name. The various appenders
- will contain other attributes or elements that are required for
them to function properly.
- </p>
- <a name="Filters"/>
- <h4>Configuring Filters</h4>
- <p>
- Log4j allows a filter to be specified in any of 4 places:
- </p>
- <ol>
- <li>At the same level as the appenders, loggers and properties
elements. These filters can accept
- or reject events before they have been passed to a
LoggerConfig.</li>
- <li>In a logger element. These filters can accept or reject events
for specific loggers.</li>
- <li>In an appender element. These filters can prevent or cause
events to be processed by
- the appender.</li>
- <li>In an appender reference element. These filters are used to
determine if a Logger should route
- the event to an appender.</li>
- </ol>
- <p>
- Although only a single <code>filter</code> element can be
configured, that element may be the
- <code>filters</code> element which represents the CompositeFilter.
The <code>filters</code> element
- allows any number of <code>filter</code> elements to be configured
within it. The following example
- shows how multiple filters can be configured on the
ConsoleAppender.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="XMLConfigTest">
- <Properties>
- <Property name="filename">target/test.log</Property>
- </Properties>
- <ThresholdFilter level="trace"/>
-
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m MDC%X%n"/>
- </Console>
- <Console name="FLOW">
- <!-- this pattern outputs class name and line number -->
- <PatternLayout pattern="%C{1}.%M %m %ex%n"/>
- <filters>
- <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/>
- <MarkerFilter marker="EXCEPTION" onMatch="ACCEPT" onMismatch="DENY"/>
- </filters>
- </Console>
- <File name="File" fileName="${dollar}{filename}">
- <PatternLayout>
- <pattern>%d %p %C{1.} [%t] %m%n</pattern>
- </PatternLayout>
- </File>
- </Appenders>
-
- <Loggers>
- <Logger name="org.apache.logging.log4j.test1" level="debug"
additivity="false">
- <ThreadContextMapFilter>
- <KeyValuePair key="test" value="123"/>
- </ThreadContextMapFilter>
- <AppenderRef ref="STDOUT"/>
- </Logger>
-
- <Logger name="org.apache.logging.log4j.test2" level="debug"
additivity="false">
- <Property name="user">${dollar}{sys:user.name}</Property>
- <AppenderRef ref="File">
- <ThreadContextMapFilter>
- <KeyValuePair key="test" value="123"/>
- </ThreadContextMapFilter>
- </AppenderRef>
- <AppenderRef ref="STDOUT" level="error"/>
- </Logger>
-
- <Root level="trace">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-]]></pre>
- </subsection>
- <a name="PropertySubstitution"/>
- <subsection name="Property Substitution">
- <p>
- Log4j 2 supports the ability to specify tokens in the
configuration as references to properties defined
- elsewhere. Some of these properties will be resolved when the
configuration file is interpreted while
- others may be passed to components where they will be evaluated at
runtime. To accomplish this, Log4j
- uses variations of <a
href="https://commons.apache.org/proper/commons-lang/";>Apache Commons Lang</a>'s
- <a class="javadoc"
href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrSubstitutor.html">StrSubstitutor</a>
- and <a class="javadoc"
href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html">StrLookup</a>
- classes. In a manner similar to Ant or Maven, this allows
variables declared as <code>${dollar}{name}</code>
- to be resolved using properties declared in the configuration
itself. For example, the following example
- shows the filename for the rolling file appender being declared as
a property.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="RoutingTest">
- <Properties>
- <Property
name="filename">target/rolling1/rollingtest-${dollar}${dollar}{sd:type}.log</Property>
- </Properties>
- <ThresholdFilter level="debug"/>
-
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m%n"/>
- <ThresholdFilter level="debug"/>
- </Console>
- <Routing name="Routing">
- <Routes pattern="${dollar}${dollar}{sd:type}">
- <Route>
- <RollingFile name="Rolling-${dollar}{sd:type}"
fileName="${dollar}{filename}"
-
filePattern="target/rolling1/test1-${dollar}{sd:type}.%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <SizeBasedTriggeringPolicy size="500" />
- </RollingFile>
- </Route>
- <Route ref="STDOUT" key="Audit"/>
- </Routes>
- </Routing>
- </Appenders>
-
- <Loggers>
- <Logger name="EventLogger" level="info" additivity="false">
- <AppenderRef ref="Routing"/>
- </Logger>
-
- <Root level="error">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-]]></pre>
- <p>
- While this is useful, there are many more places properties can
originate from. To accommodate this,
- Log4j also supports the syntax <code>${dollar}{prefix:name}</code>
where the prefix identifies tells Log4j
- that variable name should be evaluated in a specific context.
- See the <a href="lookups.html">Lookups</a> manual page for more
details.
- The contexts that are built in to Log4j are:
- </p>
- <table>
- <tr>
- <th>Prefix</th>
- <th>Context</th>
- </tr>
- <tr>
- <td>bundle</td>
- <td>
- Resource bundle. The format is
<code>${dollar}{bundle:BundleName:BundleKey}</code>.
- The bundle name follows package naming conventions, for
example:
- <code>${dollar}{bundle:com.domain.Messages:MyKey}</code>.
- </td>
- </tr>
- <tr>
- <td>ctx</td>
- <td>
- Retrieves a previously stored valued from the Thread Context
Map (MDC).
- The format is <code>${dollar}{ctx:some.key}</code>.
- </td>
- </tr>
- <tr>
- <td>date</td>
- <td>
- Inserts the current date and/or time using the specified
format pattern from the
- <a
href="https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html";>SimpleDateFormat</a>
class.
- If no pattern is specified, then the default pattern is used.
- The formats are <code>${dollar}{date:some.pattern}</code>
and <code>${dollar}{date:}</code>.
- </td>
- </tr>
- <tr>
- <td>docker</td>
- <td>
- Returns attributes from the Docker container the application
is running in.
- The format is <code>${dollar}{docker:some.attribute}</code>.
- See <a href="../log4j-docker.html">Docker documentation</a>
for requirements and a list of available attributes.
- </td>
- </tr>
- <tr>
- <td>env</td>
- <td>
- Retrieves values from system environment variables or
default value if the environment variable is not set.
- The formats are <code>${dollar}{env:ENV_NAME}</code> and
<code>${dollar}{env:ENV_NAME:-default_value}</code>.
- </td>
- </tr>
- <tr>
- <td>event</td>
- <td>
- Retrieves values from fields within the log event. The
format is <code>${dollar}{event:some.field}</code>.
- See the <a href="lookups.html#eventlookup">Lookups</a>
manual page for a list of available fields.
- </td>
- </tr>
- <tr>
- <td>java</td>
- <td>
- Retrieves information about the Java environment the
application is running in.
- The format is <code>${dollar}{java:some.property}</code>.
- See the <a href="lookups.html#java-lookup">Lookups</a>
manual page for a list of available properties.
- </td>
- </tr>
- <tr>
- <td>jndi</td>
- <td>
- A value set in the default JNDI Context. (Requires system
property <code>log4j2.enableJndiLookup</code> to be set to <code>true</code>.)
- The format is
<code>${dollar}{jndi:logging/context-name}</code>.
- </td>
- </tr>
- <tr>
- <td>jvmrunargs</td>
- <td>
- A JVM input argument accessed through JMX, but not a main
argument;
- see <a class="javadoc"
href="https://docs.oracle.com/javase/6/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--";>RuntimeMXBean.getInputArguments()</a>.
- The format is <code>${dollar}{jvmrunargs:argument}</code>.
- Not available on Android or Google App Engine.
- </td>
- </tr>
- <tr>
- <td>k8s</td>
- <td>
- Returns attributes from the Kubernetes environment the
application is running in.
- The format is <code>${dollar}{k8s:some.attribute}</code>.
- See the <a href="lookups.html#kubernetes-lookup">Lookups</a>
manual page for a list of available attributes.
- </td>
- </tr>
- <tr>
- <td>log4j</td>
- <td>Log4j configuration properties. The expressions
<code>${dollar}{log4j:configLocation}</code> and
- <code>${dollar}{log4j:configParentLocation}</code>
respectively provide the absolute path
- to the log4j configuration file and its parent folder.</td>
- </tr>
- <tr>
- <td>lower</td>
- <td>
- Converts the passed in argument to lower case (usually
used with nested lookups).
- The format is <code>${dollar}{lower:argument}</code>.
- </td>
- </tr>
- <tr>
- <td>main</td>
- <td>
- A value set with <a class="javadoc"
href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/MapLookup.html#setMainArguments-java.lang.String:A-">MapLookup.setMainArguments(String[])</a>.
- The formats are <code>${dollar}{main:index}</code> for a
0-based index into the argument list and
<code>${dollar}{main:argument.name}</code> for name from the argument list.
- </td>
- </tr>
- <tr>
- <td>map</td>
- <td>
- Provides a base for Properties in the configuration file
or retrieves a value from a MapMessage.
- The format is <code>${dollar}{map:type}</code>.
- See the <a href="lookups.html#map-lookup">Lookups</a>
manual page for further details.
- </td>
- </tr>
- <tr>
- <td>marker</td>
- <td>
- Allows use of markers in configurations.
- The formats are <code>${dollar}{marker:}</code> and
<code>${dollar}{marker:some.name}</code>.
- See the <a href="lookups.html#marker-lookup">Lookups</a>
manual page for further details.
- </td>
- </tr>
- <tr>
- <td>sd</td>
- <td>A value from a StructuredDataMessage. The key "id" will
return the name of the StructuredDataId
- without the enterprise number. The key "type" will return
the message type. Other keys will
- retrieve individual elements from the Map.</td>
- </tr>
- <tr>
- <td>spring</td>
- <td>
- Returns values of Spring properties from the Spring
configuration.
- The format is <code>${dollar}{spring:some.property}</code>.
- See the <a
href="lookups.html#spring-boot-lookup">Lookups</a> manual page for requirements
and details.
- </td>
- </tr>
- <tr>
- <td>sys</td>
- <td>
- Retrieves values from system properties.
- The formats are <code>${dollar}{sys:some.property}</code>
and <code>${dollar}{sys:some.property:-default_value}</code>.
- </td>
- </tr>
- <tr>
- <td>upper</td>
- <td>
- Converts the passed in argument to upper case (usually
used with nested lookups).
- The format is <code>${dollar}{upper:argument}</code>.
- </td>
- </tr>
- <tr>
- <td>web</td>
- <td>
- Returns values of variables associated with the Servlet
Context.
- The format is <code>${dollar}{spring:some.key}</code>.
- See the <a href="lookups.html#web-lookup">Lookups</a> manual
page for a list of available keys.
- </td>
- </tr>
- </table>
- <a name="DefaultProperties"/><h3>Default Properties</h3><p>
- A default property map can be declared in the configuration file by
placing a Properties
- element directly after the Configuration element and before any
Loggers, Filters,
- Appenders, etc. are declared. If the value cannot be located in the
specified lookup the
- value in the default property map will be used. The default map is
pre-populated with a value
- for "hostName" that is the current system's host name or IP address
and
- the "contextName" with is the value of the current logging context.
See many places
- a Properties element is used in this section for examples.
- </p>
- <p>
- Default properties may also be specified in the Lookup by using
the syntax <code>${dollar}{lookupName:key:-defaultValue}</code>.
- In some cases the key might contain a leading '-'. When this is
the case an escape character must be
- included, such as
<code>${dollar}{main:\--file:-app.properties}</code>. This would use the
- <code>MainMapLookup</code> for a key named <code>--file</code>. If
the key is not found then
- <code>app.properties</code> would be used as the default value.
- </p>
- </subsection>
- <a name="EnablingMessagePatternLookups"/>
- <subsection name="Enabling Message Pattern Lookups">
- <p>
- A message is processed (by default) without using lookups, for
example if you defined
- <code> <Property name="foo.bar">FOO_BAR </Property></code>,
then <code>logger.info("${foo.bar}")</code>
- will output <code>${dollar}{foo.bar}</code> instead of
<code>FOO_BAR</code>. You could enable message pattern
- lookups by defining message pattern using %m{lookups}.
- </p>
- </subsection>
- <a name="RuntimeLookup"/>
- <subsection name="Lookup Variables with Multiple Leading '$'
Characters">
- <p>
- An interesting feature of StrLookup processing is that when a
variable reference is declared with
- multiple leading '$' characters each time the variable is resolved
the leading '$' is simply removed.
- In the previous example the "Routes" element is capable of
resolving the variable at runtime. To allow
- this the prefix value is specified as a variable with two leading
'$' characters. When the configuration
- file is first processed the first '$' character is simply removed.
Thus, when the Routes element is evaluated
- at runtime it is the variable declaration "${dollar}{sd:type}"
which causes the event to be inspected for a
- StructuredDataMessage and if one is present the value of its type
attribute to be used as the routing key.
- Not all elements support resolving variables at runtime.
Components that do will specifically call that
- out in their documentation.
- </p>
- <p>
- If no value is found for the key in the Lookup associated with the
prefix then the value associated with
- the key in the properties declaration in the configuration file
will be used. If no value is found
- the variable declaration will be returned as the value. Default
values may be declared in the configuration
- by doing:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration>
- <Properties>
- <Property name="type">Audit</property>
- </Properties>
- ...
-</Configuration>
-]]></pre>
- <p>
- <i>As a footnote, it is worth pointing out that the variables in
the RollingFile appender declaration
- will also not be evaluated when the configuration is processed.
This is simply because the resolution
- of the whole RollingFile element is deferred until a match occurs.
- See <a href="appenders.html#RoutingAppender">RoutingAppender</a>
for more information.</i>
- </p>
- </subsection>
- <a name="Scripts"/>
- <subsection name="Scripts">
- <p>
- Log4j provides support for <a
href="https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/";>JSR
223</a>
- scripting languages to be used in some of its components. Any
language that provides support for the JSR
- 223 scripting engine may be used. A list of the languages and
bindings for them can be found at the
- <a
href="https://java.net/projects/scripting/sources/svn/show/trunk/engines";>Scripting
Engine</a> web site.
- However, some of the languages listed there, such as JavaScript,
Groovy and Beanshell, directly support the
- JSR 223 scripting framework and only require that the jars for
that language be installed.
- </p>
- <p>As of Log4j 2.17.2 the languages to be supported must be
specified as a comma separated list in the
- <code>log4j2.Script.enableLanguages</code> system property.</p>
- <p>
- The components that support using scripts do so by allowing a
<script>, <scriptFile>, or
- <scriptRef> element to be configured on
- them. The script element contains a name for the script, the
language of the script, and the script text.
- The scriptFile element contains the name of the script, its
location, its language, its charset, and
- whether the file should be watched for changes. The scriptRef
element contains the name of the
- script that is defined in the <scripts> configuration
element.
- The name of the script is used to store the script, along with its
ScriptEngine, so it can quickly be
- located each time the script needs to be run. While the name is
not required, providing it will help in
- debugging problems when the script is running. The language must
be provided on the script element and must
- specify one of the language names that appear in the Configuration
status log as described in the next
- section. If the language is not specified on the scriptFile
element the language will be determined by
- the file extension of the script path. If file monitoring is
requested it will only be enabled if
- a non-zero monitorInterval is specified on the configuration
element. That interval will be used to
- check for changes in the file.
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="RoutingTest">
- <Scripts>
- <Script name="selector" language="javascript"><![CDATA[
- var result;
- if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
- result = "NoLocation";
- } else if (logEvent.getMarker() != null &&
logEvent.getMarker().isInstanceOf("FLOW")) {
- result = "Flow";
- }
- result;
- ]]]]><![CDATA[></Script>
- <ScriptFile name="groovy.filter" path="scripts/filter.groovy"/>
- </Scripts>
-
- <Appenders>
- <Console name="STDOUT">
- <ScriptPatternSelector defaultPattern="%d %p %m%n">
- <ScriptRef ref="selector"/>
- <PatternMatch key="NoLocation" pattern="[%-5level] %c{1.} %msg%n"/>
- <PatternMatch key="Flow" pattern="[%-5level] %c{1.} ======
%C{1.}.%M:%L %msg ======%n"/>
- </ScriptPatternSelector>
- <PatternLayout pattern="%m%n"/>
- </Console>
- </Appenders>
-
- <Loggers>
- <Logger name="EventLogger" level="info" additivity="false">
- <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
- <Script name="GroovyFilter" language="groovy"><![CDATA[
- if (logEvent.getMarker() != null &&
logEvent.getMarker().isInstanceOf("FLOW")) {
- return true;
- } else if (logEvent.getContextMap().containsKey("UserId")) {
- return true;
- }
- return false;
- ]]]]><![CDATA[>
- </Script>
- </ScriptFilter>
- <AppenderRef ref="STDOUT"/>
- </Logger>
-
- <Root level="error">
- <ScriptFilter onMatch="ACCEPT" onMisMatch="DENY">
- <ScriptRef ref="groovy.filter"/>
- </ScriptFilter>
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>]]>
- </pre>
- <p>
- If the status attribute on the Configuration element is set to
DEBUG the list of script engines currently
- installed and their attributes will be listed. Although some
engines may say they are not thread safe,
- Log4j takes steps to insure that the scripts will run in a
thread-safe manner if the engine advertises
- that it is not thread safe.
- </p>
- <pre>
-2015-09-27 16:13:22,925 main DEBUG Installed script engines
-2015-09-27 16:13:22,963 main DEBUG AppleScriptEngine Version: 1.1, Language:
AppleScript, Threading: Not Thread Safe,
- Compile: false, Names: {AppleScriptEngine, AppleScript, OSA}
-2015-09-27 16:13:22,983 main DEBUG Groovy Scripting Engine Version: 2.0,
Language: Groovy, Threading: MULTITHREADED,
- Compile: true, Names: {groovy, Groovy}
-2015-09-27 16:13:23,030 main DEBUG BeanShell Engine Version: 1.0, Language:
BeanShell, Threading: MULTITHREADED,
- Compile: true, Names: {beanshell, bsh, java}
-2015-09-27 16:13:23,039 main DEBUG Mozilla Rhino Version: 1.7 release 3
PRERELEASE, Language: ECMAScript, Threading: MULTITHREADED,
- Compile: true, Names: {js, rhino, JavaScript, javascript,
ECMAScript, ecmascript}
- </pre>
- <p>
- When the scripts are executed they will be provided with a set of
variables that should allow them to
- accomplish whatever task they are expected to perform. See the
documentation for the individual components
- for the list of variables that are available to the script.
- </p>
- <p>
- The components that support scripting expect a return value to be
passed back to the calling Java code.
- This is not a problem for several of the scripting languages, but
Javascript does not allow a
- return statement unless it is within a function. However,
Javascript will return the value of the last
- statement executed in the script. As a consequence, code such as
that shown below will result in the
- desired behavior.
- </p>
- <pre><![CDATA[
- var result;
- if (logEvent.getLoggerName().equals("JavascriptNoLocation")) {
- result = "NoLocation";
- } else if (logEvent.getMarker() != null &&
logEvent.getMarker().isInstanceOf("FLOW")) {
- result = "Flow";
- }
- result;
- ]]></pre>
- <h4>A special note on Beanshell</h4>
- <p>
- JSR 223 scripting engines are supposed to identify that they
support the Compilable interface if they
- support compiling their scripts. Beanshell does this. However,
whenever the compile method is called it
- throws an Error (not an Exception). Log4j catches this but will
log the warning shown below for each
- Beanshell script when it tries to compile them. All Beanshell
scripts will then be interpreted on each
- execution.
- </p>
- <pre><![CDATA[
-2015-09-27 16:13:23,095 main DEBUG Script BeanShellSelector is compilable
-2015-09-27 16:13:23,096 main WARN Error compiling script java.lang.Error:
unimplemented
- at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:175)
- at bsh.engine.BshScriptEngine.compile(BshScriptEngine.java:154)
- at
org.apache.logging.log4j.core.script.ScriptManager$MainScriptRunner.<init>(ScriptManager.java:125)
- at
org.apache.logging.log4j.core.script.ScriptManager.addScript(ScriptManager.java:94)
- ]]></pre>
- </subsection>
- <a name="XInclude"/>
- <subsection name="XInclude">
- <p>
- XML configuration files can include other files with <a
href="https://www.xml.com/lpt/a/1009";>XInclude</a>.
- Here is an example log4j2.xml file that includes two other files:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<configuration xmlns:xi="http://www.w3.org/2001/XInclude";
- status="warn" name="XIncludeDemo">
- <properties>
- <property name="filename">xinclude-demo.log</property>
- </properties>
- <ThresholdFilter level="debug"/>
- <xi:include href="log4j-xinclude-appenders.xml" />
- <xi:include href="log4j-xinclude-loggers.xml" />
-</configuration>
-]]></pre>
- <p>log4j-xinclude-appenders.xml:</p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m%n" />
- </Console>
- <File name="File" fileName="${dollar}{filename}" bufferedIO="true"
immediateFlush="true">
- <PatternLayout>
- <pattern>%d %p %C{1.} [%t] %m%n</pattern>
- </PatternLayout>
- </File>
-</appenders>
-]]></pre>
- <p>log4j-xinclude-loggers.xml:</p>
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<loggers>
- <logger name="org.apache.logging.log4j.test1" level="debug"
additivity="false">
- <ThreadContextMapFilter>
- <KeyValuePair key="test" value="123" />
- </ThreadContextMapFilter>
- <AppenderRef ref="STDOUT" />
- </logger>
-
- <logger name="org.apache.logging.log4j.test2" level="debug"
additivity="false">
- <AppenderRef ref="File" />
- </logger>
-
- <root level="error">
- <AppenderRef ref="STDOUT" />
- </root>
-</loggers>
-]]></pre>
- </subsection>
- <a name="CompositeConfiguration"/>
- <subsection name="Composite Configuration">
- <p>
- Log4j allows multiple configuration files to be used by
specifying them as a list of comma separated
- file paths on log4j.configurationFile or, when using URLs, by
adding secondary configuration
- locations as query parameters named "override". The merge logic
can be controlled by specifying a class
- that implements the MergeStrategy interface on the
log4j.mergeStrategy property. The default
- merge strategy will merge the files using the following rules:
- <ol>
- <li>The global configuration attributes are aggregated with
those in later configurations replacing
- those in previous configurations, with the exceptions:
- <ul>
- <li>the highest status level will be used</li>
- <li>the lowest monitorInterval greater than 0 will be
used</li>
- <li>packages are joined with comma</li>
- </ul>
- </li>
- <li>Properties from all configurations are aggregated.
Duplicate properties replace those in previous
- configurations.</li>
- <li>Filters are aggregated under a CompositeFilter if more
than one Filter is defined. Since Filters
- are not named duplicates may be present.</li>
- <li>Scripts and ScriptFile references are aggregated.
Duplicate definitions replace those in previous
- configurations.</li>
- <li>Appenders are aggregated. Appenders with the same name are
replaced by those in later
- configurations, including all of the Appender's
subcomponents.</li>
- <li>Loggers are all aggregated. Logger attributes are
individually merged with duplicates being
- replaced by those in later configurations. Appender
references on a Logger are aggregated with
- duplicates being replaced by those in later configurations.
Filters on a Logger are aggregated
- under a CompositeFilter if more than one Filter is defined.
Since Filters are not named
- duplicates may be present. Filters under Appender references
included or discarded depending on
- whether their parent Appender reference is kept or
discarded.</li>
- </ol>
- </p>
- </subsection>
- <a name="StatusMessages"/>
- <subsection name="Status Messages">
- <table>
- <tr>
- <td>
- <b>Troubleshooting tip for the impatient:</b>
- <p>From log4j-2.9 onward, log4j2 will print all internal logging
to the console if system property
- <tt>log4j2.debug</tt> is either defined empty or its value
equals to <tt>true</tt> (ignoring case).</p>
- <p>Prior to log4j-2.9, there are two places where internal
logging can be controlled:</p>
- <ul>
- <li>Before a configuration is found, status logger level can be
controlled with system
- property
<code>org.apache.logging.log4j.simplelog.StatusLogger.level</code>.</li>
- <li>After a configuration is found, status logger level can be
controlled in the configuration
- file with the "status" attribute, for example:
<code><Configuration status="trace"></code>.</li>
- </ul>
- </td>
- </tr>
- </table>
- <p>
- Just as it is desirable to be able to diagnose problems in
applications, it is frequently necessary
- to be able to diagnose problems in the logging configuration or in
the configured components. Since
- logging has not been configured, "normal" logging cannot be used
during initialization. In addition,
- normal logging within appenders could create infinite recursion
which Log4j will detect and cause
- the recursive events to be ignored. To accommodate this need, the
Log4j 2 API includes a
- <a class="javadoc"
href="../log4j-api/apidocs/org/apache/logging/log4j/status/StatusLogger.html">StatusLogger</a>.
- Components declare an instance of the StatusLogger similar to:
- </p>
- <pre class="prettyprint">protected final static Logger logger =
StatusLogger.getLogger();</pre>
- <p>
- Since StatusLogger implements the Log4j 2 API's Logger interface,
all the normal Logger methods may
- be used.
- </p>
- <p>
- When configuring Log4j it is sometimes necessary to view the
generated status events. This can be
- accomplished by adding the status attribute to the configuration
element or a default value can be
- provided by setting the "Log4jDefaultStatusLevel" system property.
Valid values of the status attribute are
- "trace", "debug", "info", "warn", "error" and "fatal". The
following
- configuration has the status attribute set to debug.
- </p>
-
- <pre class="prettyprint linenums"><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="debug" name="RoutingTest">
- <Properties>
- <Property
name="filename">target/rolling1/rollingtest-${dollar}${dollar}{sd:type}.log</Property>
- </Properties>
- <ThresholdFilter level="debug"/>
-
- <Appenders>
- <Console name="STDOUT">
- <PatternLayout pattern="%m%n"/>
- <ThresholdFilter level="debug"/>
- </Console>
- <Routing name="Routing">
- <Routes pattern="${dollar}${dollar}{sd:type}">
- <Route>
- <RollingFile name="Rolling-${dollar}{sd:type}"
fileName="${dollar}{filename}"
-
filePattern="target/rolling1/test1-${dollar}{sd:type}.%i.log.gz">
- <PatternLayout>
- <pattern>%d %p %c{1.} [%t] %m%n</pattern>
- </PatternLayout>
- <SizeBasedTriggeringPolicy size="500" />
- </RollingFile>
- </Route>
- <Route ref="STDOUT" key="Audit"/>
- </Routes>
- </Routing>
- </Appenders>
-
- <Loggers>
- <Logger name="EventLogger" level="info" additivity="false">
- <AppenderRef ref="Routing"/>
- </Logger>
-
- <Root level="error">
- <AppenderRef ref="STDOUT"/>
- </Root>
- </Loggers>
-
-</Configuration>
-]]></pre>
- <p>
- During startup this configuration produces:
- </p>
-#if ($isPDF)
- <pre>
-2011-11-23 17:08:00,769 DEBUG Generated plugins in 0.003374000 seconds
-2011-11-23 17:08:00,789 DEBUG Calling createProperty on class
org.apache.logging.log4j.core.
- config.Property for element property with params(name="filename",
- value="target/rolling1/rollingtest-${dollar}{sd:type}.log")
-2011-11-23 17:08:00,792 DEBUG Calling configureSubstitutor on class
org.apache.logging.log4j.
- core.config.plugins.PropertiesPlugin for element properties with
-
params(properties={filename=target/rolling1/rollingtest-${dollar}{sd:type}.log})
-2011-11-23 17:08:00,794 DEBUG Generated plugins in 0.001362000 seconds
-2011-11-23 17:08:00,797 DEBUG Calling createFilter on class
org.apache.logging.log4j.core.
- filter.ThresholdFilter for element ThresholdFilter with
params(level="debug",
- onMatch="null", onMismatch="null")
-2011-11-23 17:08:00,800 DEBUG Calling createLayout on class
org.apache.logging.log4j.core.
- layout.PatternLayout for element PatternLayout with
params(pattern="%m%n",
- Configuration(RoutingTest), null, charset="null")
-2011-11-23 17:08:00,802 DEBUG Generated plugins in 0.001349000 seconds
-2011-11-23 17:08:00,804 DEBUG Calling createAppender on class
org.apache.logging.log4j.core.
- appender.ConsoleAppender for element Console with
params(PatternLayout(%m%n), null,
- target="null", name="STDOUT", ignoreExceptions="null")
-2011-11-23 17:08:00,804 DEBUG Calling createFilter on class
org.apache.logging.log4j.core.
- filter.ThresholdFilter for element ThresholdFilter with
params(level="debug",
- onMatch="null", onMismatch="null")
-2011-11-23 17:08:00,813 DEBUG Calling createRoute on class
org.apache.logging.log4j.core.appender.
- routing.Route for element Route with params(AppenderRef="null",
key="null", Node=Route)
-2011-11-23 17:08:00,823 DEBUG Calling createRoute on class
org.apache.logging.log4j.core.appender.
- routing.Route for element Route with params(AppenderRef="STDOUT",
key="Audit", Node=Route)
-2011-11-23 17:08:00,825 DEBUG Calling createRoutes on class
org.apache.logging.log4j.core.appender.
- routing.Routes for element Routes with
params(pattern="${dollar}{sd:type}",
- routes={Route(type=dynamic default), Route(type=static Reference=STDOUT
key='Audit'))})
-2011-11-23 17:08:00,827 DEBUG Calling createAppender on class
org.apache.logging.log4j.core.appender.
- routing.RoutingAppender for element Routing with params(name="Routing",
- ignoreExceptions="null", Routes({Route(type=dynamic
default),Route(type=static
- Reference=STDOUT key='Audit')}), Configuration(RoutingTest), null, null)
-2011-11-23 17:08:00,827 DEBUG Calling createAppenders on class
org.apache.logging.log4j.core.config.
- plugins.AppendersPlugin for element appenders with
params(appenders={STDOUT, Routing})
-2011-11-23 17:08:00,828 DEBUG Calling createAppenderRef on class
org.apache.logging.log4j.core.
- config.plugins.AppenderRefPlugin for element AppenderRef with
params(ref="Routing")
-2011-11-23 17:08:00,829 DEBUG Calling createLogger on class
org.apache.logging.log4j.core.config.
- LoggerConfig for element logger with params(additivity="false",
level="info", name="EventLogger",
- AppenderRef={Routing}, null)
-2011-11-23 17:08:00,830 DEBUG Calling createAppenderRef on class
org.apache.logging.log4j.core.
- config.plugins.AppenderRefPlugin for element AppenderRef with
params(ref="STDOUT")</pre>
- <pre>
-2011-11-23 17:08:00,831 DEBUG Calling createLogger on class
org.apache.logging.log4j.core.config.
- LoggerConfig${dollar}RootLogger for element root with
params(additivity="null", level="error",
- AppenderRef={STDOUT}, null)
-2011-11-23 17:08:00,833 DEBUG Calling createLoggers on class
org.apache.logging.log4j.core.
- config.plugins.LoggersPlugin for element loggers with
params(loggers={EventLogger, root})
-2011-11-23 17:08:00,834 DEBUG Reconfiguration completed
-2011-11-23 17:08:00,846 DEBUG Calling createLayout on class
org.apache.logging.log4j.core.
- layout.PatternLayout for element PatternLayout with params(pattern="%d
%p %c{1.} [%t] %m%n",
- Configuration(RoutingTest), null, charset="null")
-2011-11-23 17:08:00,849 DEBUG Calling createPolicy on class
org.apache.logging.log4j.core.
- appender.rolling.SizeBasedTriggeringPolicy for element
SizeBasedTriggeringPolicy with
- params(size="500")
-2011-11-23 17:08:00,851 DEBUG Calling createAppender on class
org.apache.logging.log4j.core.
- appender.RollingFileAppender for element RollingFile with
- params(fileName="target/rolling1/rollingtest-Unknown.log",
- filePattern="target/rolling1/test1-Unknown.%i.log.gz", append="null",
name="Rolling-Unknown",
- bufferedIO="null", immediateFlush="null",
- SizeBasedTriggeringPolicy(SizeBasedTriggeringPolicy(size=500)), null,
- PatternLayout(%d %p %c{1.} [%t] %m%n), null, ignoreExceptions="null")
-2011-11-23 17:08:00,858 DEBUG Generated plugins in 0.002014000 seconds
-2011-11-23 17:08:00,889 DEBUG Reconfiguration started for context sun.misc.
- Launcher${dollar}AppClassLoader@37b90b39
-2011-11-23 17:08:00,890 DEBUG Generated plugins in 0.001355000 seconds
-2011-11-23 17:08:00,959 DEBUG Generated plugins in 0.001239000 seconds
-2011-11-23 17:08:00,961 DEBUG Generated plugins in 0.001197000 seconds
-2011-11-23 17:08:00,965 WARN No Loggers were configured, using default
-2011-11-23 17:08:00,976 DEBUG Reconfiguration completed</pre>
-#else
-<pre>
-2011-11-23 17:08:00,769 DEBUG Generated plugins in 0.003374000 seconds
-2011-11-23 17:08:00,789 DEBUG Calling createProperty on class
org.apache.logging.log4j.core.config.Property for element property with
params(name="filename",
value="target/rolling1/rollingtest-${dollar}{sd:type}.log")
-2011-11-23 17:08:00,792 DEBUG Calling configureSubstitutor on class
org.apache.logging.log4j.core.config.PropertiesPlugin for element properties
with
params(properties={filename=target/rolling1/rollingtest-${dollar}{sd:type}.log})
-2011-11-23 17:08:00,794 DEBUG Generated plugins in 0.001362000 seconds
-2011-11-23 17:08:00,797 DEBUG Calling createFilter on class
org.apache.logging.log4j.core.filter.ThresholdFilter for element
ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null")
-2011-11-23 17:08:00,800 DEBUG Calling createLayout on class
org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout
with params(pattern="%m%n", Configuration(RoutingTest), null, charset="null")
-2011-11-23 17:08:00,802 DEBUG Generated plugins in 0.001349000 seconds
-2011-11-23 17:08:00,804 DEBUG Calling createAppender on class
org.apache.logging.log4j.core.appender.ConsoleAppender for element Console with
params(PatternLayout(%m%n), null, target="null", name="STDOUT",
ignoreExceptions="null")
-2011-11-23 17:08:00,804 DEBUG Calling createFilter on class
org.apache.logging.log4j.core.filter.ThresholdFilter for element
ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null")
-2011-11-23 17:08:00,813 DEBUG Calling createRoute on class
org.apache.logging.log4j.core.appender.routing.Route for element Route with
params(AppenderRef="null", key="null", Node=Route)
-2011-11-23 17:08:00,823 DEBUG Calling createRoute on class
org.apache.logging.log4j.core.appender.routing.Route for element Route with
params(AppenderRef="STDOUT", key="Audit", Node=Route)
-2011-11-23 17:08:00,825 DEBUG Calling createRoutes on class
org.apache.logging.log4j.core.appender.routing.Routes for element Routes with
params(pattern="${dollar}{sd:type}", routes={Route(type=dynamic default),
Route(type=static Reference=STDOUT key='Audit')})
-2011-11-23 17:08:00,827 DEBUG Calling createAppender on class
org.apache.logging.log4j.core.appender.routing.RoutingAppender for element
Routing with params(name="Routing", ignoreExceptions="null",
Routes({Route(type=dynamic default),Route(type=static Reference=STDOUT
key='Audit')}), Configuration(RoutingTest), null, null)
-2011-11-23 17:08:00,827 DEBUG Calling createAppenders on class
org.apache.logging.log4j.core.config.AppendersPlugin for element appenders with
params(appenders={STDOUT, Routing})
-2011-11-23 17:08:00,828 DEBUG Calling createAppenderRef on class
org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element
AppenderRef with params(ref="Routing")
-2011-11-23 17:08:00,829 DEBUG Calling createLogger on class
org.apache.logging.log4j.core.config.LoggerConfig for element logger with
params(additivity="false", level="info", name="EventLogger",
AppenderRef={Routing}, null)
-2011-11-23 17:08:00,830 DEBUG Calling createAppenderRef on class
org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element
AppenderRef with params(ref="STDOUT")
-2011-11-23 17:08:00,831 DEBUG Calling createLogger on class
org.apache.logging.log4j.core.config.LoggerConfig${dollar}RootLogger for
element root with params(additivity="null", level="error",
AppenderRef={STDOUT}, null)
-2011-11-23 17:08:00,833 DEBUG Calling createLoggers on class
org.apache.logging.log4j.core.config.LoggersPlugin for element loggers with
params(loggers={EventLogger, root})
-2011-11-23 17:08:00,834 DEBUG Reconfiguration completed
-2011-11-23 17:08:00,846 DEBUG Calling createLayout on class
org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout
with params(pattern="%d %p %c{1.} [%t] %m%n", Configuration(RoutingTest), null,
charset="null")
-2011-11-23 17:08:00,849 DEBUG Calling createPolicy on class
org.apache.logging.log4j.core.appender.rolling.SizeBasedTriggeringPolicy for
element SizeBasedTriggeringPolicy with params(size="500")
-2011-11-23 17:08:00,851 DEBUG Calling createAppender on class
org.apache.logging.log4j.core.appender.RollingFileAppender for element
RollingFile with params(fileName="target/rolling1/rollingtest-Unknown.log",
filePattern="target/rolling1/test1-Unknown.%i.log.gz", append="null",
name="Rolling-Unknown", bufferedIO="null", immediateFlush="null",
SizeBasedTriggeringPolicy(SizeBasedTriggeringPolicy(size=500)), null,
PatternLayout(%d %p %c{1.} [%t] %m%n), null, ignoreExceptions="null")
-2011-11-23 17:08:00,858 DEBUG Generated plugins in 0.002014000 seconds
-2011-11-23 17:08:00,889 DEBUG Reconfiguration started for context
sun.misc.Launcher${dollar}AppClassLoader@37b90b39
-2011-11-23 17:08:00,890 DEBUG Generated plugins in 0.001355000 seconds
-2011-11-23 17:08:00,959 DEBUG Generated plugins in 0.001239000 seconds
-2011-11-23 17:08:00,961 DEBUG Generated plugins in 0.001197000 seconds
-2011-11-23 17:08:00,965 WARN No Loggers were configured, using default
-2011-11-23 17:08:00,976 DEBUG Reconfiguration completed</pre>
-#end
- <p>
- If the status attribute is set to error than only error messages
will be written to the console. This
- makes troubleshooting configuration errors possible. As an
example, if the configuration above is changed
- to have the status set to error and the logger declaration is:</p>
- <pre class="prettyprint linenums"><![CDATA[
-<logger name="EventLogger" level="info" additivity="false">
- <AppenderRef ref="Routng"/>
-</logger>
-]]></pre>
- <p>
- the following error message will be produced.
- </p>
- <pre>2011-11-24 23:21:25,517 ERROR Unable to locate appender Routng
for logger EventLogger</pre>
- <p>
- Applications may wish to direct the status output to some other
destination. This can be accomplished
- by setting the dest attribute to either "err" to send the output
to stderr or to a file location or URL.
- This can also be done by insuring the configured status is set to
OFF and then configuring the application
- programmatically such as:
- </p>
-<pre class="prettyprint linenums"><![CDATA[
-StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR);
-StatusLogger.getLogger().registerListener(listener);
-]]></pre>
- </subsection>
- <a name="UnitTestingInMaven"/>
- <subsection name="Testing in Maven">
- <p>
- Maven can run unit and functional tests during the build cycle. By
default, any files placed in
- <code>src/test/resources</code> are automatically copied to
target/test-classes and are included
- in the classpath during execution of any tests. As such, placing a
log4j2-test.xml into this directory
- will cause it to be used instead of a log4j2.xml or log4j2.json that
might be present. Thus a different
- log configuration can be used during testing than what is used in
production.
- </p>
- <p>
- A second approach, which is extensively used by Log4j 2, is to set
the log4j.configurationFile property
- in the method annotated with @BeforeClass in the junit test class.
This will allow an arbitrarily
- named file to be used during the test.
- </p>
- <p>
- A third approach, also used extensively by Log4j 2, is to use the
<code>LoggerContextRule</code>
- JUnit test rule which provides additional convenience methods for
testing. This requires adding the
- <code>log4j-core</code> <code>test-jar</code> dependency to your
test scope dependencies. For example:
- </p>
- <pre class="prettyprint linenums"><![CDATA[
-public class AwesomeTest {
- @Rule
- public LoggerContextRule init = new LoggerContextRule("MyTestConfig.xml");
-
- @Test
- public void testSomeAwesomeFeature() {
- final LoggerContext ctx = init.getLoggerContext();
- final Logger logger =
init.getLogger("org.apache.logging.log4j.my.awesome.test.logger");
- final Configuration cfg = init.getConfiguration();
- final ListAppender app = init.getListAppender("List");
- logger.warn("Test message");
- final List<LogEvent> events = app.getEvents();
- // etc.
- }
-}
-]]></pre>
- </subsection>
- <a name="SystemProperties"/>
- <subsection name="System Properties">
- <p>
- The Log4j documentation references a number of System Properties
that can be used to control various aspects
- of Log4j 2 behavior. The table below lists these properties along
with their default value and a
- description of what they control.
- Any spaces present in the property name are for visual flow and
should be removed.
- </p>
- <p>
- Note that beginning in Log4j 2.10, all system property names have
been normalized to follow a consistent
- naming scheme. While the old property names are still supported
for backwards compatibility, it is
- recommended to update configurations to use the new style. This
system is extensible and is enabled
- through the
- <a class="javadoc"
href="../log4j-api/apidocs/org/apache/logging/log4j/util/PropertySource.html">PropertySource</a>
- interface. Additional property source classes can be added through
the standard <code>ServiceLoader</code>
- mechanism in Java SE.
- </p>
- <p>
- Properties can be overridden by sources with a lower number
priority (e.g.., -100 comes before 100). The
- following sources are all available by default:
- </p>
- <table>
- <caption align="top">PropertySource priorities and
descriptions</caption>
- <tr>
- <th>Source</th>
- <th>Priority</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>Spring Boot Properties</td>
- <td>-100</td>
- <td>
- This property source is enabled only if the Java application
uses Spring Boot and the
- <code>log4j-spring</code> module is present. It resolves
properties using a Spring
- <a
href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/Environment.html";>Environment</a>.
- </td>
- </tr>
- <tr>
- <td>System Properties</td>
- <td>0</td>
- <td>
- All properties can be set using normal system property
patterns. These have the lowest numerical priority
- among commonly available property sources and can override
properties files or environment variables.
- If a <code>log4j2.system.properties</code> file is available
on the classpath its contents are
- sourced into Java system properties at Log4j startup.
- </td>
- </tr>
- <tr>
- <td>Environment Variables</td>
- <td>100</td>
- <td>
- Environment variables are all prefixed with
<code>LOG4J_</code>, are in all caps, and words are all
- separated by underscores. Only this naming scheme is support
for environment variables as there were
- no old naming schemes to maintain compatibility with.
- </td>
- </tr>
- <tr>
- <td><code>log4j2.component.properties</code> file</td>
- <td>200</td>
- <td>
- Including this file on the classpath can be used as an
alternative to providing properties as system
- properties. This is the property source with highest numerical
priority and can be used to provide
- default values that can be overridden by the system
administrator.
- </td>
- </tr>
- </table>
- <p>
- The following is a list of available global configuration
properties. Note that these can only be set once
- per JVM process unlike configuration settings available in
configuration files. The <i>Property Name</i>
- column contains the name used in properties files and system
properties; <i>Environment Variable</i>
- for the equivalent environment variable; and <i>Legacy Property
Name</i> for the pre-2.10 name.
- </p>
-<style>
- * { // this works for all but td
- word-wrap:break-word;
- }
-
- table { // this somehow makes it work for td
- table-layout:fixed;
- width:100%;
- }
-</style>
-<table style="table-layout: fixed; width: 100%">
- <caption align="top">Log4j 2 global configuration properties</caption>
- <tr>
- <th>Property Name <br /> (Legacy Property Name)</th>
- <th>Environment Variable</th>
- <th>Default Value</th>
- <th>Description</th>
- </tr>
-
- <tr>
- <td><a name="configurationFile"/>log4j2.configurationFile
- <br />
- (<a name="log4j.configurationFile"/>log4j.configurationFile)
- </td>
- <td>LOG4J_CONFIGURATION_FILE</td>
- <td> </td>
- <td>
- Path to an Log4j 2 configuration file. May also contain a comma
separated list of configuration file names.
- May contain a URL. When specified as a URL the "override" query
parameter may be used to specify additional
- configuration file locations.
- </td>
- </tr>
- <tr>
- <td><a name="debug"/>log4j2.debug
- <br />
- (<a name="log4j2.debug"/>log4j2.debug)
- </td>
- <td>LOG4J_DEBUG</td>
- <td> </td>
- <td>
- Log4j2 will print all internal logging to the console if system property
- <tt>log4j2.debug</tt> is either defined empty or its value equals to
<tt>true</tt> (ignoring case).
- </td>
- </tr>
- <tr>
- <td><a name="mergeStrategy"/>log4j2.mergeStrategy
- <br />
- (<a name="log4j.mergeStrategy"/>log4j.mergeStrategy)
- </td>
- <td>LOG4J_MERGE_STRATEGY</td>
- <td> </td>
- <td>
- The name of the class that implements the MergeStrategy interface. If
not specified
- <code>DefaultMergeStrategy</code> will be used when creating a
CompositeConfiguration..
- </td>
- </tr>
- <tr>
- <td><a name="contextSelector"/>log4j2.contextSelector
- <br />
- (<a name="Log4jContextSelector"/>Log4jContextSelector)
- </td>
- <td>LOG4J_CONTEXT_SELECTOR</td>
- <td>ClassLoaderContextSelector</td>
- <td>
- Creates the <tt>LoggerContext</tt>s. An application can have one or more
active LoggerContexts depending
- on the circumstances.
- See <a href="logsep.html">Log Separation</a> for more details.
- Available context selector implementation classes:<br />
- <!-- deliberately inserted spaces to allow line break -->
- <tt>org.apache.logging.log4j.core.async .AsyncLoggerContextSelector</tt>
- makes <a href="async.html">all loggers asynchronous</a>.<br />
- <tt>org.apache.logging.log4j.core.async
.BasicAsyncLoggerContextSelector</tt> - makes <a href="async.html">all loggers
asynchronous</a> using a single shared AsyncLoggerContext.<br />
- <tt>org.apache.logging.log4j.core.selector .BasicContextSelector</tt> -
creates a single shared LoggerContext.<br />
- <tt>org.apache.logging.log4j.core.selector
.ClassLoaderContextSelector</tt> - separate LoggerContexts for each web
application.<br />
- <tt>org.apache.logging.log4j.core.selector .JndiContextSelector</tt> -
use JNDI to locate each web application's LoggerContext.<br/>
- <tt>org.apache.logging.log4j.core.osgi .BundleContextSelector</tt> -
separate LoggerContexts for each OSGi bundle.
- </td>
- </tr>
- <tr>
- <td><a name="logEventFactory"/>log4j2.logEventFactory
- <br />
- (<a name="Log4jLogEventFactory"/>Log4jLogEventFactory)
- </td>
- <td>LOG4J_LOG_EVENT_FACTORY</td>
- <!-- deliberately inserted spaces to allow line break -->
- <td>org.apache.logging.log4j.core.impl .DefaultLogEventFactory</td>
- <td>
- Factory class used by LoggerConfig to create <tt>LogEvent</tt> instances.
- (Ignored when the <tt>AsyncLoggerContextSelector</tt> is used.)
- </td>
- </tr>
- <tr>
- <td><a name="loggerContextFactory"/>log4j2.loggerContextFactory
- <br />
- (<a name="log4j2.loggerContextFactory"/>log4j2.loggerContextFactory)
- </td>
- <td>LOG4J_LOGGER_CONTEXT_FACTORY</td>
- <!-- deliberately inserted spaces to allow line break -->
- <td>org.apache.logging.log4j.simple .SimpleLoggerContextFactory</td>
- <td>
- Factory class used by LogManager to bootstrap the logging implementation.
- The core jar provides <tt>org.apache.logging.log4j.core
- .impl.Log4jContextFactory</tt>.
- </td>
- </tr>
- <tr>
- <td><a name="configurationFactory"/>log4j2.configurationFactory
- <br />
- (<a name="log4j.configurationFactory"/>log4j.configurationFactory)
- </td>
- <td>LOG4J_CONFIGURATION_FACTORY</td>
- <td> </td>
- <td>
- Fully specified class name of a class extending
<tt>org.apache.logging.log4j.core
- .config.ConfigurationFactory</tt>.
- If specified, an instance of this class is added to the list of
configuration factories.
- </td>
- </tr>
- <tr>
- <td><a
name="configurationAllowedProtocols"/>log4j2.Configuration.allowedProtocols
- <br />
- (<a
name="log4j.configurationAllowedProtocols"/>log4j.configurationAllowedProtocols)
- </td>
- <td>LOG4J_CONFIGURATION_ALLOWED_PROTOCOLS</td>
- <td> </td>
- <td>
- A comma separated list of the protocols that may be used to load a
configuration file. The default is
- "https, file, jar". To completely prevent accessing the configuration
via a URL specify a value of "_none".
- </td>
- </tr>
- <tr>
- <td><a
name="log4j2.configurationAuthorizationEncoding"/>log4j2.configurationAuthorizationEncoding</td>
- <td>LOG4J_CONFIGURATION_AUTHORIZATION_ENCODING</td>
- <td>UTF-8</td>
- <td>
- The encoding used in Basic Authentication (cf. <a
href="https://datatracker.ietf.org/doc/html/rfc7617";>RFC 7617</a>).
- </td>
- </tr>
- <tr>
- <td><a
name="configurationAuthorizationProvider"/>log4j2.Configuration.authorizationProvider
- <br />
- (<a
name="log4j.configurationAuthorizationProvider"/>log4j.configurationAuthorizationProvider
- </td>
- <td>LOG4J_CONFIGURATION_AUTHORIZATION_PROVIDER</td>
- <td>org.apache.logging.log4j.core.util.BasicAuthorizationProvider</td>
- <td>
- The fully qualified class name of the AuthorizationProvider.
- </td>
- </tr>
- <tr>
- <td><a name="configurationPassword"/>log4j2.Configuration.password
- <br />
- (<a name="log4j.configurationPassword"/>log4j.configurationPassword
- </td>
- <td>LOG4J_CONFIGURATION_PASSWORD</td>
- <td> </td>
- <td>
- The password required to access the remote logging configuration file.
- </td>
- </tr>
- <tr>
- <td><a
name="configurationPasswordDecryptor"/>log4j2.Configuration.passwordDecryptor
- <br />
- (<a
name="log4j.configurationPasswordDecryptor"/>log4j.configurationPasswordDecryptor
- </td>
- <td>LOG4J_CONFIGURATION_PASSWORD_DECRYPTOR</td>
- <td> </td>
- <td>
- If the password is encrypted this class will be used to decrypt it.
- </td>
- </tr>
- <tr>
- <td><a name="configurationUsername"/>log4j2.Configuration.username
- <br />
- (<a name="log4j.configurationUsername"/>log4j.configurationUsername
- </td>
- <td>LOG4J_CONFIGURATION_USERNAME</td>
- <td> </td>
- <td>
- The user name required to access the remote logging configuration file.
- </td>
- </tr>
- <tr>
- <td><a name="shutdownHookEnabled"/>log4j2.shutdownHookEnabled
- <br />
- (<a name="log4j.shutdownHookEnabled"/>log4j.shutdownHookEnabled)
- </td>
- <td>LOG4J_SHUTDOWN_HOOK_ENABLED</td>
- <td>true</td>
- <td>
- Overrides the global flag for whether or not a shutdown hook should be
used to stop a <tt>LoggerContext</tt>.
- By default, this is enabled and can be disabled on a per-configuration
basis. When running with the
- <tt>log4j-web</tt> module, this is automatically disabled.
- </td>
- </tr>
- <tr>
- <td><a name="shutdownCallbackRegistry"/>log4j2.shutdownCallbackRegistry
- <br />
- (<a
name="log4j.shutdownCallbackRegistry"/>log4j.shutdownCallbackRegistry)
- </td>
- <td>LOG4J_SHUTDOWN_CALLBACK_REGISTRY</td>
- <!-- deliberately inserted spaces to allow line break -->
- <td>org.apache.logging.log4j.core.util
.DefaultShutdownCallbackRegistry</td>
- <td>
- Fully specified class name of a class implementing
- <a class="javadoc"
href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html">ShutdownCallbackRegistry</a>.
- If specified, an instance of this class is used instead of
<tt>DefaultShutdownCallbackRegistry</tt>.
- The specified class must have a default constructor.
- </td>
- </tr>
- <tr>
- <td><a name="clock"/>log4j2.clock
- <br />
- (<a name="log4j.Clock"/>log4j.Clock)
- </td>
- <td>LOG4J_CLOCK</td>
- <td>SystemClock</td>
- <td>
- Implementation of the <tt>org.apache.logging.log4j .core.util.Clock</tt>
- interface that is used for timestamping the log events.
- <br />
- By default, <tt>System.currentTimeMillis</tt> is called on every log
event.
- <br />
- You can also specify a fully qualified class name of a custom class that
implements the
- <tt>Clock</tt> interface.
- </td>
- </tr>
- <tr>
- <td><a name="level"/>log4j2.level
- <br />
- (<a
name="org.apache.logging.log4j.level"/>org.apache.logging.log4j.level)
- </td>
- <td>LOG4J_LEVEL</td>
- <td>ERROR</td>
- <td>
- Log level of the default configuration. The default configuration is
used if the ConfigurationFactory
- could not successfully create a configuration (e.g. no log4j2.xml file
was found).
- </td>
- </tr>
- <tr>
- <td><a name="disableThreadContext"/>log4j2.disableThreadContext
- <br />
- (disableThreadContext)
- </td>
- <td>LOG4J_DISABLE_THREAD_CONTEXT</td>
- <td>false</td>
- <td>
- If <tt>true</tt>, the ThreadContext stack and map are disabled.
- (May be ignored if a custom ThreadContext map is specified.)
- </td>
- </tr>
- <tr>
- <td><a name="disableThreadContextStack"/>log4j2.disableThreadContextStack
- <br />
- (disableThreadContextStack)
- </td>
- <td>LOG4J_DISABLE_THREAD_CONTEXT_STACK</td>
- <td>false</td>
- <td>
- If <tt>true</tt>, the ThreadContext stack is disabled.
- </td>
- </tr>
- <tr>
- <td><a name="disableThreadContextMap"/>log4j2.disableThreadContextMap
- <br />
- (disableThreadContextMap)
- </td>
- <td>LOG4J_DISABLE_THREAD_CONTEXT_MAP</td>
- <td>false</td>
- <td>
- If <tt>true</tt>, the ThreadContext map is disabled.
- (May be ignored if a custom ThreadContext map is specified.)
- </td>
- </tr>
- <tr>
- <td><a name="log4j2.threadContextMap"/>log4j2.threadContextMap
- <br />
- (log4j2.threadContextMap)
- </td>
- <td>LOG4J_THREAD_CONTEXT_MAP</td>
- <td> </td>
- <td>
- Fully specified class name of a custom <tt>ThreadContextMap</tt>
implementation class.
- </td>
- </tr>
- <tr>
- <td><a
name="isThreadContextMapInheritable"/>log4j2.isThreadContextMapInheritable
- <br />
- (isThreadContextMapInheritable)
- </td>
- <td>LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE</td>
- <td>false</td>
- <td>
- If <tt>true</tt> use a <tt>InheritableThreadLocal</tt> to implement the
ThreadContext map.
- Otherwise, use a plain <tt>ThreadLocal</tt>.
- (May be ignored if a custom ThreadContext map is specified.)
- </td>
- </tr>
- <tr>
- <td><a name="contextDataInjector"/>log4j2.contextDataInjector
- <br />
- (<a name="log4j2.ContextDataInjector"/>log4j2.ContextDataInjector)
- </td>
- <td>LOG4J_CONTEXT_DATA_INJECTOR</td>
- <td> </td>
- <td>
- Fully specified class name of a custom <tt>ContextDataInjector</tt>
implementation class.
- </td>
- </tr>
- <tr>
- <td><a
name="garbagefreeThreadContextMap"/>log4j2.garbagefreeThreadContextMap
- <br />
- (<a
name="log4j2.garbagefree.threadContextMap"/>log4j2.garbagefree.threadContextMap)
- </td>
- <td>LOG4J_GARBAGEFREE_THREAD_CONTEXT_MAP</td>
- <td>false</td>
- <td>
- Specify "true" to make the ThreadContext map garbage-free.
- </td>
- </tr>
- <tr>
- <td><a name="disableJmx"/>log4j2.disableJmx
- <br />
- (<a name="log4j2.disable.jmx"/>log4j2.disable.jmx)
- </td>
- <td>LOG4J_DISABLE_JMX</td>
- <td>false</td>
- <td>
- If <tt>true</tt>, Log4j configuration objects like LoggerContexts,
Appenders, Loggers, etc.
- will not be instrumented with MBeans and cannot be remotely monitored
and managed.
- </td>
- </tr>
- <tr>
- <td><a name="jmxNotifyAsync"/>log4j2.jmxNotifyAsync
- <br />
- (<a name="log4j2.jmx.notify.async"/>log4j2.jmx.notify.async)
- </td>
- <td>LOG4J_JMX_NOTIFY_ASYNC</td>
- <td>false for web apps, true otherwise</td>
- <td>
- If <tt>true</tt>, log4j's JMX notifications are sent from a separate
background thread,
- otherwise they are sent from the caller thread.
- If system property <tt>log4j2.is.webapp</tt> is <tt>true</tt> or the
<tt>javax.servlet.Servlet</tt>
- class is on the classpath, the default behaviour
- is to use the caller thread to send JMX notifications.
- </td>
- </tr>
- <tr>
- <td><a name="skipJansi"/>log4j2.skipJansi
- <br />
- (<a name="log4j.skipJansi"/>log4j.skipJansi)
- </td>
- <td>LOG4J_SKIP_JANSI</td>
- <td>true</td>
- <td>
- If <tt>true</tt>, the ConsoleAppender will not try to use the Jansi
output stream on Windows.
- </td>
- </tr>
- <tr>
- <td><a name="ignoreTCL"/>log4j2.ignoreTCL
- <br />
- (<a name="log4j.ignoreTCL"/>log4j.ignoreTCL)
- </td>
- <td>LOG4J_IGNORE_TCL</td>
- <td>false</td>
- <td>
- If <tt>true</tt>, classes are only loaded with the default class loader.
- Otherwise, an attempt is made to load classes with the current thread's
context class loader
- before falling back to the default class loader.
- </td>
- </tr>
- <tr>
- <td><a
name="enableJndiContextSelector"/>log4j2.enableJndiContextSelector</td>
- <td>LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR</td>
- <td>false</td>
- <td>
- When true, the Log4j context selector that uses the JNDI java protocol
is enabled. When false, the default, they are disabled.
- </td>
- </tr>
- <tr>
- <td><a name="enableJndiJdbc"/>log4j2.enableJndiJdbc</td>
- <td>LOG4J_ENABLE_JNDI_JDBC</td>
- <td>false</td>
- <td>
- When true, a Log4j JDBC Appender configured with a
<code>DataSource</code> which uses JNDI's java protocol is enabled. When false,
the default, they are disabled.
- </td>
- </tr>
- <tr>
- <td><a name="enableJndiJms"/>log4j2.enableJndiJms</td>
- <td>LOG4J_ENABLE_JNDI_JMS</td>
- <td>false</td>
- <td>
- When true, a Log4j JMS Appender that uses JNDI's java protocol is
enabled. When false, the default, they are disabled.
- </td>
- </tr>
- <tr>
- <td><a name="enableJndiLookup"/>log4j2.enableJndiLookup</td>
- <td>LOG4J_ENABLE_JNDI_LOOKUP</td>
- <td>false</td>
- <td>
- When true, a Log4j lookup that uses JNDI's java protocol is enabled.
When false, the default, they are disabled.
- </td>
- </tr>
- <tr>
- <td><a name="uuidSequence"/>log4j2.uuidSequence
- <br />
- (<a
name="org.apache.logging.log4j.uuidSequence"/>org.apache.logging.log4j.uuidSequence)
- </td>
- <td>LOG4J_UUID_SEQUENCE</td>
- <td>0</td>
- <td>
- System property that may be used to seed the UUID generation with an
integer value.
- </td>
- </tr>
- <!--
- <tr>
- <td><a name="assignedSequences">log4j2.assignedSequences</td>
- <td>LOG4J_ASSIGNED_SEQUENCES</td>
- <td><a
name="org.apache.logging.log4j.assignedSequences"/>org.apache.logging.log4j.assignedSequences</td>
- <td>true</td>
- <td>
- TODO: used to seed UUID generation. Not sure when or why one would use
this...
- </td>
- </tr>
- -->
- <tr>
- <td><a name="simplelogShowContextMap"/>log4j2.simplelogShowContextMap
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.showContextMap"/>org.apache.logging.log4j
.simplelog.showContextMap)
- </td>
- <td>LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP</td>
- <td>false</td>
- <td>If <tt>true</tt>, the full ThreadContext map is included in each
SimpleLogger log message.</td>
- </tr>
- <tr>
- <td><a name="simplelogShowlogname"/>log4j2.simplelogShowlogname
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.showlogname"/>org.apache.logging.log4j
.simplelog.showlogname)
- </td>
- <td>LOG4J_SIMPLELOG_SHOWLOGNAME</td>
- <td>false</td>
- <td>If <tt>true</tt>, the logger name is included in each SimpleLogger log
message.</td>
- </tr>
- <tr>
- <td><a name="simplelogShowShortLogname"/>log4j2.simplelogShowShortLogname
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.showShortLogname"/>org.apache.logging.log4j
.simplelog.showShortLogname)
- </td>
- <td>LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME</td>
- <td>true</td>
- <td>If <tt>true</tt>, only the last component of a logger name is included
in SimpleLogger log messages.
- (E.g., if the logger name is "mycompany.myproject.mycomponent", only
"mycomponent" is logged.
- </td>
- </tr>
- <tr>
- <td><a name="simplelogShowdatetime"/>log4j2.simplelogShowdatetime
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.showdatetime"/>org.apache.logging.log4j
.simplelog.showdatetime)
- </td>
- <td>LOG4J_SIMPLELOG_SHOWDATETIME</td>
- <td>false</td>
- <td>If <tt>true</tt>, SimpleLogger log messages contain timestamp
information.
- </td>
- </tr>
- <tr>
- <td><a name="simplelogDateTimeFormat"/>log4j2.simplelogDateTimeFormat
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.dateTimeFormat"/>org.apache.logging.log4j
.simplelog.dateTimeFormat)
- </td>
- <td>LOG4J_SIMPLELOG_DATE_TIME_FORMAT</td>
- <td>"yyyy/MM/dd HH:mm:ss:SSS zzz"</td>
- <td>Date-time format to use.
- Ignored if <tt>org.apache.logging.log4j .simplelog.showdatetime</tt> is
<tt>false</tt>.
- </td>
- </tr>
- <tr>
- <td><a name="simplelogLogFile"/>log4j2.simplelogLogFile
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.logFile"/>org.apache.logging.log4j
.simplelog.logFile)
- </td>
- <td>LOG4J_SIMPLELOG_LOG_FILE</td>
- <td>system.err</td>
- <td>"system.err" (case-insensitive) logs to System.err,
- "system.out" (case-insensitive) logs to System.out,
- any other value is interpreted as a file name to save SimpleLogger
messages to.
- </td>
- </tr>
- <tr>
- <td><a name="simplelogLevel"/>log4j2.simplelogLevel
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.level"/>org.apache.logging.log4j
.simplelog.level)
- </td>
- <td>LOG4J_SIMPLELOG_LEVEL</td>
- <td>ERROR</td>
- <td>Default level for new SimpleLogger instances.
- </td>
- </tr>
- <tr>
- <td>log4j2.simplelog.<loggerName>.level
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a
name="org.apache.logging.log4j.simplelog.[loggerName]level"/>org.apache.logging.log4j
.simplelog.<loggerName>.level)
- </td>
- <td>LOG4J_SIMPLELOG_<LOGGER_NAME>_LEVEL</td>
- <td>SimpleLogger default log level</td>
- <td>Log level for a the SimpleLogger instance with the specified name.</td>
- </tr>
- <tr>
- <td><a name="simplelogStatusLoggerLevel"/>log4j2.simplelogStatusLoggerLevel
- <br />
- <!-- deliberately inserted spaces to allow line break -->
- (<a name="org.apache.logging.log4j.simplelog.StatusLogger.level"
/>org.apache.logging.log4j.simplelog .StatusLogger.level)
- </td>
- <td>LOG4J_SIMPLELOG_STATUS_LOGGER_LEVEL</td>
- <td>ERROR</td>
- <td>This property is used to control the initial StatusLogger level, and
can be overridden in code by calling
- <code>StatusLogger.getLogger() .setLevel(someLevel)</code>.
- Note that the StatusLogger level is only used to determine the status log
output level
- until a listener is registered. In practice, a listener is registered when
a configuration is found,
- and from that point onwards, status messages are only sent to the
listeners (depending on their statusLevel).</td>
- </tr>
- <tr>
- <td><a name="defaultStatusLevel"/>log4j2.defaultStatusLevel
- <br />
- (<a name="Log4jDefaultStatusLevel" />Log4jDefaultStatusLevel)
- </td>
- <td>LOG4J_DEFAULT_STATUS_LEVEL</td>
- <td>ERROR</td>
- <td>
- <p>The StatusLogger logs events that occur in the logging system to the
console.
- During configuration, AbstractConfiguration registers a
StatusConsoleListener with the StatusLogger that may
- redirect status log events from the default console output to a file.
- The listener also supports fine-grained filtering.
- This system property specifies the default status log level for the
listener to use if the configuration does not
- specify a status level.
- </p><p>
- Note: this property is used by the log4j-core implementation only after
a configuration file has been found.</p>
- </td>
- </tr>
- <tr>
- <td><a name="statusLoggerLevel"/>log4j2.statusLoggerLevel
- <br />
- (<a name="log4j2.StatusLogger.level"/>log4j2.StatusLogger.level)
- </td>
- <td>LOG4J_STATUS_LOGGER_LEVEL</td>
- <td>WARN</td>
- <td>
- <p>The initial "listenersLevel" of the StatusLogger. If StatusLogger
listeners are added, the "listenerLevel"
- is changed to that of the most verbose listener. If any listeners are
registered, the listenerLevel is
- used to quickly determine if an interested listener exists.
- </p><p>
- By default, StatusLogger listeners are added when a configuration is
found and by the JMX
- StatusLoggerAdmin MBean. For example, if a configuration contains
- <code><Configuration status="trace"></code>, a listener with
statusLevel TRACE is registered
- and the StatusLogger listenerLevel is set to TRACE, resulting in verbose
status messages displayed on the console.
- </p><p>
- If no listeners are registered, the listenersLevel is not used, and the
StatusLogger output level
- is determined by <code>StatusLogger.getLogger().getLevel()</code>
- (see property <code>org.apache.logging.log4j.simplelog
.StatusLogger.level</code>).</p>
- </td>
- </tr>
- <tr>
- <td><a name="statusEntries"/>log4j2.statusEntries
- <br />
- (<a name="log4j2.status.entries"/>log4j2.status.entries)
- </td>
- <td>LOG4J_STATUS_ENTRIES</td>
- <td>200</td>
- <td>
- Number of StatusLogger events that are kept in a buffer and can be
retrieved with
- <tt>StatusLogger.getStatusData()</tt>.
- </td>
- </tr>
- <tr>
- <td><a name="statusLoggerDateformat"/>log4j2.statusLoggerDateformat
- <br />
- (<a
name="log4j2.StatusLogger.DateFormat"/>log4j2.StatusLogger.DateFormat)
- </td>
- <td>LOG4J_STATUS_LOGGER_DATEFORMAT</td>
- <td> </td>
- <td>
- Date-time format string to use as the format for timestamps
- in the status logger output. See <code>java.text.SimpleDateFormat</code>
for supported formats.
- </td>
- </tr>
- <tr>
- <td><a
name="asyncLoggerExceptionHandler"/>log4j2.asyncLoggerExceptionHandler
- <br />
- (<a name="AsyncLogger.ExceptionHandler"/>AsyncLogger.ExceptionHandler)
- </td>
- <td>LOG4J_ASYNC_LOGGER_EXCEPTION_HANDLER</td>
- <td>default handler</td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a name="asyncLoggerRingBufferSize"/>log4j2.asyncLoggerRingBufferSize
- <br />
- (<a name="AsyncLogger.RingBufferSize"/>AsyncLogger.RingBufferSize)
- </td>
- <td>LOG4J_ASYNC_LOGGER_RING_BUFFER_SIZE</td>
- <td>256 * 1024 or 4 * 1024 in garbage-free mode</td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a name="asyncLoggerWaitStrategy"/>log4j2.asyncLoggerWaitStrategy
- <br />
- (<a name="AsyncLogger.WaitStrategy" />AsyncLogger.WaitStrategy)
- </td>
- <td>LOG4J_ASYNC_LOGGER_WAIT_STRATEGY</td>
- <td>
- Timeout
- </td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a name="asyncLoggerTimeout"/>log4j2.asyncLoggerTimeout
- <br />
- (<a name="AsyncLogger.Timeout" />AsyncLogger.Timeout)
- </td>
- <td>LOG4J_ASYNC_LOGGER_TIMEOUT</td>
- <td>
- 10
- </td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a name="asyncLoggerSleepTimeNs"/>log4j2.asyncLoggerSleepTimeNs
- <br />
- (<a name="AsyncLogger.SleepTimeNs" />AsyncLogger.SleepTimeNs)
- </td>
- <td>LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS</td>
- <td>
- 100
- </td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a name="asyncLoggerRetries"/>log4j2.asyncLoggerRetries
- <br />
- (<a name="AsyncLogger.Retries" />AsyncLogger.Retries)
- </td>
- <td>LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS</td>
- <td>
- 200
- </td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a
name="AsyncLogger.SynchronizeEnqueueWhenQueueFull"/>AsyncLogger.SynchronizeEnqueueWhenQueueFull
- </td>
- <td>ASYNC_LOGGER_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL</td>
- <td>
- true
- </td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a
name="asyncLoggerThreadNameStrategy"/>log4j2.asyncLoggerThreadNameStrategy
- <br />
- (<a
name="AsyncLogger.ThreadNameStrategy"/>AsyncLogger.ThreadNameStrategy)
- </td>
- <td>LOG4J_ASYNC_LOGGER_THREAD_NAME_STRATEGY</td>
- <td>
- CACHED
- </td>
- <td>
- See <a href="async.html#SysPropsAllAsync">Async Logger System
Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a
name="asyncLoggerConfigExceptionHandler"/>log4j2.asyncLoggerConfigExceptionHandler
- <br />
- (<a
name="AsyncLoggerConfig.ExceptionHandler"/>AsyncLoggerConfig.ExceptionHandler)
- </td>
- <td>LOG4J_ASYNC_LOGGER_CONFIG_EXCEPTION_HANDLER</td>
- <td>default handler</td>
- <td>
- See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous
Logger System Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a
name="asyncLoggerConfigRingBufferSize"/>log4j2.asyncLoggerConfigRingBufferSize
- <br />
- (<a
name="AsyncLoggerConfig.RingBufferSize"/>AsyncLoggerConfig.RingBufferSize)
- </td>
- <td>LOG4J_ASYNC_LOGGER_CONFIG_RING_BUFFER_SIZE</td>
- <td>256 * 1024 or 4 * 1024 in garbage-free mode</td>
- <td>
- See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous
Logger System Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a
name="asyncLoggerConfigWaitStrategy"/>log4j2.asyncLoggerConfigWaitStrategy
- <br />
- (<a
name="AsyncLoggerConfig.WaitStrategy"/>AsyncLoggerConfig.WaitStrategy)
- </td>
- <td>LOG4J_ASYNC_LOGGER_CONFIG_WAIT_STRATEGY</td>
- <td>
- Timeout
- </td>
- <td>
- See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous
Logger System Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a
name="AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull"/>AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull
- </td>
- <td>ASYNC_LOGGER_CONFIG_SYNCHRONIZE_ENQUEUE_WHEN_QUEUE_FULL</td>
- <td>
- true
- </td>
- <td>
- See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous
Logger System Properties</a> for details.
- </td>
- </tr>
- <tr>
- <td><a name="julLoggerAdapter"/>log4j2.julLoggerAdapter
- <br />
- (<a name="log4j.jul.LoggerAdapter"/>log4j.jul.LoggerAdapter)
- </td>
- <td>LOG4J_JUL_LOGGER_ADAPTER</td>
- <!-- deliberately inserted spaces to allow line break -->
- <td>org.apache.logging.log4j .jul.ApiLoggerAdapter</td>
- <td>
- Default LoggerAdapter to use in the JUL adapter. By default, if
log4j-core is available, then the class
- <code>org.apache.logging.log4j.jul .CoreLoggerAdapter</code> will be
used. Otherwise, the
- <code>ApiLoggerAdapter</code> will be used. Custom implementations must
provide a public default constructor.
- </td>
- </tr>
- <tr>
- <td><a name="formatMsgAsync"/>log4j2.formatMsgAsync
- <br />
- (<a name="log4j.format.msg.async"/>log4j.format.msg.async)
- </td>
- <td>LOG4J_FORMAT_MSG_ASYNC</td>
- <td>
- false
- </td>
- <td>
- If <tt>false</tt> (the default), Log4j will make sure the message is
formatted in the caller thread, to ensure
- the value at the time of the call to the logger is the value that is
logged.
- </td>
- </tr>
- <tr>
- <td><a name="asyncQueueFullPolicy"/>log4j2.asyncQueueFullPolicy
- <br />
- (<a name="log4j2.AsyncQueueFullPolicy"/>log4j2.AsyncQueueFullPolicy)
- </td>
- <td>LOG4J_ASYNC_QUEUE_FULL_POLICY</td>
- <td> </td>
- <td>
- <p>Used by Async Loggers and the AsyncAppender to maintain application
throughput even when
- the underlying appender cannot keep up with the logging rate and the
queue is filling up.</p>
- <p>If no value is specified (the default) events are never discarded. If
the queue is full, the
- logger call blocks until the event can be added to the queue.</p>
- <p>Specify <tt>Discard</tt> to drop events whose level is equal or less
than the threshold level
- (INFO by default) when the queue is full.</p>
- </td>
- </tr>
- <tr>
- <td><a name="discardThreshold"/>log4j2.discardThreshold
- <br />
- (<a name="log4j2.DiscardThreshold"/>log4j2.DiscardThreshold)
- </td>
- <td>LOG4J_DISCARD_THRESHOLD</td>
- <td>INFO</td>
- <td>Used by the DiscardingAsyncQueueFullPolicy to determine which events
to drop when the queue
- becomes full. By default, <tt>INFO</tt>, <tt>DEBUG</tt> and
<tt>TRACE</tt> level
- events are discarded when the queue is full.
- This property only has effect if <tt>Discard</tt> is specified as the
- <tt>log4j2.AsyncQueueFullPolicy</tt>.</td>
- </tr>
- <tr>
- <td><a name="messageFactory"/>log4j2.messageFactory
- <br />
- (<a name="log4j2.messageFactory" />log4j2.messageFactory)
- </td>
- <td>LOG4J_MESSAGE_FACTORY</td>
- <td>org.apache.logging.log4j.message. ParameterizedMessageFactory or
- org.apache.logging.log4j.message. ReusableMessageFactory in garbage-free
mode</td>
- <td>Default message factory used by Loggers if no factory was
specified.</td>
- </tr>
- <tr>
- <td><a name="flowMessageFactory"/>log4j2.flowMessageFactory
- <br />
- (<a name="log4j2.flowMessageFactory" />log4j2.flowMessageFactory)
- </td>
- <td>LOG4J_FLOW_MESSAGE_FACTORY</td>
- <td>org.apache.logging.log4j.message. DefaultFlowMessageFactory</td>
- <td>Default flow message factory used by Loggers.</td>
- </tr>
- <tr>
- <td><a name="isWebapp"/>log4j2.isWebapp
- <br />
- (<a name="log4j2.is.webapp"/>log4j2.is.webapp)
- </td>
- <td>LOG4J_IS_WEBAPP</td>
- <td>true if <tt>Servlet</tt> class on class path </td>
- <td>This system property can be used to force Log4j 2 to behave as if it
is part of a web application (when true)
- or as if it is not part of a web application (when false).</td>
- </tr>
- <tr>
- <td><a name="enableThreadlocals"/>log4j2.enableThreadlocals
- <br />
- (<a name="log4j2.enable.threadlocals" />log4j2.enable.threadlocals)
- </td>
- <td>LOG4J_ENABLE_THREADLOCALS</td>
- <td>true</td>
- <td>This system property can be used to switch off the use of
threadlocals, which will partly disable
- Log4j's garbage-free behaviour: to be fully garbage-free, Log4j stores
- objects in ThreadLocal fields to reuse them, otherwise new objects are
created for each log event.
- Note that this property is not effective when Log4j detects it is
running in a web application.</td>
- </tr>
- <tr>
- <td><a name="enableDirectEncoders"/>log4j2.enableDirectEncoders
- <br />
- (<a name="log4j2.enable.direct.encoders" />log4j2.enable.direct.encoders)
- </td>
- <td>LOG4J_ENABLE_DIRECT_ENCODERS</td>
- <td>true</td>
- <td>This property can be used to force garbage-aware Layouts and Appenders
to revert to the
- pre-2.6 behaviour where converting log events to text generates
temporary objects like
- Strings and char[] arrays, and converting this text to bytes generates
temporary byte[] arrays.
- By default, this property is <tt>true</tt> and garbage-aware Layouts and
Appenders that convert log events
- to text will convert this text to bytes without creating temporary
objects.</td>
- </tr>
- <tr>
- <td><a name="initialReusableMsgSize"/>log4j2.initialReusableMsgSize
- <br />
- (<a name="log4j.initialReusableMsgSize" />log4j.initialReusableMsgSize)
- </td>
- <td>LOG4J_INITIAL_REUSABLE_MSG_SIZE</td>
- <td>128</td>
- <td>In GC-free mode, this property determines the initial size of the
reusable StringBuilders where the message
- text is formatted and potentially passed to background threads.</td>
- </tr>
- <tr>
- <td><a name="maxReusableMsgSize"/>log4j2.maxReusableMsgSize
- <br />
- (<a name="log4j.maxReusableMsgSize" />log4j.maxReusableMsgSize)
- </td>
- <td>LOG4J_MAX_REUSABLE_MSG_SIZE</td>
- <td>518</td>
- <td>In GC-free mode, this property determines the maximum size of the
reusable StringBuilders where the message
- text is formatted and potentially passed to background threads.</td>
- </tr>
- <tr>
- <td><a name="layoutStringBuilderMaxSize"/>log4j2.layoutStringBuilderMaxSize
- <br />
- (<a name="log4j.layoutStringBuilder.maxSize"
/>log4j.layoutStringBuilder.maxSize)
- </td>
- <td>LOG4J_LAYOUT_STRING_BUILDER_MAX_SIZE</td>
- <td>2048</td>
- <td>This property determines the maximum size of the thread-local reusable
StringBuilders
- used to format the log event to text by Layouts that extend
AbstractStringLayout.</td>
- </tr>
- <tr>
- <td><a name="unboxRingbufferSize"/>log4j2.unboxRingbufferSize
- <br />
- (<a name="log4j.unbox.ringbuffer.size" />log4j.unbox.ringbuffer.size)
- </td>
- <td>LOG4J_UNBOX_RINGBUFFER_SIZE</td>
- <td>32</td>
- <td>The <tt>org.apache.logging.log4j.util.Unbox</tt> utility
- manages a small thread-local ring buffer of StringBuilders.
- Each time one of the <tt>box()</tt> methods is called, the next slot in
the ring buffer is used, until the ring
- buffer is full and the first slot is reused. By default the Unbox ring
buffer has 32 slots, so user code can
- have up to 32 boxed primitives in a single logger call.
- <p>
- If more slots are required, set system property
<tt>log4j.unbox.ringbuffer.size</tt> to the desired ring buffer size.
- Note that the specified number will be rounded up to the nearest power of
2.</p></td>
- </tr>
- <tr>
- <td><a
name="loggerContextStacktraceOnStart"/>log4j2.loggerContextStacktraceOnStart
- <br />
- (<a name="log4j.LoggerContext.stacktrace.on.start"
/>log4j.LoggerContext.stacktrace.on.start)
- </td>
- <td>LOG4J_LOGGER_CONTEXT_STACKTRACE_ON_START</td>
- <td>false</td>
- <td>Prints a stacktrace to the <a href="#StatusMessages">status logger</a>
at DEBUG level
- when the LoggerContext is started. For debug purposes.</td>
- </tr>
- <tr>
- <td><a name="log4j2.trustStoreLocation "/>log4j2.trustStoreLocation</td>
- <td>LOG4J_TRUST_STORE_LOCATION</td>
- <td></td>
- <td>The location of the trust store. If not provided the default trust
store will be used.</td>
- </tr>
- <tr>
- <td><a name="log4j2.trustStorePassword"/>log4j2.trustStorePassword</td>
- <td>LOG4J_TRUST_STORE_PASSWORD</td>
- <td></td>
- <td>Password needed to access the trust store.</td>
- </tr>
- <tr>
- <td><a
name="log4j2.trustStorePasswordFile"/>log4j2.trustStorePasswordFile</td>
- <td>LOG4J_TRUST_STORE_PASSWORD_FILE</td>
- <td></td>
- <td>The location of a file that contains the password for the trust
store.</td>
- </tr>
- <tr>
- <td><a
name="log4j2.trustStorePasswordEnvironmentVariable"/>log4j2.trustStorePasswordEnvironmentVariable</td>
- <td>LOG4J_TRUST_STORE_PASSWORD_ENVIRONMENT_VARIABLE</td>
- <td></td>
- <td>The name of the environment variable that contains the trust store
password.</td>
- </tr>
- <tr>
- <td><a name="log4j2.trustStoreType"/>log4j2.trustStoreType</td>
- <td>LOG4J_TRUST_STORE_TYPE</td>
- <td></td>
- <td>The type of key store used for the trust store.</td>
- </tr>
- <tr>
- <td><a
name="log4j2.trustStoreKeyManagerFactoryAlgorithm"/>log4j2.trustStoreKeyManagerFactoryAlgorithm</td>
- <td>LOG4J_TRUST_STORE_KEY_MANAGER_FACTORY_ALGORITHM</td>
- <td></td>
- <td>Java cryptographic algorithm.</td>
- </tr>
- <tr>
- <td><a name="log4j2.keyStoreLocation "/>log4j2.keyStoreLocation </td>
- <td>LOG4J_KEY_STORE_LOCATION</td>
- <td></td>
- <td>The location of the key store. If not provided the default key store
will be used.</td>
- </tr>
- <tr>
- <td><a name="log4j2.keyStorePassword"/>log4j2.keyStorePassword</td>
- <td>LOG4J_KEY_STORE_PASSWORD</td>
- <td></td>
- <td>Password needed to access the key store.</td>
- </tr>
- <tr>
- <td><a name="log4j2.keyStorePasswordFile"/>log4j2.keyStorePasswordFile</td>
- <td>LOG4J_KEY_STORE_PASSWORD_FILE</td>
- <td></td>
- <td>The location of a file that contains the password for the key
store.</td>
- </tr>
- <tr>
- <td><a
name="log4j2.keyStorePasswordEnvironmentVariable"/>log4j2.keyStorePasswordEnvironmentVariable</td>
- <td>LOG4J_KEY_STORE_PASSWORD_ENVIRONMENT_VARIABLE</td>
- <td></td>
- <td>The name of the environment variable that contains the key store
password.</td>
- </tr>
- <tr>
- <td><a name="log4j2.keyStoreType"/>log4j2.keyStoreType</td>
- <td>LOG4J_KEY_STORE_TYPE</td>
- <td></td>t
- <td>The type of key store.</td>
- </tr>
- <tr>
- <td><a
name="log4j2.keyStoreKeyManagerFactoryAlgorithm"/>log4j2.keyStoreKeyManagerFactoryAlgorithm</td>
- <td>LOG4J_KEY_STORE_KEY_MANAGER_FACTORY_ALGORITHM</td>
- <td></td>
- <td>Java cryptographic algorithm.</td>
- </tr>
- <tr>
- <td><a name="log4j2.sslVerifyHostName"/>log4j2.sslVerifyHostName</td>
- <td></td>
- <td>false</td>
- <td>true or false if the host name should be verified</td>
- </tr>
- <tr>
- <td><a
name="log4j2.Script.enableLanguages"/>log4j2.Script.enableLanguages</td>
- <td></td>
- <td></td>
- <td>The list of script languages that are allowed to execute. The names
specified must have a ScriptEngine installed
- that advertises the same language(s) in order for scripting to be
enabled. If no languages are specified, which is
- the default, the ScriptManager will not be installed.</td>
- </tr>
- <tr>
- <td><a
name="log4j2.disableCloudConfigLoggingSystem"/>log4j2.disableCloudConfigLoggingSystem</td>
- <td></td>
- <td></td>
- <td>Disables the usage of the Spring Boot
<tt>Log4j2CloudConfigLoggingSystem</tt>. Defaults to <tt>false</tt>.</td>
- </tr>
-</table>
-
- </subsection>
- </section>
- </body>
-</document>
