| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| 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. |
| --> |
| <!-- Generated by Apache Maven Doxia at Feb 22, 2015 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title> |
| Configuring Log4j 2 - Apache Log4j 2</title> |
| <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" /> |
| <link rel="stylesheet" href="../css/site.css" type="text/css" /> |
| <script type="text/javascript" src="../js/jquery.min.js"></script> |
| <script type="text/javascript" src="../js/bootstrap.min.js"></script> |
| <script type="text/javascript" src="../js/prettify.min.js"></script> |
| <script type="text/javascript" src="../js/site.js"></script> |
| <meta name="author" content="Ralph Goers" /> |
| <meta name="Date-Revision-yyyymmdd" content="20150222" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| </head> |
| <body class="composite"> |
| <img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" /> |
| <img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" /> |
| <div class="clear"></div> |
| |
| <div class="navbar"> |
| <div class="navbar-inner"> |
| <div class="container-fluid"> |
| <a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 ™</a> |
| <ul class="nav"> |
| <li> |
| |
| |
| <a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| <li> |
| |
| |
| <a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a> |
| </li> |
| <li> |
| <a href="../../../" title="Logging Services">Logging Services</a> |
| </li> |
| <li> |
| |
| |
| <a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="external" target="_blank" title="Sonar">Sonar</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container-fluid"> |
| <table class="layout-table"> |
| <tr> |
| <td class="sidebar"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li> |
| <li class="none"> |
| <a href="../index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="../download.html" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="../maven-artifacts.html" title="Maven and Ivy">Maven and Ivy</a> |
| </li> |
| <li class="none"> |
| <a href="../build.html" title="Build">Build</a> |
| </li> |
| <li class="none"> |
| <a href="../guidelines.html" title="Guidelines">Guidelines</a> |
| </li> |
| <li class="none"> |
| <a href="../javastyle.html" title="Style Guide">Style Guide</a> |
| </li> |
| <li class="none"> |
| <a href="../changelog.html" title="Changelog">Changelog</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../javadoc.html" title="Javadoc">Javadoc</a> |
| </li> |
| <li class="none"> |
| <a href="../runtime-dependencies.html" title="Runtime Dependencies">Runtime Dependencies</a> |
| </li> |
| <li class="none"> |
| <a href="../faq.html" title="FAQ">FAQ</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-book"></i>Manual</li> |
| <li class="none"> |
| <a href="../manual/index.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/architecture.html" title="Architecture">Architecture</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/api.html" title="API">API</a> |
| </li> |
| <li class="expanded active"> |
| <a href="../manual/configuration.html" title="Configuration">Configuration</a> |
| <ul> |
| <li class="none"> |
| <a href="../manual/configuration.html#AutomaticConfiguration" title="Automatic Configuration">Automatic Configuration</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#Additivity" title="Additivity">Additivity</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#AutomaticReconfiguration" title="Automatic Reconfiguration">Automatic Reconfiguration</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#ChainsawSupport" title="Chainsaw Support">Chainsaw Support</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#ConfigurationSyntax" title="Configuration Syntax">Configuration Syntax</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#XML" title="XML Syntax">XML Syntax</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#JSON" title="JSON Syntax">JSON Syntax</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#Loggers" title="Configuring Loggers">Configuring Loggers</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#Appenders" title="Configuring Appenders">Configuring Appenders</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#Filters" title="Configuring Filters">Configuring Filters</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#PropertySubstitution" title="Property Substitution">Property Substitution</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#XInclude" title="XInclude">XInclude</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#StatusMessages" title="Status Messages">Status Messages</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#UnitTestingInMaven" title="Unit Testing in Maven">Unit Testing in Maven</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/configuration.html#SystemProperties" title="System Properties">System Properties</a> |
| </li> |
| </ul> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/webapp.html" title="Web Applications and JSPs">Web Applications and JSPs</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/plugins.html" title="Plugins">Plugins</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/lookups.html" title="Lookups">Lookups</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/appenders.html" title="Appenders">Appenders</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/layouts.html" title="Layouts">Layouts</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/filters.html" title="Filters">Filters</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/async.html" title="Async Loggers">Async Loggers</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/jmx.html" title="JMX">JMX</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/customconfig.html" title="Extending Log4j Configuration">Extending Log4j Configuration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/customloglevels.html" title="Custom Log Levels">Custom Log Levels</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Components</li> |
| <li class="none"> |
| <a href="../log4j-api/index.html" title="API">API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-core/index.html" title="Implementation">Implementation</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API">Log4j 1.2 API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-jul/index.html" title="JUL Adapter">JUL Adapter</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-flume-ng/index.html" title="Apache Flume Appender">Apache Flume Appender</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI">Log4j JMX GUI</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-web/index.html" title="Log4j Web Application Support">Log4j Web Application Support</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-nosql/index.html" title="Log4j NoSQL support">Log4j NoSQL support</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-iostreams/index.html" title="Log4j IO Streams">Log4j IO Streams</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li> |
| <li class="none"> |
| <a href="../dependencies.html" title="Dependencies">Dependencies</a> |
| </li> |
| <li class="none"> |
| <a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a> |
| </li> |
| <li class="none"> |
| <a href="../dependency-management.html" title="Dependency Management">Dependency Management</a> |
| </li> |
| <li class="none"> |
| <a href="../team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="../license.html" title="Project License">Project License</a> |
| </li> |
| <li class="none"> |
| <a href="../source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| <li class="none"> |
| <a href="../project-summary.html" title="Project Summary">Project Summary</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Project Reports</li> |
| <li class="none"> |
| <a href="../changes-report.html" title="Changes Report">Changes Report</a> |
| </li> |
| <li class="none"> |
| <a href="../jira-report.html" title="JIRA Report">JIRA Report</a> |
| </li> |
| <li class="none"> |
| <a href="../surefire-report.html" title="Surefire Report">Surefire Report</a> |
| </li> |
| <li class="none"> |
| <a href="../rat-report.html" title="RAT Report">RAT Report</a> |
| </li> |
| </ul> |
| </div> |
| <div id="poweredBy"> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" /> |
| </a> |
| </div> |
| </td> |
| <td class="content"> |
| <!-- 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. --> |
| |
| <div class="section"><h2>Configuration<a name="Configuration"></a></h2> |
| <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 style="list-style-type: decimal"> |
| <li>Through a configuration file written in XML, JSON, or YAML.</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>. |
| </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"></a> |
| <div class="section"><h3>Automatic Configuration<a name="Automatic_Configuration"></a></h3> |
| <p> |
| Log4j has the ability to automatically configure itself during initialization. |
| When Log4j starts it will locate all the ConfigurationFactory plugins and arrange then in weighted |
| order from highest to lowest. As delivered, Log4j contains three ConfigurationFactory implementations: |
| one for JSON, one for YAML, and one for XML. |
| </p> |
| <ol style="list-style-type: decimal"> |
| <li>Log4j will inspect the <tt>"log4j.configurationFile"</tt> system property and, if set, will attempt to |
| load the configuration using the <tt>ConfigurationFactory</tt> that matches the file |
| extension.</li> |
| <li>If no system property is set the YAML ConfigurationFactory will look for |
| <tt>log4j2-test.yaml</tt> or <tt>log4j2-test.yml</tt> in the classpath.</li> |
| <li>If no such file is found the JSON ConfigurationFactory will look for |
| <tt>log4j2-test.json</tt> or <tt>log4j2-test.jsn</tt> in the classpath.</li> |
| <li>If no such file is found the XML ConfigurationFactory will look for |
| <tt>log4j2-test.xml</tt> in the classpath.</li> |
| <li>If a test file cannot be located the YAML ConfigurationFactory will look for |
| <tt>log4j2.yaml</tt> or <tt>log4j2.yml</tt> on the classpath.</li> |
| <li>If a YAML file cannot be located the JSON ConfigurationFactory will look for |
| <tt>log4j2.json</tt> or <tt>log4j2.jsn</tt> on the classpath.</li> |
| <li>If a JSON file cannot be located the XML ConfigurationFactory will try to locate |
| <tt>log4j2.xml</tt> on the classpath.</li> |
| <li>If no configuration file could be located the <tt>DefaultConfiguration</tt> will |
| be used. This will cause logging output to go to the console.</li> |
| </ol> |
| <p>An example application named <tt>MyApp</tt> that uses log4j can be used to illustrate how |
| this is done. |
| </p> |
| <div class="prettyprint linenums"><pre> |
| 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></div> |
| <p> |
| <tt>MyApp</tt> begins by importing log4j related classes. It |
| then defines a static logger variable with the name <tt>MyApp</tt> |
| which happens to be the fully qualified name of the class. |
| </p> |
| <p> |
| <tt>MyApp</tt> uses the <tt>Bar</tt> class defined in the package<tt>com.foo</tt>. |
| </p> |
| <div class="prettyprint linenums"><pre> |
| 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></div> |
| <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 href="../log4j-core/apidocs/org/apache/logging/log4j/core/appender/ConsoleAppender.html" class="javadoc">ConsoleAppender</a> |
| attached to the root logger.</li> |
| <li>A <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/layout/PatternLayout.html" class="javadoc">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 <tt>Level.ERROR</tt>. |
| </p> |
| <p>The output of MyApp would be similar to: |
| </p> |
| <div><pre> |
| 17:13:01.540 [main] ERROR com.foo.Bar - Did it again! |
| 17:13:01.540 [main] ERROR MyApp - Didn't do it. |
| </pre></div> |
| <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> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| <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> |
| <div><pre> |
| 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></div> |
| <p> |
| Note that status logging is disabled when the default configuration is used. |
| </p> |
| <p> |
| Perhaps it is desired to eliminate all the TRACE output from everything except <tt>com.foo.Bar</tt>. |
| Simply changing the log level would not accomplish the task. Instead, the solution is to |
| add a new logger definition to the configuration: |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <Logger name="com.foo.Bar" level="TRACE"/> |
| <Root level="ERROR"> |
| <AppenderRef ref="STDOUT"> |
| </Root> |
| </pre></div> |
| <p> |
| With this configuration all log events from <tt>com.foo.Bar</tt> will be recorded while only error |
| events will be recorded from all other components. |
| </p> |
| </div> |
| <a name="Additivity"></a> |
| <div class="section"><h3>Additivity<a name="Additivity"></a></h3> |
| <p> |
| In the previous example all the events from <tt>com.foo.Bar</tt> were still written to the Console. This is |
| because the logger for <tt>com.foo.Bar</tt> did not have any appenders configured while its parent did. In fact, |
| the following configuration |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| <p>would result in</p> |
| <div><pre> |
| 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></div> |
| <p>Notice that the trace messages from <tt>com.foo.Bar</tt> appear twice. This is because the appender associated |
| with logger <tt>com.foo.Bar</tt> is first used, which writes the first instance to the Console. Next, the parent |
| of <tt>com.foo.Bar</tt>, 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> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| <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> |
| </div> |
| <a name="AutomaticReconfiguration"></a> |
| <div class="section"><h3>Automatic Reconfiguration<a name="Automatic_Reconfiguration"></a></h3> |
| <p> |
| When configured from a File, Log4j has the ability to automatically detect changes to the configuration |
| file and reconfigure itself. If the monitorInterval 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> |
| <div class="prettyprint linenums"><pre> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <Configuration monitorInterval="30"> |
| ... |
| </Configuration> |
| </pre></div> |
| </div> |
| <a name="ChainsawSupport"></a> |
| <div class="section"><h3>Chainsaw can automatically process your log files (Advertising appender configurations)<a name="Chainsaw_can_automatically_process_your_log_files_Advertising_appender_configurations"></a></h3> |
| <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 class="externalLink" 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 class="externalLink" 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 class="externalLink" 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 class="externalLink" href="http://jmdns.sourceforge.net">http://jmdns.sourceforge.net</a> |
| to your application classpath in order to advertise with the 'multicastdns' advertiser.</b> |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| </div> |
| <a name="ConfigurationSyntax"></a> |
| <div class="section"><h3>Configuration Syntax<a name="Configuration_Syntax"></a></h3> |
| <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> |
| <a name="XML"></a> |
| <div class="section"><h4>Configuration with XML<a name="Configuration_with_XML"></a></h4> |
| <p> |
| The configuration element in the XML file accepts several attributes: |
| </p> |
| <table border="0" class="bodyTable"> |
| <tr class="a"> |
| <th>Attribute Name</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <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 class="a"> |
| <td>dest</td> |
| <td>Either "err", which will send output to stderr, or a file path or URL.</td> |
| </tr> |
| |
| <tr class="b"> |
| <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 class="a"> |
| <td>name</td> |
| <td>The name of the configuration.</td> |
| </tr> |
| <tr class="b"> |
| <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 class="a"> |
| <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 class="b"> |
| <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 class="a"> |
| <td>status</td> |
| <td>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.</td> |
| </tr> |
| <tr class="b"> |
| <td>strict</td> |
| <td>Enables the use of the strict XML format. Not supported in JSON configurations.</td> |
| </tr> |
| <tr class="a"> |
| <td>verbose</td> |
| <td>Enables diagnostic information while loading plugins.</td> |
| </tr> |
| </table> |
| <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> |
| <div class="prettyprint"><pre><PatternLayout pattern="%m%n"/></pre></div> |
| <p>and</p> |
| <div class="prettyprint"><pre> |
| <PatternLayout> |
| <Pattern>%m%n</Pattern> |
| </PatternLayout></pre></div> |
| <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> |
| |
| <div class="prettyprint linenums"><pre> |
| <?xml version="1.0" encoding="UTF-8"?>; |
| <Configuration> |
| <Properties> |
| <Property name="name1">value</property> |
| <Property name="name2" value="value2"/> |
| </Properties> |
| <<i>filter</i> ... /> |
| <Appenders> |
| <<i>appender</i> ... > |
| <<i>filter</i> ... /> |
| </<i>appender</i>> |
| ... |
| </Appenders> |
| <Loggers> |
| <Logger name="name1"> |
| <<i>filter</i> ... /> |
| </Logger> |
| ... |
| <Root level="level"> |
| <AppenderRef ref="name"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </pre></div> |
| <p> |
| See the many examples on this page for sample appender, filter and logger declarations. |
| </p> |
| <div class="section"><h5>Strict XML<a name="Strict_XML"></a></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> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| <p> |
| Below is a sample configuration using the strict format. |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <?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="${filename}"> |
| <Layout type="PatternLayout"> |
| <Pattern>%d %p %C{1.} [%t] %m%n</Pattern> |
| </Layout> |
| </Appender> |
| <Appender type="List" name="List"> |
| </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="List"/> |
| </Root> |
| </Loggers> |
| |
| </Configuration> |
| </pre></div> |
| <a name="JSON"></a> |
| </div></div><div class="section"><h4>Configuration with JSON<a name="Configuration_with_JSON"></a></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> |
| <div class="prettyprint linenums"><pre> |
| { "configuration": { "status": "error", "name": "RoutingTest", |
| "packages": "org.apache.logging.log4j.test", |
| "properties": { |
| "property": { "name": "filename", |
| "value" : "target/rolling1/rollingtest-$${sd:type}.log" } |
| }, |
| "ThresholdFilter": { "level": "debug" }, |
| "appenders": { |
| "Console": { "name": "STDOUT", |
| "PatternLayout": { "pattern": "%m%n" } |
| }, |
| "List": { "name": "List", |
| "ThresholdFilter": { "level": "debug" } |
| }, |
| "Routing": { "name": "Routing", |
| "Routes": { "pattern": "$${sd:type}", |
| "Route": [ |
| { |
| "RollingFile": { |
| "name": "Rolling-${sd:type}", "fileName": "${filename}", |
| "filePattern": "target/rolling1/test1-${sd:type}.%i.log.gz", |
| "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"}, |
| "SizeBasedTriggeringPolicy": { "size": "500" } |
| } |
| }, |
| { "AppenderRef": "STDOUT", "key": "Audit"}, |
| { "AppenderRef": "List", "key": "Service"} |
| ] |
| } |
| } |
| }, |
| "loggers": { |
| "logger": { "name": "EventLogger", "level": "info", "additivity": "false", |
| "AppenderRef": { "ref": "Routing" }}, |
| "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }} |
| } |
| } |
| } |
| </pre></div> |
| <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> |
| <div class="prettyprint linenums"><pre> |
| { "configuration": { "status": "debug", "name": "RoutingTest", |
| "packages": "org.apache.logging.log4j.test", |
| "properties": { |
| "property": { "name": "filename", |
| "value" : "target/rolling1/rollingtest-$${sd:type}.log" } |
| }, |
| "ThresholdFilter": { "level": "debug" }, |
| "appenders": { |
| "appender": [ |
| { "type": "Console", "name": "STDOUT", "PatternLayout": { "pattern": "%m%n" }}, |
| { "type": "List", "name": "List", "ThresholdFilter": { "level": "debug" }}, |
| { "type": "Routing", "name": "Routing", |
| "Routes": { "pattern": "$${sd:type}", |
| "Route": [ |
| { |
| "RollingFile": { |
| "name": "Rolling-${sd:type}", "fileName": "${filename}", |
| "filePattern": "target/rolling1/test1-${sd:type}.%i.log.gz", |
| "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"}, |
| "SizeBasedTriggeringPolicy": { "size": "500" } |
| } |
| }, |
| { "AppenderRef": "STDOUT", "key": "Audit"}, |
| { "AppenderRef": "List", "key": "Service"} |
| ] |
| } |
| } |
| ] |
| }, |
| "loggers": { |
| "logger": [ |
| { "name": "EventLogger", "level": "info", "additivity": "false", |
| "AppenderRef": { "ref": "Routing" }}, |
| { "name": "com.foo.bar", "level": "error", "additivity": "false", |
| "AppenderRef": { "ref": "Console" }} |
| ], |
| "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }} |
| } |
| } |
| } |
| </pre></div> |
| <p> |
| The JSON support uses the Jackson Data Processor to parse the JSON files. These dependencies must be added |
| to a project that wants to use JSON for configuration: |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <dependency> |
| <groupId>com.fasterxml.jackson.core</groupId> |
| <artifactId>jackson-core</artifactId> |
| <version>2.5.1</version> |
| </dependency> |
| |
| <dependency> |
| <groupId>com.fasterxml.jackson.core</groupId> |
| <artifactId>jackson-databind</artifactId> |
| <version>2.5.1</version> |
| </dependency> |
| |
| <dependency> |
| <groupId>com.fasterxml.jackson.core</groupId> |
| <artifactId>jackson-annotations</artifactId> |
| <version>2.5.1</version> |
| </dependency> |
| </pre></div> |
| <a name="Loggers"></a> |
| </div><div class="section"><h4>Configuring loggers<a name="Configuring_loggers"></a></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 <tt>logger</tt> element. The <tt>logger</tt> 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 false will be used. |
| </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><i>Every configuration must have a root logger</i></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 style="list-style-type: decimal"> |
| <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"></a> |
| </div><div class="section"><h4>Configuring Appenders<a name="Configuring_Appenders"></a></h4> |
| <p> |
| An appender is configured either using the specific appender plugin's name or with an appender |
| element and the type attibute 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"></a> |
| </div><div class="section"><h4>Configuring Filters<a name="Configuring_Filters"></a></h4> |
| <p> |
| Log4j allows a filter to be specified in any of 4 places: |
| </p> |
| <ol style="list-style-type: decimal"> |
| <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 <tt>filter</tt> element can be configured, that element may be the |
| <tt>filters</tt> element which represents the CompositeFilter. The <tt>filters</tt> element |
| allows any number of <tt>filter</tt> elements to be configured within it. The following example |
| shows how multiple filters can be configured on the ConsoleAppender. |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <?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="${filename}"> |
| <PatternLayout> |
| <pattern>%d %p %C{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| </File> |
| <List name="List"> |
| </List> |
| </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">${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="List"/> |
| </Root> |
| </Loggers> |
| |
| </Configuration> |
| </pre></div> |
| </div></div> |
| <a name="PropertySubstitution"></a> |
| <div class="section"><h3>Property Substitution<a name="Property_Substitution"></a></h3> |
| <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 class="externalLink" href="https://commons.apache.org/proper/commons-lang/">Apache Commons Lang</a>'s |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrSubstitutor.html" class="javadoc">StrSubstitutor</a> |
| and <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html" class="javadoc">StrLookup</a> |
| classes. In a manner similar to Ant or Maven, this allows variables declared as <tt>${name}</tt> |
| 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> |
| <div class="prettyprint linenums"><pre> |
| <?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-$${sd:type}.log</Property> |
| </Properties> |
| <ThresholdFilter level="debug"/> |
| |
| <Appenders> |
| <Console name="STDOUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <List name="List"> |
| <ThresholdFilter level="debug"/> |
| </List> |
| <Routing name="Routing"> |
| <Routes pattern="$${sd:type}"> |
| <Route> |
| <RollingFile name="Rolling-${sd:type}" fileName="${filename}" |
| filePattern="target/rolling1/test1-${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"/> |
| <Route ref="List" key="Service"/> |
| </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></div> |
| <p> |
| While this is useful, there are many more places properties can originate from. To accommodate this, |
| Log4j also supports the syntax <tt>${prefix:name}</tt> where the prefix identifies tells Log4j |
| that variable name should be evaluated in a specific context. The contexts that are built in to Logj4 |
| are: |
| </p> |
| <table border="0" class="bodyTable"> |
| <tr class="a"> |
| <th>Prefix</th> |
| <th>Context</th> |
| </tr> |
| <tr class="b"> |
| <td>bundle</td> |
| <td> |
| Resource bundle. The format is <tt>${bundle:BundleName:BundleKey}</tt>. |
| The bundle name follows package naming conventions, for example: |
| <tt>${bundle:com.domain.Messages:MyKey}</tt>. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>ctx</td> |
| <td>Thread Context Map (MDC)</td> |
| </tr> |
| <tr class="b"> |
| <td>date</td> |
| <td>Inserts the current date and/or time using the specified format</td> |
| </tr> |
| <tr class="a"> |
| <td>env</td> |
| <td>System environment variables</td> |
| </tr> |
| <tr class="b"> |
| <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 class="a"> |
| <td>main</td> |
| <td>A value set with <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/MapLookup.html#setMainArguments-java.lang.String:A-" class="javadoc">MapLookup.setMainArguments(String[])</a></td> |
| </tr> |
| <tr class="b"> |
| <td>map</td> |
| <td>A value from a MapMessage</td> |
| </tr> |
| <tr class="a"> |
| <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 class="b"> |
| <td>sys</td> |
| <td>System properties</td> |
| </tr> |
| </table> |
| <p> |
| A default property map can be declared in the configuration file. 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. |
| </p> |
| <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 variable is simply removed. Thus, when the Routes element is evaluated |
| at runtime it is the variable declaration "${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> |
| <div class="prettyprint linenums"><pre> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <Configuration> |
| <Properties> |
| <Property name="type">Audit</property> |
| </Properties> |
| ... |
| </Configuration> |
| </pre></div> |
| <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> |
| </div> |
| <a name="XInclude"></a> |
| <div class="section"><h3>XInclude<a name="XInclude"></a></h3> |
| <p> |
| XML configuration files can include other files with <a class="externalLink" href="http://www.xml.com/lpt/a/1009">XInclude</a>. |
| Here is an example log4j2.xml file that includes two other files: |
| </p> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| <p>log4j-xinclude-appenders.xml:</p> |
| <div class="prettyprint linenums"><pre> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <appenders> |
| <Console name="STDOUT"> |
| <PatternLayout pattern="%m%n" /> |
| </Console> |
| <File name="File" fileName="${filename}" bufferedIO="true" immediateFlush="true"> |
| <PatternLayout> |
| <pattern>%d %p %C{1.} [%t] %m%n</pattern> |
| </PatternLayout> |
| </File> |
| </appenders> |
| </pre></div> |
| <p>log4j-xinclude-loggers.xml:</p> |
| <div class="prettyprint linenums"><pre> |
| <?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></div> |
| </div> |
| <a name="StatusMessages"></a> |
| <div class="section"><h3>Status Messages<a name="Status_Messages"></a></h3> |
| <table border="0" class="bodyTable"> |
| <tr class="a"> |
| <td> |
| <b>Troubleshooting tip for the impatient:</b> |
| <ul> |
| <li>Before a configuration is found, status logger level can be controlled with system |
| property <tt>org.apache.logging.log4j.simplelog.StatusLogger.level</tt>.</li> |
| <li>After a configuration is found, status logger level can be controlled in the configuration |
| file with the "status" attribute, for example: <tt><Configuration status="trace"></tt>.</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 href="../log4j-api/apidocs/org/apache/logging/log4j/status/StatusLogger.html" class="javadoc">StatusLogger</a>. |
| Components declare an instance of the StatusLogger similar to: |
| </p> |
| <div class="prettyprint"><pre>protected final static Logger logger = StatusLogger.getLogger();</pre></div> |
| <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> |
| |
| <div class="prettyprint linenums"><pre> |
| <?xml version="1.0" encoding="UTF-8"?>; |
| <Configuration status="debug" name="RoutingTest"> |
| <Properties> |
| <Property name="filename">target/rolling1/rollingtest-$${sd:type}.log</Property> |
| </Properties> |
| <ThresholdFilter level="debug"/> |
| |
| <Appenders> |
| <Console name="STDOUT"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| <List name="List"> |
| <ThresholdFilter level="debug"/> |
| </List> |
| <Routing name="Routing"> |
| <Routes pattern="$${sd:type}"> |
| <Route> |
| <RollingFile name="Rolling-${sd:type}" fileName="${filename}" |
| filePattern="target/rolling1/test1-${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"/> |
| <Route ref="List" key="Service"/> |
| </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></div> |
| <p> |
| During startup this configuration produces: |
| </p> |
| <div><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-${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-${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,806 DEBUG Calling createAppender on class org.apache.logging.log4j.test.appender.ListAppender for element List with params(name="List", entryPerNewLine="null", raw="null", null, ThresholdFilter(DEBUG)) |
| 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,824 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="List", key="Service", 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="${sd:type}", routes={Route(type=dynamic default), Route(type=static Reference=STDOUT key='Audit'), Route(type=static Reference=List key='Service')}) |
| 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'),Route(type=static Reference=List key='Service')}), 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, List, 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$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$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></div> |
| <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> |
| <div class="prettyprint linenums"><pre> |
| <logger name="EventLogger" level="info" additivity="false"> |
| <AppenderRef ref="Routng"/> |
| </logger> |
| </pre></div> |
| <p> |
| the following error message will be produced. |
| </p> |
| <div><pre>2011-11-24 23:21:25,517 ERROR Unable to locate appender Routng for logger EventLogger</pre></div> |
| <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> |
| <div class="prettyprint linenums"><pre> |
| StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR); |
| StatusLogger.getLogger().registerListener(listener); |
| </pre></div> |
| </div> |
| <a name="UnitTestingInMaven"></a> |
| <div class="section"><h3>Testing in Maven<a name="Testing_in_Maven"></a></h3> |
| <p> |
| Maven can run unit and functional tests during the build cycle. By default, any files placed in |
| <tt>src/test/resources</tt> 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 <tt>InitialLoggerContext</tt> |
| JUnit test rule which provides additional convenience methods for testing. This requires adding the |
| <tt>log4j-core</tt> <tt>test-jar</tt> dependency to your test scope dependencies. For example: |
| </p> |
| <div class="prettyprint linenums"><pre> |
| public class AwesomeTest { |
| @Rule |
| public InitialLoggerContext init = new InitialLoggerContext("MyTestConfig.xml"); |
| |
| @Test |
| public void testSomeAwesomeFeature() { |
| final LoggerContext ctx = init.getContext(); |
| 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></div> |
| </div> |
| <a name="SystemProperties"></a> |
| <div class="section"><h3>System Properties<a name="System_Properties"></a></h3> |
| <p> |
| Below follows a number of system properties that can be used to control Log4j 2 behaviour. |
| Any spaces present in the property name are for visual flow and should be removed. |
| </p> |
| <table border="0" class="bodyTable"><caption align="top">Log4j 2 System Properties</caption> |
| |
| <tr class="a"> |
| <th>System Property</th> |
| <th>Default Value</th> |
| <th>Description</th> |
| </tr> |
| <tr class="b"> |
| <td>log4j.configurationFile</td> |
| <td> </td> |
| <td> |
| Path to an XML or JSON Log4j 2 configuration file. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>Log4jContextSelector</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 class="b"> |
| <td>Log4jLogEventFactory</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 class="a"> |
| <td>log4j2.loggerContextFactory</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 class="b"> |
| <td>log4j.configurationFactory</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 class="a"> |
| <td>log4j.shutdownHookEnabled</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 class="b"> |
| <td>log4j.shutdownCallbackRegistry</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 href="../log4j-core/apidocs/org/apache/logging/log4j/core/util/ShutdownCallbackRegistry.html" class="javadoc">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 class="a"> |
| <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 class="b"> |
| <td>org.apache.logging.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 class="a"> |
| <td>disableThreadContext</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 class="b"> |
| <td>disableThreadContextStack</td> |
| <td>false</td> |
| <td> |
| If <tt>true</tt>, the ThreadContext stack is disabled. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>disableThreadContextMap</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 class="b"> |
| <td>log4j2.threadContextMap</td> |
| <td> </td> |
| <td> |
| Fully specified class name of a custom <tt>ThreadContextMap</tt> implementation class. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>isThreadContextMapInheritable</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 class="b"> |
| <td>log4j2.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 class="a"> |
| <td>log4j2.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 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 class="b"> |
| <td>log4j.skipJansi</td> |
| <td>false</td> |
| <td> |
| If <tt>true</tt>, the ConsoleAppender will not try to use the Jansi output stream on Windows. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>log4j.ignoreTCL</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 class="b"> |
| <td>org.apache.logging.log4j.uuidSequence</td> |
| <td>0</td> |
| <td> |
| System property that may be used to seed the UUID generation with an integer value. |
| </td> |
| </tr> |
| <!-- <tr> |
| <td>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 class="a"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog .showContextMap</td> |
| <td>false</td> |
| <td>If <tt>true</tt>, the full ThreadContext map is included in each SimpleLogger log message.</td> |
| </tr> |
| <tr class="b"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.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 class="a"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog .showShortLogname</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 class="b"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog .showdatetime</td> |
| <td>false</td> |
| <td>If <tt>true</tt>, SimpleLogger log messages contain timestamp information. |
| </td> |
| </tr> |
| <tr class="a"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog .dateTimeFormat</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 class="b"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.logj.simplelog .logFile</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 class="a"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog .level</td> |
| <td>ERROR</td> |
| <td>Default level for new SimpleLogger instances. |
| </td> |
| </tr> |
| <tr class="b"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog.<loggerName>level</td> |
| <td>SimpleLogger default log level</td> |
| <td>Log level for a the SimpleLogger instance with the specified name.</td> |
| </tr> |
| <tr class="a"> |
| <!-- deliberately inserted spaces to allow line break --> |
| <td>org.apache.logging.log4j.simplelog .StatusLogger.level</td> |
| <td>ERROR</td> |
| <td>This property is used to control the initial StatusLogger level, and can be overridden in code by calling |
| <tt>StatusLogger.getLogger().setLevel(someLevel)</tt>. |
| 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 class="b"> |
| <td>Log4jDefaultStatusLevel</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 class="a"> |
| <td>log4j2.StatusLogger.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 |
| <tt><Configuration status="trace"></tt>, 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 <tt>StatusLogger.getLogger().getLevel()</tt> |
| (see property <tt>org.apache.logging.log4j.simplelog .StatusLogger.level</tt>).</p> |
| </td> |
| </tr> |
| <tr class="b"> |
| <td>log4j2.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 class="a"> |
| <td>AsyncLogger.ExceptionHandler</td> |
| <td>  |
| </td> |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="b"> |
| <td>AsyncLogger.RingBufferSize</td> |
| <td>256 * 1024</td> |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>AsyncLogger.WaitStrategy</td> |
| <td> |
| Sleep |
| </td> |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="b"> |
| <td>AsyncLogger.ThreadNameStrategy</td> |
| <td> |
| CACHED |
| </td> |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>AsyncLoggerConfig.ExceptionHandler</td> |
| <td>  </td> |
| <td> |
| See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="b"> |
| <td>AsyncLoggerConfig.RingBufferSize</td> |
| <td>256 * 1024</td> |
| <td> |
| See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="a"> |
| <td>AsyncLoggerConfig.WaitStrategy</td> |
| <td> |
| Sleep |
| </td> |
| <td> |
| See <a href="async.html#SysPropsMixedSync-Async">Mixed Async/Synchronous Logger System Properties</a> for details. |
| </td> |
| </tr> |
| <tr class="b"> |
| <td>log4j.jul.LoggerAdapter</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 |
| <tt>org.apache.logging.log4j.jul .CoreLoggerAdapter</tt> will be used. Otherwise, the |
| <tt>ApiLogggerAdapter</tt> will be used. Custom implementations must provide a public default constructor. |
| </td> |
| </tr> |
| </table> |
| |
| </div> |
| </div> |
| |
| |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| <div class="footer"> |
| <p>Copyright © 1999-2015 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p> |
| <p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| <p>Site powered by <a class="external" href="http://getbootstrap.com/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p> |
| </div> |
| </div> |
| </body> |
| </html> |
