| <?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="rgoers@apache.org">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> |
| 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="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>"log4j.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="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="http://jmdns.sourceforge.net">http://jmdns.sourceforge.net</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="http://jmdns.sourceforge.net">http://jmdns.sourceforge.net</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="http://commons.apache.org/proper/commons-vfs/">http://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 from <a href="http://jmdns.sourceforge.net">http://jmdns.sourceforge.net</a> |
| to your application classpath in order to advertise with the 'multicastdns' advertiser.</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>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 "trace", "debug", "info", "warn", "error" and "fatal". |
| 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. 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 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 configuerd 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" |
| packages="org.apache.logging.log4j.test"> |
| <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 |
| identifer 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> |
| Properties configuration files support the advertiser, monitorInterval, name, packages, shutdownHook, |
| shutdownTimeout, status, verbose, and dest attrbutes. 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 = ${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.name = com.example.my.app |
| logger.rolling.level = debug |
| logger.rolling.additivity = false |
| logger.rolling.appenderRef.rolling.ref = RollingFile |
| |
| 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" packages="org.apache.logging.log4j.test"> |
| <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" packages="org.apache.logging.log4j.test"> |
| <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>base64</td> |
| <td> |
| Base64 encoded data. The format is <code>${dollar}{base64:Base64_encoded_data}</code>. |
| For example: |
| <code>${dollar}{base64:SGVsbG8gV29ybGQhCg==}</code> yields <code>Hello World!</code>. |
| </td> |
| </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>Thread Context Map (MDC)</td> |
| </tr> |
| <tr> |
| <td>date</td> |
| <td>Inserts the current date and/or time using the specified format</td> |
| </tr> |
| <tr> |
| <td>env</td> |
| <td>System environment variables. The formats are <code>${dollar}{env:ENV_NAME}</code> and <code>${dollar}{env:ENV_NAME:-default_value}</code>.</td> |
| </tr> |
| <tr> |
| <td>jndi</td> |
| <td>A value set in the default JNDI Context.</td> |
| </tr> |
| <tr> |
| <td>jvmrunargs</td> |
| <td> |
| A JVM input argument accessed through JMX, but not a main argument; |
| see <a class="javadoc" href="http://docs.oracle.com/javase/6/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--">RuntimeMXBean.getInputArguments()</a>. |
| Not available on Android.</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>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></td> |
| </tr> |
| <tr> |
| <td>map</td> |
| <td>A value from a MapMessage</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>sys</td> |
| <td>System properties. The formats are <code>${dollar}{sys:some.property}</code> and <code>${dollar}{sys:some.property:-default_value}</code>.</td> |
| </tr> |
| </table> |
| <a name="DefaultProperties"/><h3>Default Properites</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="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="http://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> |
| 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="http://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 exception that the highest status level and the lowest |
| monitorInterval greater than 0 will be used.</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 definiations 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 defined (with any or no value).</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 accomodate 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>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>0</td> |
| <td> |
| Including this file on the classpath can be used as an alternative to providing properties as system |
| properties. This has priority over system properties, but they can be overridden by environment |
| variables as described above. |
| </td> |
| </tr> |
| <tr> |
| <td>System Properties</td> |
| <td>100</td> |
| <td> |
| All properties can be set using normal system property patterns. These have the lowest priority and |
| can be overridden by included properties files or environment variables. |
| </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>Environemt 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 defined (with any or no value). |
| </td> |
| </tr> |
| <tr> |
| <td><a name="mergeFactory"/>log4j2.mergeFactory |
| <br /> |
| (<a name="log4j.mergeFactory"/>log4j.mergeFactory) |
| </td> |
| <td>LOG4J_MERGE_FACTORY</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.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="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="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="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>ApiLogggerAdapter</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="formatMsgNoLookups"/>log4j2.formatMsgNoLookups |
| <br /> |
| (<a name="log4j2.formatMsgNoLookups" />log4j2.formatMsgNoLookups) |
| </td> |
| <td>FORMAT_MESSAGES_PATTERN_DISABLE_LOOKUPS</td> |
| <td>false</td> |
| <td>Disables message pattern lookups globally when set to <tt>true</tt>. |
| This is equivalent to defining all message patterns using <tt>%m{nolookups}</tt>.</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> |
| </table> |
| |
| </subsection> |
| </section> |
| </body> |
| </document> |