| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.9.1 from src/site/xdoc/manual/configuration.xml.vm at 2020-02-25 |
| | Rendered using Apache Maven Fluido Skin 1.8 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.9.1" /> |
| <meta name="author" content="Ralph Goers" /> |
| <title>Log4j – Configuring Log4j 2</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.8.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.8.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="http://logging.apache.org" id="bannerLeft"><img src="../images/ls-logo.jpg" alt=""/></a></div> |
| <div class="pull-right"><a href="http://logging.apache.org/log4j/2.x" id="bannerRight"><img src="../images/logo.png" alt=""/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2020-02-25<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.13.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://analysis.apache.org/dashboard/index/org.apache.logging.log4j:log4j" class="externalLink" title="Sonar">Sonar</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" border="0"/> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="icon-chevron-right"></span>Javadoc</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../changelog.html" title="Changelog"><span class="none"></span>Changelog</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" border="0"/> For Contributors</li> |
| <li><a href="../build.html" title="Building Log4j from Source"><span class="none"></span>Building Log4j from Source</a></li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" border="0"/> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/compatibility.html" title="Log4j 1.x Compatibility"><span class="none"></span>Log4j 1.x Compatibility</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="none"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../manual/scala-api.html" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li class="active"><a href="#"><span class="icon-chevron-down"></span>Configuration</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/configuration.html#AutomaticConfiguration" title="Automatic Configuration"><span class="none"></span>Automatic Configuration</a></li> |
| <li><a href="../manual/configuration.html#Additivity" title="Additivity"><span class="none"></span>Additivity</a></li> |
| <li><a href="../manual/configuration.html#AutomaticReconfiguration" title="Automatic Reconfiguration"><span class="none"></span>Automatic Reconfiguration</a></li> |
| <li><a href="../manual/configuration.html#ChainsawSupport" title="Chainsaw Support"><span class="none"></span>Chainsaw Support</a></li> |
| <li><a href="../manual/configuration.html#ConfigurationSyntax" title="Configuration Syntax"><span class="none"></span>Configuration Syntax</a></li> |
| <li><a href="../manual/configuration.html#XML" title="XML Syntax"><span class="none"></span>XML Syntax</a></li> |
| <li><a href="../manual/configuration.html#JSON" title="JSON Syntax"><span class="none"></span>JSON Syntax</a></li> |
| <li><a href="../manual/configuration.html#YAML" title="YAML Syntax"><span class="none"></span>YAML Syntax</a></li> |
| <li><a href="../manual/configuration.html#Properties" title="Properties Syntax"><span class="none"></span>Properties Syntax</a></li> |
| <li><a href="../manual/configuration.html#Loggers" title="Configuring Loggers"><span class="none"></span>Configuring Loggers</a></li> |
| <li><a href="../manual/configuration.html#Appenders" title="Configuring Appenders"><span class="none"></span>Configuring Appenders</a></li> |
| <li><a href="../manual/configuration.html#Filters" title="Configuring Filters"><span class="none"></span>Configuring Filters</a></li> |
| <li><a href="../manual/configuration.html#PropertySubstitution" title="Property Substitution"><span class="none"></span>Property Substitution</a></li> |
| <li><a href="../manual/configuration.html#RuntimeLookup" title="Lookup Variables"><span class="none"></span>Lookup Variables</a></li> |
| <li><a href="../manual/configuration.html#Scripts" title="Scripts"><span class="none"></span>Scripts</a></li> |
| <li><a href="../manual/configuration.html#XInclude" title="XInclude"><span class="none"></span>XInclude</a></li> |
| <li><a href="../manual/configuration.html#CompositeConfiguration" title="Composite Configurations"><span class="none"></span>Composite Configurations</a></li> |
| <li><a href="../manual/configuration.html#StatusMessages" title="Status Messages"><span class="none"></span>Status Messages</a></li> |
| <li><a href="../manual/configuration.html#UnitTestingInMaven" title="Unit Testing in Maven"><span class="none"></span>Unit Testing in Maven</a></li> |
| <li><a href="../manual/configuration.html#SystemProperties" title="System Properties"><span class="none"></span>System Properties</a></li> |
| </ul></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="../manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="../manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="../manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="../manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" border="0"/> Related Projects</li> |
| <li><a href="http://logging.apache.org/log4j/scala/index.html" class="externalLink" title="Log4j-Scala"><span class="none"></span>Log4j-Scala</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" border="0"/> Legacy Sites</li> |
| <li><a href="http://logging.apache.org/log4j/1.2/" class="externalLink" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.3/" class="externalLink" title="Log4j 2.3 - Java 6"><span class="none"></span>Log4j 2.3 - Java 6</a></li> |
| <li><a href="http://logging.apache.org/log4j/log4j-2.12.1" class="externalLink" title="Log4j 2.12.1 - Java 7"><span class="none"></span>Log4j 2.12.1 - Java 7</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" border="0"/> Components</li> |
| <li><a href="../log4j-api/index.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-core/index.html" title="Implementation"><span class="none"></span>Implementation</a></li> |
| <li><a href="../log4j-jcl/index.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api/index.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul/index.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng/index.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib/index.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui/index.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web/index.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-appserver/index.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb/index.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb2/index.html" title="Log4j MongoDB2 appender"><span class="none"></span>Log4j MongoDB2 appender</a></li> |
| <li><a href="../log4j-mongodb3/index.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-cassandra/index.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams/index.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-liquibase/index.html" title="Log4j Liquibase Binding"><span class="none"></span>Log4j Liquibase Binding</a></li> |
| <li><a href="../log4j-docker/index.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-spring-cloud-config/log4j-spring-cloud-config-client/index.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" border="0"/> Project Information</li> |
| <li><a href="../dependency-convergence.html" title="Dependency Convergence"><span class="none"></span>Dependency Convergence</a></li> |
| <li><a href="../dependency-management.html" title="Dependency Management"><span class="none"></span>Dependency Management</a></li> |
| <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a></li> |
| <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a></li> |
| <li><a href="../license.html" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../project-summary.html" title="Project Summary"><span class="none"></span>Project Summary</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/layers.png" alt="Project Reports" border="0"/> Project Reports</li> |
| <li><a href="../changes-report.html" title="Changes Report"><span class="none"></span>Changes Report</a></li> |
| <li><a href="../jira-report.html" title="JIRA Report"><span class="none"></span>JIRA Report</a></li> |
| <li><a href="../rat-report.html" title="RAT Report"><span class="none"></span>RAT Report</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <hr /> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <section> |
| <h2><a name="Configuration"></a>Configuration</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, 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"></a> |
| <section> |
| <h3><a name="Automatic_Configuration"></a>Automatic Configuration</h3> |
| |
| <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 style="list-style-type: decimal"> |
| |
| <li>Log4j will inspect the "log4j.configurationFile" system property and, if set, will attempt to |
| load the configuration using the ConfigurationFactory that matches the file |
| extension.</li> |
| |
| <li>If no system property is set the properties ConfigurationFactory will look for |
| log4j2-test.properties in the classpath.</li> |
| |
| <li>If no such file is found the YAML ConfigurationFactory will look for |
| log4j2-test.yaml or log4j2-test.yml in the classpath.</li> |
| |
| <li>If no such file is found the JSON ConfigurationFactory will look for |
| log4j2-test.json or log4j2-test.jsn in the classpath.</li> |
| |
| <li>If no such file is found the XML ConfigurationFactory will look for |
| log4j2-test.xml in the classpath.</li> |
| |
| <li>If a test file cannot be located the properties ConfigurationFactory will look for |
| log4j2.properties on the classpath.</li> |
| |
| <li>If a properties file cannot be located the YAML ConfigurationFactory will look for |
| log4j2.yaml or log4j2.yml on the classpath.</li> |
| |
| <li>If a YAML file cannot be located the JSON ConfigurationFactory will look for |
| log4j2.json or log4j2.jsn on the classpath.</li> |
| |
| <li>If a JSON file cannot be located the XML ConfigurationFactory will try to locate |
| log4j2.xml on the classpath.</li> |
| |
| <li>If no configuration file could be located the DefaultConfiguration will |
| be used. This will cause logging output to go to the console.</li> |
| </ol> |
| |
| <p>An example application named MyApp that uses log4j can be used to illustrate how |
| this is done. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 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> |
| MyApp begins by importing log4j related classes. It |
| then defines a static logger variable with the name MyApp |
| which happens to be the fully qualified name of the class. |
| </p> |
| |
| <p> |
| MyApp uses the Bar class defined in the packagecom.foo. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 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 Level.ERROR. |
| </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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </section> |
| <a name="Additivity"></a> |
| <section> |
| <h3><a name="Additivity"></a>Additivity</h3> |
| |
| <p> |
| Perhaps it is desired to eliminate all the TRACE output from everything except com.foo.Bar. |
| 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> |
| <pre class="prettyprint linenums"> |
| <Logger name="com.foo.Bar" level="TRACE"/> |
| <Root level="ERROR"> |
| <AppenderRef ref="STDOUT"> |
| </Root> |
| </pre></div> |
| |
| <p> |
| With this configuration all log events from com.foo.Bar will be recorded while only error |
| events will be recorded from all other components. |
| </p> |
| |
| <p> |
| In the previous example all the events from com.foo.Bar were still written to the Console. This is |
| because the logger for com.foo.Bar did not have any appenders configured while its parent did. In fact, |
| the following configuration |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <?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 com.foo.Bar appear twice. This is because the appender associated |
| with logger com.foo.Bar is first used, which writes the first instance to the Console. Next, the parent |
| of com.foo.Bar, 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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </section> |
| <a name="AutomaticReconfiguration"></a> |
| <section> |
| <h3><a name="Automatic_Reconfiguration"></a>Automatic Reconfiguration</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> |
| <pre class="prettyprint linenums"> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <Configuration monitorInterval="30"> |
| ... |
| </Configuration> |
| </pre></div> |
| </section> |
| <a name="ChainsawSupport"></a> |
| <section> |
| <h3><a name="Chainsaw_can_automatically_process_your_log_files_.28Advertising_appender_configurations.29"></a>Chainsaw can automatically process your log files (Advertising appender configurations)</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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </section> |
| <a name="ConfigurationSyntax"></a> |
| <section> |
| <h3><a name="Configuration_Syntax"></a>Configuration Syntax</h3> |
| |
| <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 border="0" class="table table-striped"> |
| |
| <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" for stderr, "out" for stdout, a file path, or a 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>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 href="../log4j-core/target/site/apidocs/org/apache/logging/log4j/core/LoggerContext.html#stoplong_java.util.concurrent.TimeUnit" class="javadoc">LoggerContext.stop(long, |
| java.util.concurrent.TimeUnit)</a>. |
| (Not used if shutdownHook is set to "disable".)</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <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 status="trace" is one of the first tools available to you if you need to |
| troubleshoot log4j. |
| </p> |
| <p> |
| (Alternatively, setting system property log4j2.debug 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 class="a"> |
| |
| <td>strict</td> |
| |
| <td>Enables the use of the strict XML format. Not supported in JSON configurations.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>verbose</td> |
| |
| <td>Enables diagnostic information while loading plugins.</td> |
| </tr> |
| </table> |
| <a name="XML"></a></section><section> |
| <h3><a name="Configuration_with_XML"></a>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> |
| |
| <div> |
| <pre class="prettyprint"><PatternLayout pattern="%m%n"/></pre></div> |
| |
| <p>and</p> |
| |
| <div> |
| <pre class="prettyprint"> |
| <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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| <section><section> |
| <h5><a name="Strict_XML"></a>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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <?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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </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></div> |
| <a name="JSON"></a> |
| </section></section><section> |
| <h4><a name="Configuration_with_JSON"></a>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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| { "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" }, |
| "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"} |
| ] |
| } |
| } |
| }, |
| "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> |
| <pre class="prettyprint linenums"> |
| { "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" }, "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"} |
| ] |
| } |
| } |
| ] |
| }, |
| "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></div> |
| |
| <p> |
| Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using |
| JSON configuration files. |
| </p> |
| <a name="YAML"></a> |
| </section><section> |
| <h4><a name="Configuration_with_YAML"></a>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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| Configuration: |
| status: warn |
| name: YAMLConfigTest |
| properties: |
| property: |
| name: filename |
| value: target/test-yaml.log |
| thresholdFilter: |
| level: debug |
| appenders: |
| Console: |
| name: STDOUT |
| PatternLayout: |
| Pattern: "%m%n" |
| File: |
| name: File |
| fileName: ${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></div> |
| |
| <p> |
| Additional <a href="../runtime-dependencies.html">runtime dependencies</a> are required for using |
| YAML configuration files. |
| </p> |
| <a name="Properties"></a> |
| </section><section> |
| <h4><a name="Configuration_with_Properties"></a>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> |
| |
| <div> |
| <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></div> |
| <a name="Loggers"></a> |
| </section><section> |
| <h4><a name="Configuring_loggers"></a>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 logger element. The logger 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> |
| 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> |
| </section><section> |
| <h4><a name="Configuring_Appenders"></a>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"></a> |
| </section><section> |
| <h4><a name="Configuring_Filters"></a>Configuring Filters</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 filter element can be configured, that element may be the |
| filters element which represents the CompositeFilter. The filters element |
| allows any number of filter elements to be configured within it. The following example |
| shows how multiple filters can be configured on the ConsoleAppender. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </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="STDOUT"/> |
| </Root> |
| </Loggers> |
| |
| </Configuration> |
| </pre></div> |
| </section></section> |
| <a name="PropertySubstitution"></a> |
| <section> |
| <h3><a name="Property_Substitution"></a>Property Substitution</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 ${name} |
| 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> |
| <pre class="prettyprint linenums"> |
| <?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"/> |
| <ThresholdFilter level="debug"/> |
| </Console> |
| <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"/> |
| </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 ${prefix:name} 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 border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Prefix</th> |
| |
| <th>Context</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>base64</td> |
| |
| <td> |
| Base64 encoded data. The format is ${base64:Base64_encoded_data}. |
| For example: |
| ${base64:SGVsbG8gV29ybGQhCg==} yields Hello World!. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>bundle</td> |
| |
| <td> |
| Resource bundle. The format is ${bundle:BundleName:BundleKey}. |
| The bundle name follows package naming conventions, for example: |
| ${bundle:com.domain.Messages:MyKey}. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>ctx</td> |
| |
| <td>Thread Context Map (MDC)</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>date</td> |
| |
| <td>Inserts the current date and/or time using the specified format</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>env</td> |
| |
| <td>System environment variables. The formats are ${env:ENV_NAME} and ${env:ENV_NAME:-default_value}.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td>jndi</td> |
| |
| <td>A value set in the default JNDI Context.</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>log4j</td> |
| |
| <td>Log4j configuration properties. The expressions ${log4j:configLocation} and |
| ${log4j:configParentLocation} respectively provide the absolute path |
| to the log4j configuration file and its parent folder.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <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="a"> |
| |
| <td>map</td> |
| |
| <td>A value from a MapMessage</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <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="a"> |
| |
| <td>sys</td> |
| |
| <td>System properties. The formats are ${sys:some.property} and ${sys:some.property:-default_value}.</td> |
| </tr> |
| </table> |
| <a name="DefaultProperties"></a></section><section> |
| <h3><a name="Default_Properites"></a>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 ${lookupName:key:-defaultValue}. |
| In some cases the key might contain a leading '-'. When this is the case an escape character must be |
| included, such as ${main:\--file:-app.properties}. This would use the |
| MainMapLookup for a key named --file. If the key is not found then |
| app.properties would be used as the default value. |
| </p> |
| </section> |
| <a name="RuntimeLookup"></a> |
| <section> |
| <h3><a name="Lookup_Variables_with_Multiple_Leading_.27.24.27_Characters"></a>Lookup Variables with Multiple Leading '$' Characters</h3> |
| |
| <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 "${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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </section> |
| <a name="Scripts"></a> |
| <section> |
| <h3><a name="Scripts"></a>Scripts</h3> |
| |
| <p> |
| Log4j provides support for <a class="externalLink" 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 class="externalLink" 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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <?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; |
| ]]></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; |
| ]]> |
| </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></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <pre> |
| var result; |
| if (logEvent.getLoggerName().equals("JavascriptNoLocation")) { |
| result = "NoLocation"; |
| } else if (logEvent.getMarker() != null && logEvent.getMarker().isInstanceOf("FLOW")) { |
| result = "Flow"; |
| } |
| result; |
| </pre></div> |
| <section> |
| <h4><a name="A_special_note_on_Beanshell"></a>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> |
| |
| <div> |
| <pre> |
| 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></div> |
| </section></section> |
| <a name="XInclude"></a> |
| <section> |
| <h3><a name="XInclude"></a>XInclude</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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| <pre class="prettyprint linenums"> |
| <?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> |
| </section> |
| <a name="CompositeConfiguration"></a> |
| <section> |
| <h3><a name="Composite_Configuration"></a>Composite Configuration</h3> |
| |
| <p> |
| Log4j allows multiple configuration files to be used by specifying them as a list of comma separated |
| file paths on log4j.configurationFile. 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: |
| </p> |
| <ol style="list-style-type: decimal"> |
| |
| <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> |
| |
| </section> |
| <a name="StatusMessages"></a> |
| <section> |
| <h3><a name="Status_Messages"></a>Status Messages</h3> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <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 |
| log4j2.debug 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 org.apache.logging.log4j.simplelog.StatusLogger.level.</li> |
| |
| <li>After a configuration is found, status logger level can be controlled in the configuration |
| file with the "status" attribute, for example: <Configuration status="trace">.</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> |
| <pre class="prettyprint">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> |
| <pre class="prettyprint linenums"> |
| <?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"/> |
| <ThresholdFilter level="debug"/> |
| </Console> |
| <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"/> |
| </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,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="${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$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> |
| <pre class="prettyprint linenums"> |
| <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> |
| <pre class="prettyprint linenums"> |
| StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR); |
| StatusLogger.getLogger().registerListener(listener); |
| </pre></div> |
| </section> |
| <a name="UnitTestingInMaven"></a> |
| <section> |
| <h3><a name="Testing_in_Maven"></a>Testing in Maven</h3> |
| |
| <p> |
| Maven can run unit and functional tests during the build cycle. By default, any files placed in |
| src/test/resources 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 LoggerContextRule |
| JUnit test rule which provides additional convenience methods for testing. This requires adding the |
| log4j-core test-jar dependency to your test scope dependencies. For example: |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| 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></div> |
| </section> |
| <a name="SystemProperties"></a> |
| <section> |
| <h3><a name="System_Properties"></a>System Properties</h3> |
| |
| <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 href="../log4j-api/apidocs/org/apache/logging/log4j/util/PropertySource.html" class="javadoc">PropertySource</a> |
| interface. Additional property source classes can be added through the standard ServiceLoader |
| 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 border="0" class="table table-striped"><caption align="top">PropertySource priorities and descriptions</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Source</th> |
| |
| <th>Priority</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td>Environment Variables</td> |
| |
| <td>-100</td> |
| |
| <td> |
| Environment variables are all prefixed with LOG4J_, 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 class="a"> |
| |
| <td>log4j2.component.properties 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 class="b"> |
| |
| <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></style> |
| |
| <table border="0" class="table table-striped" style="table-layout: fixed; width: 100%"><caption align="top">Log4j 2 global configuration properties</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Property Name <br /> (Legacy Property Name)</th> |
| |
| <th>Environment Variable</th> |
| |
| <th>Default Value</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| |
| <tr class="b"> |
| |
| <td><a name="configurationFile"></a>log4j2.configurationFile |
| <br /> |
| (<a name="log4j.configurationFile"></a>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. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="debug"></a>log4j2.debug |
| <br /> |
| (<a name="log4j2.debug"></a>log4j2.debug) |
| </td> |
| |
| <td>LOG4J_DEBUG</td> |
| |
| <td> </td> |
| |
| <td> |
| Log4j2 will print all internal logging to the console if system property |
| log4j2.debug is defined (with any or no value). |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="mergeFactory"></a>log4j2.mergeFactory |
| <br /> |
| (<a name="log4j.mergeFactory"></a>log4j.mergeFactory) |
| </td> |
| |
| <td>LOG4J_MERGE_FACTORY</td> |
| |
| <td> </td> |
| |
| <td> |
| The name of the class that implements the MergeStrategy interface. If not specified |
| DefaultMergeStrategy will be used when creating a CompositeConfiguration.. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="contextSelector"></a>log4j2.contextSelector |
| <br /> |
| (<a name="Log4jContextSelector"></a>Log4jContextSelector) |
| </td> |
| |
| <td>LOG4J_CONTEXT_SELECTOR</td> |
| |
| <td>ClassLoaderContextSelector</td> |
| |
| <td> |
| Creates the LoggerContexts. 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 /> |
| |
| org.apache.logging.log4j.core.async .AsyncLoggerContextSelector - makes <a href="async.html">all loggers asynchronous</a>.<br /> |
| org.apache.logging.log4j.core.selector .BasicContextSelector - creates a single shared LoggerContext.<br /> |
| org.apache.logging.log4j.core.selector .ClassLoaderContextSelector - separate LoggerContexts for each web application.<br /> |
| org.apache.logging.log4j.core.selector .JndiContextSelector - use JNDI to locate each web application's LoggerContext.<br /> |
| org.apache.logging.log4j.core.osgi .BundleContextSelector - separate LoggerContexts for each OSGi bundle. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="logEventFactory"></a>log4j2.logEventFactory |
| <br /> |
| (<a name="Log4jLogEventFactory"></a>Log4jLogEventFactory) |
| </td> |
| |
| <td>LOG4J_LOG_EVENT_FACTORY</td> |
| |
| |
| <td>org.apache.logging.log4j.core.impl .DefaultLogEventFactory</td> |
| |
| <td> |
| Factory class used by LoggerConfig to create LogEvent instances. |
| (Ignored when the AsyncLoggerContextSelector is used.) |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="loggerContextFactory"></a>log4j2.loggerContextFactory |
| <br /> |
| (<a name="log4j2.loggerContextFactory"></a>log4j2.loggerContextFactory) |
| </td> |
| |
| <td>LOG4J_LOGGER_CONTEXT_FACTORY</td> |
| |
| |
| <td>org.apache.logging.log4j.simple .SimpleLoggerContextFactory</td> |
| |
| <td> |
| Factory class used by LogManager to bootstrap the logging implementation. |
| The core jar provides org.apache.logging.log4j.core |
| .impl.Log4jContextFactory. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="configurationFactory"></a>log4j2.configurationFactory |
| <br /> |
| (<a name="log4j.configurationFactory"></a>log4j.configurationFactory) |
| </td> |
| |
| <td>LOG4J_CONFIGURATION_FACTORY</td> |
| |
| <td> </td> |
| |
| <td> |
| Fully specified class name of a class extending org.apache.logging.log4j.core |
| .config.ConfigurationFactory. |
| If specified, an instance of this class is added to the list of configuration factories. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="shutdownHookEnabled"></a>log4j2.shutdownHookEnabled |
| <br /> |
| (<a name="log4j.shutdownHookEnabled"></a>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 LoggerContext. |
| By default, this is enabled and can be disabled on a per-configuration basis. When running with the |
| log4j-web module, this is automatically disabled. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="shutdownCallbackRegistry"></a>log4j2.shutdownCallbackRegistry |
| <br /> |
| (<a name="log4j.shutdownCallbackRegistry"></a>log4j.shutdownCallbackRegistry) |
| </td> |
| |
| <td>LOG4J_SHUTDOWN_CALLBACK_REGISTRY</td> |
| |
| |
| <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 DefaultShutdownCallbackRegistry. |
| The specified class must have a default constructor. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="clock"></a>log4j2.clock |
| <br /> |
| (<a name="log4j.Clock"></a>log4j.Clock) |
| </td> |
| |
| <td>LOG4J_CLOCK</td> |
| |
| <td>SystemClock</td> |
| |
| <td> |
| Implementation of the org.apache.logging.log4j .core.util.Clock |
| interface that is used for timestamping the log events. |
| <br /> |
| By default, System.currentTimeMillis is called on every log event. |
| <br /> |
| You can also specify a fully qualified class name of a custom class that implements the |
| Clock interface. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="level"></a>log4j2.level |
| <br /> |
| (<a name="org.apache.logging.log4j.level"></a>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 class="a"> |
| |
| <td><a name="disableThreadContext"></a>log4j2.disableThreadContext |
| <br /> |
| (disableThreadContext) |
| </td> |
| |
| <td>LOG4J_DISABLE_THREAD_CONTEXT</td> |
| |
| <td>false</td> |
| |
| <td> |
| If true, the ThreadContext stack and map are disabled. |
| (May be ignored if a custom ThreadContext map is specified.) |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="disableThreadContextStack"></a>log4j2.disableThreadContextStack |
| <br /> |
| (disableThreadContextStack) |
| </td> |
| |
| <td>LOG4J_DISABLE_THREAD_CONTEXT_STACK</td> |
| |
| <td>false</td> |
| |
| <td> |
| If true, the ThreadContext stack is disabled. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="disableThreadContextMap"></a>log4j2.disableThreadContextMap |
| <br /> |
| (disableThreadContextMap) |
| </td> |
| |
| <td>LOG4J_DISABLE_THREAD_CONTEXT_MAP</td> |
| |
| <td>false</td> |
| |
| <td> |
| If true, the ThreadContext map is disabled. |
| (May be ignored if a custom ThreadContext map is specified.) |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="log4j2.threadContextMap"></a>log4j2.threadContextMap |
| <br /> |
| (log4j2.threadContextMap) |
| </td> |
| |
| <td>LOG4J_THREAD_CONTEXT_MAP</td> |
| |
| <td> </td> |
| |
| <td> |
| Fully specified class name of a custom ThreadContextMap implementation class. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="isThreadContextMapInheritable"></a>log4j2.isThreadContextMapInheritable |
| <br /> |
| (isThreadContextMapInheritable) |
| </td> |
| |
| <td>LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE</td> |
| |
| <td>false</td> |
| |
| <td> |
| If true use a InheritableThreadLocal to implement the ThreadContext map. |
| Otherwise, use a plain ThreadLocal. |
| (May be ignored if a custom ThreadContext map is specified.) |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="contextDataInjector"></a>log4j2.contextDataInjector |
| <br /> |
| (<a name="log4j2.ContextDataInjector"></a>log4j2.ContextDataInjector) |
| </td> |
| |
| <td>LOG4J_CONTEXT_DATA_INJECTOR</td> |
| |
| <td> </td> |
| |
| <td> |
| Fully specified class name of a custom ContextDataInjector implementation class. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="garbagefreeThreadContextMap"></a>log4j2.garbagefreeThreadContextMap |
| <br /> |
| (<a name="log4j2.garbagefree.threadContextMap"></a>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 class="b"> |
| |
| <td><a name="disableJmx"></a>log4j2.disableJmx |
| <br /> |
| (<a name="log4j2.disable.jmx"></a>log4j2.disable.jmx) |
| </td> |
| |
| <td>LOG4J_DISABLE_JMX</td> |
| |
| <td>false</td> |
| |
| <td> |
| If true, 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><a name="jmxNotifyAsync"></a>log4j2.jmxNotifyAsync |
| <br /> |
| (<a name="log4j2.jmx.notify.async"></a>log4j2.jmx.notify.async) |
| </td> |
| |
| <td>LOG4J_JMX_NOTIFY_ASYNC</td> |
| |
| <td>false for web apps, true otherwise</td> |
| |
| <td> |
| If true, log4j's JMX notifications are sent from a separate background thread, |
| otherwise they are sent from the caller thread. |
| If system property log4j2.is.webapp is true or the javax.servlet.Servlet |
| class is on the classpath, the default behaviour |
| is to use the caller thread to send JMX notifications. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="skipJansi"></a>log4j2.skipJansi |
| <br /> |
| (<a name="log4j.skipJansi"></a>log4j.skipJansi) |
| </td> |
| |
| <td>LOG4J_SKIP_JANSI</td> |
| |
| <td>true</td> |
| |
| <td> |
| If true, the ConsoleAppender will not try to use the Jansi output stream on Windows. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="ignoreTCL"></a>log4j2.ignoreTCL |
| <br /> |
| (<a name="log4j.ignoreTCL"></a>log4j.ignoreTCL) |
| </td> |
| |
| <td>LOG4J_IGNORE_TCL</td> |
| |
| <td>false</td> |
| |
| <td> |
| If true, 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><a name="uuidSequence"></a>log4j2.uuidSequence |
| <br /> |
| (<a name="org.apache.logging.log4j.uuidSequence"></a>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 class="a"> |
| |
| <td><a name="simplelogShowContextMap"></a>log4j2.simplelogShowContextMap |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.showContextMap"></a>org.apache.logging.log4j .simplelog.showContextMap) |
| </td> |
| |
| <td>LOG4J_SIMPLELOG_SHOW_CONTEXT_MAP</td> |
| |
| <td>false</td> |
| |
| <td>If true, the full ThreadContext map is included in each SimpleLogger log message.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="simplelogShowlogname"></a>log4j2.simplelogShowlogname |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.showlogname"></a>org.apache.logging.log4j .simplelog.showlogname) |
| </td> |
| |
| <td>LOG4J_SIMPLELOG_SHOWLOGNAME</td> |
| |
| <td>false</td> |
| |
| <td>If true, the logger name is included in each SimpleLogger log message.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="simplelogShowShortLogname"></a>log4j2.simplelogShowShortLogname |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.showShortLogname"></a>org.apache.logging.log4j .simplelog.showShortLogname) |
| </td> |
| |
| <td>LOG4J_SIMPLELOG_SHOW_SHORT_LOGNAME</td> |
| |
| <td>true</td> |
| |
| <td>If true, 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"> |
| |
| <td><a name="simplelogShowdatetime"></a>log4j2.simplelogShowdatetime |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.showdatetime"></a>org.apache.logging.log4j .simplelog.showdatetime) |
| </td> |
| |
| <td>LOG4J_SIMPLELOG_SHOWDATETIME</td> |
| |
| <td>false</td> |
| |
| <td>If true, SimpleLogger log messages contain timestamp information. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="simplelogDateTimeFormat"></a>log4j2.simplelogDateTimeFormat |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.dateTimeFormat"></a>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 org.apache.logging.log4j .simplelog.showdatetime is false. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="simplelogLogFile"></a>log4j2.simplelogLogFile |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.logFile"></a>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 class="a"> |
| |
| <td><a name="simplelogLevel"></a>log4j2.simplelogLevel |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.level"></a>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 class="b"> |
| |
| <td>log4j2.simplelog.<loggerName>.level |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.loggerNamelevel"></a>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 class="a"> |
| |
| <td><a name="simplelogStatusLoggerLevel"></a>log4j2.simplelogStatusLoggerLevel |
| <br /> |
| |
| (<a name="org.apache.logging.log4j.simplelog.StatusLogger.level"></a>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 |
| StatusLogger.getLogger() .setLevel(someLevel). |
| 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><a name="defaultStatusLevel"></a>log4j2.defaultStatusLevel |
| <br /> |
| (<a name="Log4jDefaultStatusLevel"></a>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 class="a"> |
| |
| <td><a name="statusLoggerLevel"></a>log4j2.statusLoggerLevel |
| <br /> |
| (<a name="log4j2.StatusLogger.level"></a>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 |
| <Configuration status="trace">, 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 StatusLogger.getLogger().getLevel() |
| (see property org.apache.logging.log4j.simplelog .StatusLogger.level).</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="statusEntries"></a>log4j2.statusEntries |
| <br /> |
| (<a name="log4j2.status.entries"></a>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 |
| StatusLogger.getStatusData(). |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="statusLoggerDateformat"></a>log4j2.statusLoggerDateformat |
| <br /> |
| (<a name="log4j2.StatusLogger.DateFormat"></a>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 java.text.SimpleDateFormat for supported formats. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="asyncLoggerExceptionHandler"></a>log4j2.asyncLoggerExceptionHandler |
| <br /> |
| (<a name="AsyncLogger.ExceptionHandler"></a>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 class="a"> |
| |
| <td><a name="asyncLoggerRingBufferSize"></a>log4j2.asyncLoggerRingBufferSize |
| <br /> |
| (<a name="AsyncLogger.RingBufferSize"></a>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 class="b"> |
| |
| <td><a name="asyncLoggerWaitStrategy"></a>log4j2.asyncLoggerWaitStrategy |
| <br /> |
| (<a name="AsyncLogger.WaitStrategy"></a>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 class="a"> |
| |
| <td><a name="AsyncLogger.SynchronizeEnqueueWhenQueueFull"></a>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 class="b"> |
| |
| <td><a name="asyncLoggerThreadNameStrategy"></a>log4j2.asyncLoggerThreadNameStrategy |
| <br /> |
| (<a name="AsyncLogger.ThreadNameStrategy"></a>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 class="a"> |
| |
| <td><a name="asyncLoggerConfigExceptionHandler"></a>log4j2.asyncLoggerConfigExceptionHandler |
| <br /> |
| (<a name="AsyncLoggerConfig.ExceptionHandler"></a>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 class="b"> |
| |
| <td><a name="asyncLoggerConfigRingBufferSize"></a>log4j2.asyncLoggerConfigRingBufferSize |
| <br /> |
| (<a name="AsyncLoggerConfig.RingBufferSize"></a>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 class="a"> |
| |
| <td><a name="asyncLoggerConfigWaitStrategy"></a>log4j2.asyncLoggerConfigWaitStrategy |
| <br /> |
| (<a name="AsyncLoggerConfig.WaitStrategy"></a>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 class="b"> |
| |
| <td><a name="AsyncLoggerConfig.SynchronizeEnqueueWhenQueueFull"></a>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 class="a"> |
| |
| <td><a name="julLoggerAdapter"></a>log4j2.julLoggerAdapter |
| <br /> |
| (<a name="log4j.jul.LoggerAdapter"></a>log4j.jul.LoggerAdapter) |
| </td> |
| |
| <td>LOG4J_JUL_LOGGER_ADAPTER</td> |
| |
| |
| <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 |
| org.apache.logging.log4j.jul .CoreLoggerAdapter will be used. Otherwise, the |
| ApiLogggerAdapter will be used. Custom implementations must provide a public default constructor. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="formatMsgAsync"></a>log4j2.formatMsgAsync |
| <br /> |
| (<a name="log4j.format.msg.async"></a>log4j.format.msg.async) |
| </td> |
| |
| <td>LOG4J_FORMAT_MSG_ASYNC</td> |
| |
| <td> |
| false |
| </td> |
| |
| <td> |
| If false (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 class="a"> |
| |
| <td><a name="asyncQueueFullPolicy"></a>log4j2.asyncQueueFullPolicy |
| <br /> |
| (<a name="log4j2.AsyncQueueFullPolicy"></a>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 Discard 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 class="b"> |
| |
| <td><a name="discardThreshold"></a>log4j2.discardThreshold |
| <br /> |
| (<a name="log4j2.DiscardThreshold"></a>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, INFO, DEBUG and TRACE level |
| events are discarded when the queue is full. |
| This property only has effect if Discard is specified as the |
| log4j2.AsyncQueueFullPolicy.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="messageFactory"></a>log4j2.messageFactory |
| <br /> |
| (<a name="log4j2.messageFactory"></a>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 class="b"> |
| |
| <td><a name="flowMessageFactory"></a>log4j2.flowMessageFactory |
| <br /> |
| (<a name="log4j2.flowMessageFactory"></a>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 class="a"> |
| |
| <td><a name="isWebapp"></a>log4j2.isWebapp |
| <br /> |
| (<a name="log4j2.is.webapp"></a>log4j2.is.webapp) |
| </td> |
| |
| <td>LOG4J_IS_WEBAPP</td> |
| |
| <td>true if Servlet 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 class="b"> |
| |
| <td><a name="enableThreadlocals"></a>log4j2.enableThreadlocals |
| <br /> |
| (<a name="log4j2.enable.threadlocals"></a>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 class="a"> |
| |
| <td><a name="enableDirectEncoders"></a>log4j2.enableDirectEncoders |
| <br /> |
| (<a name="log4j2.enable.direct.encoders"></a>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 true 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 class="b"> |
| |
| <td><a name="initialReusableMsgSize"></a>log4j2.initialReusableMsgSize |
| <br /> |
| (<a name="log4j.initialReusableMsgSize"></a>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 class="a"> |
| |
| <td><a name="maxReusableMsgSize"></a>log4j2.maxReusableMsgSize |
| <br /> |
| (<a name="log4j.maxReusableMsgSize"></a>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 class="b"> |
| |
| <td><a name="layoutStringBuilderMaxSize"></a>log4j2.layoutStringBuilderMaxSize |
| <br /> |
| (<a name="log4j.layoutStringBuilder.maxSize"></a>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 class="a"> |
| |
| <td><a name="unboxRingbufferSize"></a>log4j2.unboxRingbufferSize |
| <br /> |
| (<a name="log4j.unbox.ringbuffer.size"></a>log4j.unbox.ringbuffer.size) |
| </td> |
| |
| <td>LOG4J_UNBOX_RINGBUFFER_SIZE</td> |
| |
| <td>32</td> |
| |
| <td>The org.apache.logging.log4j.util.Unbox utility |
| manages a small thread-local ring buffer of StringBuilders. |
| Each time one of the box() 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 log4j.unbox.ringbuffer.size 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 class="b"> |
| |
| <td><a name="loggerContextStacktraceOnStart"></a>log4j2.loggerContextStacktraceOnStart |
| <br /> |
| (<a name="log4j.LoggerContext.stacktrace.on.start"></a>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 class="a"> |
| |
| <td><a name="formatMsgNoLookups"></a>log4j2.formatMsgNoLookups |
| <br /> |
| (<a name="log4j2.formatMsgNoLookups"></a>log4j2.formatMsgNoLookups) |
| </td> |
| |
| <td>FORMAT_MESSAGES_PATTERN_DISABLE_LOOKUPS</td> |
| |
| <td>false</td> |
| |
| <td>Disables message pattern lookups globally when set to true. |
| This is equivalent to defining all message patterns using %m{nolookups}.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="log4j2.trustStoreLocation"></a>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 class="a"> |
| |
| <td><a name="log4j2.trustStorePassword"></a>log4j2.trustStorePassword</td> |
| |
| <td>LOG4J_TRUST_STORE_PASSWORD</td> |
| |
| <td></td> |
| |
| <td>Password needed to access the trust store.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="log4j2.trustStorePasswordFile"></a>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 class="a"> |
| |
| <td><a name="log4j2.trustStorePasswordEnvironmentVariable"></a>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 class="b"> |
| |
| <td><a name="log4j2.trustStoreType"></a>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 class="a"> |
| |
| <td><a name="log4j2.trustStoreKeyManagerFactoryAlgorithm"></a>log4j2.trustStoreKeyManagerFactoryAlgorithm</td> |
| |
| <td>LOG4J_TRUST_STORE_KEY_MANAGER_FACTORY_ALGORITHM</td> |
| |
| <td></td> |
| |
| <td>Java cryptographic algorithm.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="log4j2.keyStoreLocation"></a>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 class="a"> |
| |
| <td><a name="log4j2.keyStorePassword"></a>log4j2.keyStorePassword</td> |
| |
| <td>LOG4J_KEY_STORE_PASSWORD</td> |
| |
| <td></td> |
| |
| <td>Password needed to access the key store.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="log4j2.keyStorePasswordFile"></a>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 class="a"> |
| |
| <td><a name="log4j2.keyStorePasswordEnvironmentVariable"></a>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 class="b"> |
| |
| <td><a name="log4j2.keyStoreType"></a>log4j2.keyStoreType</td> |
| |
| <td>LOG4J_KEY_STORE_TYPE</td> |
| |
| <td></td>t |
| |
| <td>The type of key store.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td><a name="log4j2.keyStoreKeyManagerFactoryAlgorithm"></a>log4j2.keyStoreKeyManagerFactoryAlgorithm</td> |
| |
| <td>LOG4J_KEY_STORE_KEY_MANAGER_FACTORY_ALGORITHM</td> |
| |
| <td></td> |
| |
| <td>Java cryptographic algorithm.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td><a name="log4j2.sslVerifyHostName"></a>log4j2.sslVerifyHostName</td> |
| |
| <td></td> |
| |
| <td>false</td> |
| |
| <td>true or false if the host name should be verified</td> |
| </tr> |
| </table> |
| |
| </section> |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2020 <a class="external" href="http://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
