| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/configuration.xml.vm at 2024-03-06 |
| | Rendered using Apache Maven Fluido Skin 1.11.2 |
| --> |
| <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.11.1" /> |
| <meta name="author" content="Ralph Goers" /> |
| <title>Log4j – Configuring Log4j 2</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.11.2.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.11.2.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../../.." id="bannerLeft"><img src="../images/ls-logo.jpg" alt="" style="" /></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/logo.png" alt="" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2024-03-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.23.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="../../../" 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" style="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="../support.html" title="Support"><span class="none"></span>Support</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="../release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</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="../security.html" title="Security"><span class="icon-chevron-right"></span>Security</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" style="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/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></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="../../kotlin" title="Kotlin API"><span class="none"></span>Kotlin API</a></li> |
| <li><a href="../../scala" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li class="active"><a><span class="icon-chevron-down"></span>Configuration</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/configuration.html#Architecture" title="Configuration Architecture"><span class="none"></span>Configuration Architecture</a></li> |
| <li><a href="../manual/configuration.html#Arbiters" title="Arbiters"><span class="none"></span>Arbiters</a></li> |
| <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/pencil.png" alt="For Contributors" style="border: 0;" /> For Contributors</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/cog.png" alt="Components" style="border: 0;" /> Components</li> |
| <li><a href="../log4j-api.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="../log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-jakarta-web.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li> |
| <li><a href="../log4j-appserver.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb3.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-mongodb4.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li> |
| <li><a href="../log4j-cassandra.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-docker.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-kubernetes.html" title="Log4j Kubernetes Support"><span class="none"></span>Log4j Kubernetes Support</a></li> |
| <li><a href="../log4j-spring-boot.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li> |
| <li><a href="../log4j-spring-cloud-config-client.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/tag.png" alt="Related Projects" style="border: 0;" /> Related Projects</li> |
| <li><a href="../../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li> |
| <li><a href="../../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li> |
| <li><a href="../../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li> |
| <li><a href="../../kotlin" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li> |
| <li><a href="../../scala" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li> |
| <li><a href="../../transform" title="Log4j Transform"><span class="none"></span>Log4j Transform</a></li> |
| <li><a href="../../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" style="border: 0;" /> Legacy Sites</li> |
| <li><a href="../../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li> |
| <li><a href="../../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li> |
| <li><a href="../../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" style="border: 0;" /> Project Information</li> |
| <li><a href="../team.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="https://github.com/apache/logging-log4j2" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="none"></span>Javadoc</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <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> |
| All available formats are functionally equivalent. For example, a configuration file in XML can be |
| rewritten using the properties format (and the opposite) without any loss of functionality. However, |
| the hierarchical nature of a Log4j configuration can be captured better in formats which naturally |
| support nesting so XML, JSON, and YAML files, are usually easier to use. |
| </p> |
| |
| <p> |
| Note that unlike Log4j 1.x, the public Log4j 2 API does not expose methods to add, modify or remove |
| appenders and filters or manipulate the configuration in any way. |
| </p> |
| <a name="Architecture"></a> |
| <section> |
| <h3><a name="Configuration_Architecture"></a>Configuration Architecture</h3> |
| |
| <p> |
| In part because support for XML was added first, Log4j's configuration is reflected as a tree structure. |
| In fact every configuration dialect, including the ConfigurationBuilder, generates a Node for every |
| configuration element. A node is a fairly simple structure that contains a set of attributes, a set of |
| child nodes and a PluginType. It is important to note that every Node must have a corresponding plugin, |
| as the plugin is the component that actually performs the work represented by the node. |
| </p> |
| |
| <p> |
| Every document type supported by Log4j has a ConfigurationFactory. The factory itself is a Log4j plugin |
| that declares what file extensions it supports and what its priority is. Properties have the highest |
| precedence with a value of 8, followed by yaml, json and xml. When autoconfiguration is performed Log4j |
| will call each of these factories in order to determine which, if any, support the specified configuration |
| file format. If one is found that factory will create the corresponding Configuration object and pass the |
| reference to the configuration data to it. |
| </p> |
| |
| <p>Every configuration implementation, such as XMLConfiguration, YamlConfiguration, JsonConfiguration, etc. |
| has the primary task of converting the configuration text into the Node tree, typically by parsing the |
| text with whatever tool is available for that document type. It should be noted that while most of the |
| supported document types are inherently tree structured, the Java properties syntax is not. Because of the |
| need to convert the syntax into a Node tree the Java properties syntax used by Log4j required all properties |
| follow a naming pattern that made the tree structure clear. As a consequence, the Java Properties format |
| tends to be more verbose than using a different document type. |
| </p> |
| |
| <p> |
| Once the Node tree is created control is delegated to AbstractConfiguration, which converts the Nodes into |
| their respective Java objects using Log4j's Plugin system and provides all the common functionality. |
| </p> |
| </section> |
| <a name="Arbiters"></a> |
| <section> |
| <h3><a name="Arbiters"></a>Arbiters</h3> |
| |
| <p> |
| In some situations it is desirable to have a single logging configuration that can be used in any |
| deployment environment. For example, it may be necessary to have a different default logging level in |
| production then in development. Another case might be where one type of appender is used when running |
| natively but another is used when deployed to a docker container. One way to handle that is to use |
| a tool such as Spring Cloud Config Server that can be environment aware and serve a different file for |
| each environment. Another option is to include Arbiters in the configuration. |
| </p> |
| |
| <p> |
| An Arbiter is a Log4j plugin that has the job of determining whether other configured elements should be |
| included in the generated configuration. While all other "Core" plugins are designed to execute as part of |
| Log4j's runtime logic Arbiters execute after the Node tree has been constructed but before the tree is |
| converted to a configuration. An Arbiter is a Node itself which is always removed from the Node tree |
| before it the tree is processed. All an arbiter really does is provide a method that returns a boolean |
| result that determines whether the child nodes of the arbiter should remain in the configuration or be |
| pruned. |
| </p> |
| |
| <p> |
| Arbiters may occur anywhere an element is allowed in the configuration. So an Arbiter could encapsulate |
| something as simple as a single property declaration or a whole set of Appenders or Loggers. Arbiters |
| may also be nested although Arbiters that are the descendant of another arbiter will only be evaluated if the |
| ancestor returned true. The child elements of an Arbiter must be valid elements for whatever element is |
| the parent of the Arbiter. |
| </p> |
| |
| <p> |
| This example shows two Arbiters configured that will include either a Console Appender or a List Appender |
| depending on whether the value of the env System Property is "dev" or "prod". |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Configuration name="ConfigTest" status="ERROR" monitorInterval="5"> |
| <Appenders> |
| |
| <SystemPropertyArbiter propertyName="env" propertyValue="dev"> |
| <Console name="Out"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| </SystemPropertyArbiter> |
| <SystemPropertyArbiter propertyName="env" propertyValue="prod"> |
| <List name="Out"> |
| </List> |
| </SystemPropertyArbiter> |
| |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.test" level="trace" additivity="false"> |
| <AppenderRef ref="Out"/> |
| </Logger> |
| <Root level="error"> |
| <AppenderRef ref="Out"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </pre></div> |
| |
| <p> |
| Normally Arbiters act in isolation from other Arbiters. That is, the outcome of one Arbiter will not |
| impact any other Arbiters. This can be cumbersome when you simply want to use one of a set of choices. A |
| special plugin named "Select" can be used in this case. Each element under the Select is required to be |
| an Arbiter. The first Arbiter that returns a true value will be the one used while others are ignored. |
| If no Arbiter returns true a DefaultArbiter may be configured with the default configuration elements. |
| The DefaultArbiter is an Arbiter that always returns true, so using it outside of a Select would result in |
| its configured elements always being included just as if it hadn't been present. |
| </p> |
| |
| <p> |
| This example shows an Arbiter that uses Javascript residing in a separate file to determine whether to |
| include the Console Appender. If the result is false then a List Appender will be included. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Configuration name="ConfigTest" status="ERROR" monitorInterval="5"> |
| <Appenders> |
| <Select> |
| <ScriptArbiter> |
| <ScriptFile language="JavaScript" path="src/test/resources/scripts/prodtest.js" charset="UTF-8" /> |
| <Console name="Out"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| </ScriptArbiter> |
| <DefaultArbiter> |
| <List name="Out"> |
| </List> |
| </DefaultArbiter> |
| </Select> |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.test" level="trace" additivity="false"> |
| <AppenderRef ref="Out"/> |
| </Logger> |
| <Root level="error"> |
| <AppenderRef ref="Out"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </pre></div> |
| |
| <p> |
| Natively Log4j contains the SystemProperty Arbiter that can evaluate whether to include elements based on |
| whether a SystemProperty is non-null or has a specific value, a ClassArbiter that makes its decision |
| based on whether the specified class is present, and a ScriptArbiter that makes its decision based |
| on the result of the script configured with it. |
| </p> |
| |
| <p> |
| For Spring Boot users an Arbiter named <code>SpringProfile</code> has been provided. The specified profiles |
| are evaluated by Spring's <code>Environment.acceptsProfiles()</code> method, so any expressions it supports |
| may be used as the name attribute. |
| </p> |
| |
| <p>This example will use a Console Appender when the Spring profile is "dev" or "staging" and a List |
| Appender when the active profile is "prod". |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <Configuration name="ConfigTest" status="ERROR" monitorInterval="5"> |
| <Appenders> |
| |
| <SpringProfile name="dev | staging"> |
| <Console name="Out"> |
| <PatternLayout pattern="%m%n"/> |
| </Console> |
| </SpringProfile> |
| <SpringProfile name="prod"> |
| <List name="Out"> |
| </List> |
| </SpringProfile> |
| |
| </Appenders> |
| <Loggers> |
| <Logger name="org.apache.test" level="trace" additivity="false"> |
| <AppenderRef ref="Out"/> |
| </Logger> |
| <Root level="error"> |
| <AppenderRef ref="Out"/> |
| </Root> |
| </Loggers> |
| </Configuration> |
| </pre></div> |
| </section> |
| <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 <code>"log4j2.configurationFile"</code> system property and, if set, will attempt to |
| load the configuration using the <code>ConfigurationFactory</code> that matches the file |
| extension. Note that this is not restricted to a location on the local file system and may contain |
| a URL.</li> |
| |
| <li>If no system property is set the properties ConfigurationFactory will look for |
| <code>log4j2-test.properties</code> in the classpath.</li> |
| |
| <li>If no such file is found the YAML ConfigurationFactory will look for |
| <code>log4j2-test.yaml</code> or <code>log4j2-test.yml</code> in the classpath.</li> |
| |
| <li>If no such file is found the JSON ConfigurationFactory will look for |
| <code>log4j2-test.json</code> or <code>log4j2-test.jsn</code> in the classpath.</li> |
| |
| <li>If no such file is found the XML ConfigurationFactory will look for |
| <code>log4j2-test.xml</code> in the classpath.</li> |
| |
| <li>If a test file cannot be located the properties ConfigurationFactory will look for |
| <code>log4j2.properties</code> on the classpath.</li> |
| |
| <li>If a properties file cannot be located the YAML ConfigurationFactory will look for |
| <code>log4j2.yaml</code> or <code>log4j2.yml</code> on the classpath.</li> |
| |
| <li>If a YAML file cannot be located the JSON ConfigurationFactory will look for |
| <code>log4j2.json</code> or <code>log4j2.jsn</code> on the classpath.</li> |
| |
| <li>If a JSON file cannot be located the XML ConfigurationFactory will try to locate |
| <code>log4j2.xml</code> on the classpath.</li> |
| |
| <li>If no configuration file could be located the <code>DefaultConfiguration</code> will |
| be used. This will cause logging output to go to the console.</li> |
| </ol> |
| |
| <p>An example application named <code>MyApp</code> that uses log4j can be used to illustrate how |
| this is done. |
| </p> |
| |
| <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> |
| <code>MyApp</code> begins by importing Log4j related classes. It |
| then defines a static logger variable with the name <code>MyApp</code> |
| which happens to be the fully qualified name of the class. |
| </p> |
| |
| <p> |
| <code>MyApp</code> uses the <code>Bar</code> class defined in the package<code>com.foo</code>. |
| </p> |
| |
| <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 <code>Level.ERROR</code>. |
| </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="Configuration_From_a_URI"></a> |
| <section> |
| <h3><a name="Configuration_From_a_URI"></a>Configuration From a URI</h3> |
| |
| <p> |
| When <code>log4j2.configurationFile</code> references a URL, Log4j will first determine if the URL reference |
| a file using the file protocol. If it does Log4j will validate that the file URL is valid and continue |
| processing as previously described. If it contains a protocol other than file then Log4j will inspect |
| the value of the <code>log4j2.Configuration.allowedProtocols</code> system property. If the provided list |
| contains the protocol specified then Log4j will use the URI to locate the specified configuration file. If |
| not an exception will be thrown and an error message will be logged. If no value is provided for the |
| system property it will default to "https, file, jar". Use of any protocol other than "file" can be |
| prevented by setting the system property value to "_none". This value would be an invalid protocol so cannot |
| conflict with any custom protocols that may be present. |
| </p> |
| |
| <p> |
| Log4j supports access to remote URLs that require authentication. Log4j supports basic authentication |
| out of the box. If the <code>log4j2.Configuration.username</code> and <code>log4j2.Configuration.password</code> |
| are specified those values will be used to perform the authentication. If the password is encrypted a custom |
| password decryptor may be supplied by specifying the fully qualified class name in the |
| <code>log4j2.Configuration.passwordDecryptor</code> system property. A custom |
| <code>AuthenticationProvider</code> may be used by setting the |
| <code>log4j2.Configuration.authenticationProvider</code> system property to the fully qualified class name |
| of the provider. |
| </p> |
| |
| </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 <code>com.foo.Bar</code>. |
| Simply changing the log level would not accomplish the task. Instead, the solution is to |
| add a new logger definition to the configuration: |
| </p> |
| |
| <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 <code>com.foo.Bar</code> will be recorded while only error |
| events will be recorded from all other components. |
| </p> |
| |
| <p> |
| In the previous example all the events from <code>com.foo.Bar</code> were still written to the Console. This is |
| because the logger for <code>com.foo.Bar</code> did not have any appenders configured while its parent did. In fact, |
| the following configuration |
| </p> |
| |
| <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 <code>com.foo.Bar</code> appear twice. This is because the appender associated |
| with logger <code>com.foo.Bar</code> is first used, which writes the first instance to the Console. Next, the parent |
| of <code>com.foo.Bar</code>, which in this case is the root logger, is referenced. The event is then passed to its |
| appender, which is also writes to the Console, resulting in the second instance. This is known as |
| additivity. While additivity can be quite a convenient feature (as in the first previous example where |
| no appender reference needed to be configured), in many cases this behavior is considered undesirable |
| and so it is possible to disable it by setting the additivity attribute on the logger to false: |
| </p> |
| |
| <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 <code>monitorInterval</code> attribute is specified on the configuration |
| element and is set to a non-zero value then the file will be checked the next time a log event is evaluated |
| and/or logged and the monitorInterval has elapsed since the last check. The example below shows how |
| to configure the attribute so that the configuration file will be checked for changes only after at |
| least 30 seconds have elapsed. The minimum interval is 5 seconds. |
| </p> |
| |
| <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="https://github.com/jmdns/jmdns">JmDNS</a> library. |
| </p> |
| |
| <p> |
| Chainsaw automatically discovers log4j's multicastdns-generated advertisements and displays those discovered |
| advertisements in Chainsaw's Zeroconf tab (if the jmdns library is in Chainsaw's classpath). To begin parsing and tailing |
| a log file provided in an advertisement, just double-click the advertised entry in Chainsaw's Zeroconf tab. |
| Currently, Chainsaw only supports FileAppender advertisements. |
| </p> |
| |
| <p> |
| To advertise an appender configuration: |
| </p> |
| |
| <ul> |
| |
| <li>Add the JmDNS library from <a class="externalLink" href="https://github.com/jmdns/jmdns/releases">JmDNS GitHub Releases</a> to the application classpath</li> |
| |
| <li>Set the 'advertiser' attribute of the configuration element to 'multicastdns'</li> |
| |
| <li>Set the 'advertise' attribute on the appender element to 'true'</li> |
| |
| <li>If advertising a FileAppender-based configuration, set the 'advertiseURI' attribute on the appender element to an appropriate URI</li> |
| </ul> |
| |
| <p> |
| FileAppender-based configurations require an additional 'advertiseURI' attribute to be specified on the appender. |
| The 'advertiseURI' attribute provides Chainsaw with information on how the file can be accessed. |
| For example, the file may be remotely accessible to Chainsaw via ssh/sftp by specifying a Commons VFS |
| (<a class="externalLink" href="https://commons.apache.org/proper/commons-vfs/">https://commons.apache.org/proper/commons-vfs/</a>) sftp:// URI, |
| an http:// URI may be used if the file is accessible through a web server, or a file:// URI can be specified |
| if accessing the file from a locally-running instance of Chainsaw. |
| </p> |
| |
| <p> |
| Here is an example advertisement-enabled appender configuration which can be used by a locally-running Chainsaw to |
| automatically tail the log file (notice the file:// advertiseURI): |
| </p> |
| |
| <p> |
| <b>Please note, you must add the JmDNS library mentioned above.</b> |
| </p> |
| |
| <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 align="left">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 align="left">dest</td> |
| |
| <td>Either "err" for stderr, "out" for stdout, a file path, or a URL.</td> |
| </tr> |
| |
| |
| <tr class="b"> |
| |
| <td align="left">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 align="left">name</td> |
| |
| <td>The name of the configuration.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">packages</td> |
| |
| <td><b>Use of the packages attribute is deprecated and will be removed in Log4j 3.0.</b> Plugins |
| should be processed with the Log4j annotation processor. |
| |
| A comma separated list of package names to search for plugins. Plugins are only loaded |
| once per classloader so changing this value may not have any effect upon reconfiguration.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">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 align="left">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 align="left">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 <code>shutdownHook</code> is set to "disable".)</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">status</td> |
| |
| <td> |
| <p>The level of internal Log4j events that should be logged to the console. |
| Valid values for this attribute are "off", "trace", "debug", "info", "warn", "error", "fatal", and |
| "all". Log4j will log details about initialization, rollover and other internal actions to the status |
| logger. Setting <code>status="trace"</code> is one of the first tools available to you if you need to |
| troubleshoot log4j. |
| </p> |
| <p> |
| (Alternatively, setting system property <code>log4j2.debug</code> 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 align="left">strict</td> |
| |
| <td>Enables the use of the strict XML format. Not supported in JSON configurations.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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. |
| |
| <section><section> |
| <h5><a name="Concise_Syntax"></a>Concise Syntax</h5> |
| |
| The concise format makes configuration very easy as the element names match the components they represent |
| however it cannot be validated with an XML schema. For example, the ConsoleAppender is configured by |
| declaring an XML element named Console under its parent appenders element. However, element |
| and attribute names are not case sensitive. In addition, attributes can either be specified |
| as an XML attribute or as an XML element that has no attributes and has a text value. So |
| </p> |
| |
| <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 configured 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"> |
| <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 |
| target: SYSTEM_OUT |
| 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 |
| identifier must not contain a '.'. Each individual component MUST have a "type" attribute |
| specified that identifies the component's Plugin type. |
| </p> |
| |
| <p> |
| As of version 2.6, this list of identifiers is no longer required as names are inferred upon first usage, |
| however if you wish to use more complex identifies you must still use the list. If the list is present |
| it will be used. |
| </p> |
| |
| <p> |
| Unlike the base components, when creating subcomponents you cannot specify an element containing a list of |
| identifiers. Instead, you must define the wrapper element with its type as is shown in the policies |
| definition in the rolling file appender below. You then define each of the subcomponents below that |
| wrapper element, as the TimeBasedTriggeringPolicy and SizeBasedTriggeringPolicy are defined below. |
| </p> |
| |
| <p> |
| As of version 2.17.2, |
| <code>rootLogger</code> and <code>logger.<var>key</var></code> properties can be specified to set the |
| level and zero or more appender refs to create for that logger. The level and appender refs are |
| separated by comma <code>,</code> characters with optional whitespace surrounding the comma. The |
| following example demonstrates how the shorthand is expanded when reading properties configurations. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| appender.stdout.type = Console |
| # ... other appender properties |
| appender.file.type = File |
| # ... other appender properties |
| logger.app = INFO, stdout, file |
| logger.app.name = com.example.app |
| |
| # is equivalent to: |
| # appender.stdout.type = Console |
| # appender.stdout.name = stdout |
| # ... |
| appender.file.type = File |
| appender.file.name = file |
| # ... |
| logger.app.name = com.example.app |
| logger.app.level = INFO |
| logger.app.appenderRef.$1.ref = stdout |
| logger.app.appenderRef.$2.ref = file |
| </pre></div> |
| |
| <p> |
| Properties configuration files support the advertiser, monitorInterval, name, packages, shutdownHook, |
| shutdownTimeout, status, verbose, and dest attributes. See <a href="#ConfigurationSyntax">Configuration Syntax</a> |
| for the definitions of these attributes. |
| </p> |
| |
| <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 = debug, RollingFile |
| logger.rolling.name = com.example.my.app |
| logger.rolling.additivity = false |
| |
| rootLogger = info, STDOUT |
| |
| # or using a grouping element: |
| # rootLogger.level = info |
| # rootLogger.appenderRef.stdout.ref = STDOUT |
| </pre></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 <code>logger</code> element. The <code>logger</code> element |
| must have a name attribute specified, will usually have a level attribute specified and may |
| also have an additivity attribute specified. The level may be configured with one of TRACE, |
| DEBUG, INFO, WARN, ERROR, ALL or OFF. If no level is specified it will default to ERROR. The |
| additivity attribute may be assigned a value of true or false. If the attribute is omitted |
| the default value of true will be used. |
| </p> |
| |
| <p> |
| Capturing location information (the class name, file name, method name, and line number of the caller) |
| can be slow. Log4j tries to optimize this by reducing the size of the stack that must be traversed |
| to find the caller of the logging method. It does this by determining if any component that might |
| be accessed requires location information. This can cause performance issues if a logger is configured |
| at a level like trace or debug with the expectation that most logs will be filtered on an Appender |
| reference or Appender as Log4j will calculate the location information even though the log event |
| is going to be discarded. To disable this behavior the <code>includeLocation</code> attribute |
| can be set to false on the LoggerConfig. This will cause Log4j to defer calculating the location |
| information until absolutely necessary. |
| </p> |
| |
| <p> |
| A LoggerConfig (including the root LoggerConfig) can be configured with properties that will be added |
| to the properties copied from the ThreadContextMap. These properties can be referenced from Appenders, |
| Filters, Layouts, etc just as if they were part of the ThreadContext Map. The properties can contain |
| variables that will be resolved either when the configuration is parsed or dynamically when each |
| event is logged. See <a href="#PropertySubstitution">Property Substitution</a> for more information on |
| using variables. |
| </p> |
| |
| <p> |
| The LoggerConfig may also be configured with one or more AppenderRef elements. Each appender |
| referenced will become associated with the specified LoggerConfig. If multiple appenders |
| are configured on the LoggerConfig each of them be called when processing logging events. |
| </p> |
| |
| <p> |
| <b><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 <code>filter</code> element can be configured, that element may be the |
| <code>filters</code> element which represents the CompositeFilter. The <code>filters</code> element |
| allows any number of <code>filter</code> elements to be configured within it. The following example |
| shows how multiple filters can be configured on the ConsoleAppender. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="debug" name="XMLConfigTest"> |
| <Properties> |
| <Property name="filename">target/test.log</Property> |
| </Properties> |
| <ThresholdFilter level="trace"/> |
| |
| <Appenders> |
| <Console name="STDOUT"> |
| <PatternLayout pattern="%m MDC%X%n"/> |
| </Console> |
| <Console name="FLOW"> |
| <!-- this pattern outputs class name and line number --> |
| <PatternLayout pattern="%C{1}.%M %m %ex%n"/> |
| <filters> |
| <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/> |
| <MarkerFilter marker="EXCEPTION" onMatch="ACCEPT" onMismatch="DENY"/> |
| </filters> |
| </Console> |
| <File name="File" fileName="${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 <code>${name}</code> |
| to be resolved using properties declared in the configuration itself. For example, the following example |
| shows the filename for the rolling file appender being declared as a property. |
| </p> |
| |
| <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> |
| While this is useful, there are many more places properties can originate from. To accommodate this, |
| Log4j also supports the syntax <code>${prefix:name}</code> where the prefix identifies tells Log4j |
| that variable name should be evaluated in a specific context. |
| See the <a href="lookups.html">Lookups</a> manual page for more details. |
| The contexts that are built in to Log4j are: |
| </p> |
| |
| <table border="0" class="table table-striped"> |
| |
| <tr class="a"> |
| |
| <th>Prefix</th> |
| |
| <th>Context</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">bundle</td> |
| |
| <td> |
| Resource bundle. The format is <code>${bundle:BundleName:BundleKey}</code>. |
| The bundle name follows package naming conventions, for example: |
| <code>${bundle:com.domain.Messages:MyKey}</code>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">ctx</td> |
| |
| <td> |
| Retrieves a previously stored valued from the Thread Context Map (MDC). |
| The format is <code>${ctx:some.key}</code>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">date</td> |
| |
| <td> |
| Inserts the current date and/or time using the specified format pattern from the |
| <a class="externalLink" href="https://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a> class. |
| If no pattern is specified, then the default pattern is used. |
| The formats are <code>${date:some.pattern}</code> and <code>${date:}</code>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">docker</td> |
| |
| <td> |
| Returns attributes from the Docker container the application is running in. |
| The format is <code>${docker:some.attribute}</code>. |
| See <a href="../log4j-docker.html">Docker documentation</a> for requirements and a list of available attributes. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">env</td> |
| |
| <td> |
| Retrieves values from system environment variables or default value if the environment variable is not set. |
| The formats are <code>${env:ENV_NAME}</code> and <code>${env:ENV_NAME:-default_value}</code>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">event</td> |
| |
| <td> |
| Retrieves values from fields within the log event. The format is <code>${event:some.field}</code>. |
| See the <a href="lookups.html#eventlookup">Lookups</a> manual page for a list of available fields. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">java</td> |
| |
| <td> |
| Retrieves information about the Java environment the application is running in. |
| The format is <code>${java:some.property}</code>. |
| See the <a href="lookups.html#java-lookup">Lookups</a> manual page for a list of available properties. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">jndi</td> |
| |
| <td> |
| A value set in the default JNDI Context. (Requires system property <code>log4j2.enableJndiLookup</code> to be set to <code>true</code>.) |
| The format is <code>${jndi:logging/context-name}</code>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">jvmrunargs</td> |
| |
| <td> |
| A JVM input argument accessed through JMX, but not a main argument; |
| see <a class="javadoc" href="https://docs.oracle.com/javase/6/docs/api/java/lang/management/RuntimeMXBean.html#getInputArguments--">RuntimeMXBean.getInputArguments()</a>. |
| The format is <code>${jvmrunargs:argument}</code>. |
| Not available on Android or Google App Engine. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">k8s</td> |
| |
| <td> |
| Returns attributes from the Kubernetes environment the application is running in. |
| The format is <code>${k8s:some.attribute}</code>. |
| See the <a href="lookups.html#kubernetes-lookup">Lookups</a> manual page for a list of available attributes. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">log4j</td> |
| |
| <td>Log4j configuration properties. The expressions <code>${log4j:configLocation}</code> and |
| <code>${log4j:configParentLocation}</code> respectively provide the absolute path |
| to the log4j configuration file and its parent folder.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">lower</td> |
| |
| <td> |
| Converts the passed in argument to lower case (usually used with nested lookups). |
| The format is <code>${lower:argument}</code>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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>. |
| The formats are <code>${main:index}</code> for a 0-based index into the argument list and <code>${main:argument.name}</code> for name from the argument list. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">map</td> |
| |
| <td> |
| Provides a base for Properties in the configuration file or retrieves a value from a MapMessage. |
| The format is <code>${map:type}</code>. |
| See the <a href="lookups.html#map-lookup">Lookups</a> manual page for further details. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">marker</td> |
| |
| <td> |
| Allows use of markers in configurations. |
| The formats are <code>${marker:}</code> and <code>${marker:some.name}</code>. |
| See the <a href="lookups.html#marker-lookup">Lookups</a> manual page for further details. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">sd</td> |
| |
| <td>A value from a StructuredDataMessage. The key "id" will return the name of the StructuredDataId |
| without the enterprise number. The key "type" will return the message type. Other keys will |
| retrieve individual elements from the Map.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">spring</td> |
| |
| <td> |
| Returns values of Spring properties from the Spring configuration. |
| The format is <code>${spring:some.property}</code>. |
| See the <a href="lookups.html#spring-boot-lookup">Lookups</a> manual page for requirements and details. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">sys</td> |
| |
| <td> |
| Retrieves values from system properties. |
| The formats are <code>${sys:some.property}</code> and <code>${sys:some.property:-default_value}</code>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">upper</td> |
| |
| <td> |
| Converts the passed in argument to upper case (usually used with nested lookups). |
| The format is <code>${upper:argument}</code>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">web</td> |
| |
| <td> |
| Returns values of variables associated with the Servlet Context. |
| The format is <code>${spring:some.key}</code>. |
| See the <a href="lookups.html#web-lookup">Lookups</a> manual page for a list of available keys. |
| </td> |
| </tr> |
| </table> |
| <a name="DefaultProperties"></a></section><section> |
| <h3><a name="Default_Properties"></a>Default Properties</h3> |
| <p> |
| A default property map can be declared in the configuration file by placing a Properties |
| element directly after the Configuration element and before any Loggers, Filters, |
| Appenders, etc. are declared. If the value cannot be located in the specified lookup the |
| value in the default property map will be used. The default map is pre-populated with a value |
| for "hostName" that is the current system's host name or IP address and |
| the "contextName" with is the value of the current logging context. See many places |
| a Properties element is used in this section for examples. |
| </p> |
| |
| <p> |
| Default properties may also be specified in the Lookup by using the syntax <code>${lookupName:key:-defaultValue}</code>. |
| In some cases the key might contain a leading '-'. When this is the case an escape character must be |
| included, such as <code>${main:\--file:-app.properties}</code>. This would use the |
| <code>MainMapLookup</code> for a key named <code>--file</code>. If the key is not found then |
| <code>app.properties</code> would be used as the default value. |
| </p> |
| </section> |
| <a name="EnablingMessagePatternLookups"></a> |
| <section> |
| <h3><a name="Enabling_Message_Pattern_Lookups"></a>Enabling Message Pattern Lookups</h3> |
| |
| <p> |
| A message is processed (by default) without using lookups, for example if you defined |
| <code> <Property name="foo.bar">FOO_BAR </Property></code>, then <code>logger.info("${foo.bar}")</code> |
| will output <code>${foo.bar}</code> instead of <code>FOO_BAR</code>. You could enable message pattern |
| lookups by defining message pattern using %m{lookups}. |
| </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="https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/">JSR 223</a> |
| scripting languages to be used in some of its components. Any language that provides support for the JSR |
| 223 scripting engine may be used. A list of the languages and bindings for them can be found at the |
| <a 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>As of Log4j 2.17.2 the languages to be supported must be specified as a comma separated list in the |
| <code>log4j2.Script.enableLanguages</code> system property.</p> |
| |
| <p> |
| The components that support using scripts do so by allowing a <script>, <scriptFile>, or |
| <scriptRef> element to be configured on |
| them. The script element contains a name for the script, the language of the script, and the script text. |
| The scriptFile element contains the name of the script, its location, its language, its charset, and |
| whether the file should be watched for changes. The scriptRef element contains the name of the |
| script that is defined in the <scripts> configuration element. |
| The name of the script is used to store the script, along with its ScriptEngine, so it can quickly be |
| located each time the script needs to be run. While the name is not required, providing it will help in |
| debugging problems when the script is running. The language must be provided on the script element and must |
| specify one of the language names that appear in the Configuration status log as described in the next |
| section. If the language is not specified on the scriptFile element the language will be determined by |
| the file extension of the script path. If file monitoring is requested it will only be enabled if |
| a non-zero monitorInterval is specified on the configuration element. That interval will be used to |
| check for changes in the file. |
| </p> |
| |
| <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="https://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 or, when using URLs, by adding secondary configuration |
| locations as query parameters named "override". The merge logic can be controlled by specifying a class |
| that implements the MergeStrategy interface on the log4j.mergeStrategy property. The default |
| merge strategy will merge the files using the following rules: |
| </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 exceptions: |
| |
| <ul> |
| |
| <li>the highest status level will be used</li> |
| |
| <li>the lowest monitorInterval greater than 0 will be used</li> |
| |
| <li>packages are joined with comma</li> |
| </ul> |
| </li> |
| |
| <li>Properties from all configurations are aggregated. Duplicate properties replace those in previous |
| configurations.</li> |
| |
| <li>Filters are aggregated under a CompositeFilter if more than one Filter is defined. Since Filters |
| are not named duplicates may be present.</li> |
| |
| <li>Scripts and ScriptFile references are aggregated. Duplicate definitions replace those in previous |
| configurations.</li> |
| |
| <li>Appenders are aggregated. Appenders with the same name are replaced by those in later |
| configurations, including all of the Appender's subcomponents.</li> |
| |
| <li>Loggers are all aggregated. Logger attributes are individually merged with duplicates being |
| replaced by those in later configurations. Appender references on a Logger are aggregated with |
| duplicates being replaced by those in later configurations. Filters on a Logger are aggregated |
| under a CompositeFilter if more than one Filter is defined. Since Filters are not named |
| duplicates may be present. Filters under Appender references included or discarded depending on |
| whether their parent Appender reference is kept or discarded.</li> |
| </ol> |
| |
| </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 align="left"> |
| <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 |
| <code>log4j2.debug</code> is either defined empty or its value equals to <code>true</code> (ignoring case).</p> |
| |
| <p>Prior to log4j-2.9, there are two places where internal logging can be controlled:</p> |
| |
| <ul> |
| |
| <li>Before a configuration is found, status logger level can be controlled with system |
| property <code>org.apache.logging.log4j.simplelog.StatusLogger.level</code>.</li> |
| |
| <li>After a configuration is found, status logger level can be controlled in the configuration |
| file with the "status" attribute, for example: <code><Configuration status="trace"></code>.</li> |
| </ul> |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| Just as it is desirable to be able to diagnose problems in applications, it is frequently necessary |
| to be able to diagnose problems in the logging configuration or in the configured components. Since |
| logging has not been configured, "normal" logging cannot be used during initialization. In addition, |
| normal logging within appenders could create infinite recursion which Log4j will detect and cause |
| the recursive events to be ignored. To accommodate this need, the Log4j 2 API includes a |
| <a 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 |
| <code>src/test/resources</code> are automatically copied to target/test-classes and are included |
| in the classpath during execution of any tests. As such, placing a log4j2-test.xml into this directory |
| will cause it to be used instead of a log4j2.xml or log4j2.json that might be present. Thus a different |
| log configuration can be used during testing than what is used in production. |
| </p> |
| |
| <p> |
| A second approach, which is extensively used by Log4j 2, is to set the log4j.configurationFile property |
| in the method annotated with @BeforeClass in the junit test class. This will allow an arbitrarily |
| named file to be used during the test. |
| </p> |
| |
| <p> |
| A third approach, also used extensively by Log4j 2, is to use the <code>LoggerContextRule</code> |
| JUnit test rule which provides additional convenience methods for testing. This requires adding the |
| <code>log4j-core</code> <code>test-jar</code> dependency to your test scope dependencies. For example: |
| </p> |
| |
| <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 <code>ServiceLoader</code> |
| mechanism in Java SE. |
| </p> |
| |
| <p> |
| Properties can be overridden by sources with a lower number priority (e.g.., -100 comes before 100). The |
| following sources are all available by default: |
| </p> |
| |
| <table 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 align="left">Spring Boot Properties</td> |
| |
| <td>-100</td> |
| |
| <td> |
| This property source is enabled only if the Java application uses Spring Boot and the |
| <code>log4j-spring</code> module is present. It resolves properties using a Spring |
| <a class="externalLink" href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/env/Environment.html">Environment</a>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">System Properties</td> |
| |
| <td>0</td> |
| |
| <td> |
| All properties can be set using normal system property patterns. These have the lowest numerical priority |
| among commonly available property sources and can override properties files or environment variables. |
| If a <code>log4j2.system.properties</code> file is available on the classpath its contents are |
| sourced into Java system properties at Log4j startup. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">Environment Variables</td> |
| |
| <td>100</td> |
| |
| <td> |
| Environment variables are all prefixed with <code>LOG4J_</code>, are in all caps, and words are all |
| separated by underscores. Only this naming scheme is support for environment variables as there were |
| no old naming schemes to maintain compatibility with. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><code>log4j2.component.properties</code> file</td> |
| |
| <td>200</td> |
| |
| <td> |
| Including this file on the classpath can be used as an alternative to providing properties as system |
| properties. This is the property source with highest numerical priority and can be used to provide |
| default values that can be overridden by the system administrator. |
| </td> |
| </tr> |
| </table> |
| |
| <p> |
| The following is a list of available global configuration properties. Note that these can only be set once |
| per JVM process unlike configuration settings available in configuration files. The <i>Property Name</i> |
| column contains the name used in properties files and system properties; <i>Environment Variable</i> |
| for the equivalent environment variable; and <i>Legacy Property Name</i> for the pre-2.10 name. |
| </p> |
| <style></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 align="left"><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. |
| May contain a URL. When specified as a URL the "override" query parameter may be used to specify additional |
| configuration file locations. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 |
| <code>log4j2.debug</code> is either defined empty or its value equals to <code>true</code> (ignoring case). |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="mergeStrategy"></a>log4j2.mergeStrategy |
| <br /> |
| (<a name="log4j.mergeStrategy"></a>log4j.mergeStrategy) |
| </td> |
| |
| <td>LOG4J_MERGE_STRATEGY</td> |
| |
| <td> </td> |
| |
| <td> |
| The name of the class that implements the MergeStrategy interface. If not specified |
| <code>DefaultMergeStrategy</code> will be used when creating a CompositeConfiguration.. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="contextSelector"></a>log4j2.contextSelector |
| <br /> |
| (<a name="Log4jContextSelector"></a>Log4jContextSelector) |
| </td> |
| |
| <td>LOG4J_CONTEXT_SELECTOR</td> |
| |
| <td>ClassLoaderContextSelector</td> |
| |
| <td> |
| Creates the <code>LoggerContext</code>s. An application can have one or more active LoggerContexts depending |
| on the circumstances. |
| See <a href="logsep.html">Log Separation</a> for more details. |
| Available context selector implementation classes:<br /> |
| |
| <code>org.apache.logging.log4j.core.async .AsyncLoggerContextSelector</code> - makes <a href="async.html">all loggers asynchronous</a>.<br /> |
| <code>org.apache.logging.log4j.core.async .BasicAsyncLoggerContextSelector</code> - makes <a href="async.html">all loggers asynchronous</a> using a single shared AsyncLoggerContext.<br /> |
| <code>org.apache.logging.log4j.core.selector .BasicContextSelector</code> - creates a single shared LoggerContext.<br /> |
| <code>org.apache.logging.log4j.core.selector .ClassLoaderContextSelector</code> - separate LoggerContexts for each web application.<br /> |
| <code>org.apache.logging.log4j.core.selector .JndiContextSelector</code> - use JNDI to locate each web application's LoggerContext.<br /> |
| <code>org.apache.logging.log4j.core.osgi .BundleContextSelector</code> - separate LoggerContexts for each OSGi bundle. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>LogEvent</code> instances. |
| (Ignored when the <code>AsyncLoggerContextSelector</code> is used.) |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>org.apache.logging.log4j.core |
| .impl.Log4jContextFactory</code>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>org.apache.logging.log4j.core |
| .config.ConfigurationFactory</code>. |
| If specified, an instance of this class is added to the list of configuration factories. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="configurationAllowedProtocols"></a>log4j2.Configuration.allowedProtocols |
| <br /> |
| (<a name="log4j.configurationAllowedProtocols"></a>log4j.configurationAllowedProtocols) |
| </td> |
| |
| <td>LOG4J_CONFIGURATION_ALLOWED_PROTOCOLS</td> |
| |
| <td> </td> |
| |
| <td> |
| A comma separated list of the protocols that may be used to load a configuration file. The default is |
| "https, file, jar". To completely prevent accessing the configuration via a URL specify a value of "_none". |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="log4j2.configurationAuthorizationEncoding"></a>log4j2.configurationAuthorizationEncoding</td> |
| |
| <td>LOG4J_CONFIGURATION_AUTHORIZATION_ENCODING</td> |
| |
| <td>UTF-8</td> |
| |
| <td> |
| The encoding used in Basic Authentication (cf. <a class="externalLink" href="https://datatracker.ietf.org/doc/html/rfc7617">RFC 7617</a>). |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="configurationAuthorizationProvider"></a>log4j2.Configuration.authorizationProvider |
| <br /> |
| (<a name="log4j.configurationAuthorizationProvider"></a>log4j.configurationAuthorizationProvider |
| </td> |
| |
| <td>LOG4J_CONFIGURATION_AUTHORIZATION_PROVIDER</td> |
| |
| <td>org.apache.logging.log4j.core.util.BasicAuthorizationProvider</td> |
| |
| <td> |
| The fully qualified class name of the AuthorizationProvider. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="configurationPassword"></a>log4j2.Configuration.password |
| <br /> |
| (<a name="log4j.configurationPassword"></a>log4j.configurationPassword |
| </td> |
| |
| <td>LOG4J_CONFIGURATION_PASSWORD</td> |
| |
| <td> </td> |
| |
| <td> |
| The password required to access the remote logging configuration file. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="configurationPasswordDecryptor"></a>log4j2.Configuration.passwordDecryptor |
| <br /> |
| (<a name="log4j.configurationPasswordDecryptor"></a>log4j.configurationPasswordDecryptor |
| </td> |
| |
| <td>LOG4J_CONFIGURATION_PASSWORD_DECRYPTOR</td> |
| |
| <td> </td> |
| |
| <td> |
| If the password is encrypted this class will be used to decrypt it. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="configurationUsername"></a>log4j2.Configuration.username |
| <br /> |
| (<a name="log4j.configurationUsername"></a>log4j.configurationUsername |
| </td> |
| |
| <td>LOG4J_CONFIGURATION_USERNAME</td> |
| |
| <td> </td> |
| |
| <td> |
| The user name required to access the remote logging configuration file. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>LoggerContext</code>. |
| By default, this is enabled and can be disabled on a per-configuration basis. When running with the |
| <code>log4j-web</code> module, this is automatically disabled. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>DefaultShutdownCallbackRegistry</code>. |
| The specified class must have a default constructor. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>org.apache.logging.log4j .core.util.Clock</code> |
| interface that is used for timestamping the log events. |
| <br /> |
| By default, <code>System.currentTimeMillis</code> is called on every log event. |
| <br /> |
| You can also specify a fully qualified class name of a custom class that implements the |
| <code>Clock</code> interface. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 align="left"><a name="disableThreadContext"></a>log4j2.disableThreadContext |
| <br /> |
| (disableThreadContext) |
| </td> |
| |
| <td>LOG4J_DISABLE_THREAD_CONTEXT</td> |
| |
| <td>false</td> |
| |
| <td> |
| If <code>true</code>, the ThreadContext stack and map are disabled. |
| (May be ignored if a custom ThreadContext map is specified.) |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="disableThreadContextStack"></a>log4j2.disableThreadContextStack |
| <br /> |
| (disableThreadContextStack) |
| </td> |
| |
| <td>LOG4J_DISABLE_THREAD_CONTEXT_STACK</td> |
| |
| <td>false</td> |
| |
| <td> |
| If <code>true</code>, the ThreadContext stack is disabled. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="disableThreadContextMap"></a>log4j2.disableThreadContextMap |
| <br /> |
| (disableThreadContextMap) |
| </td> |
| |
| <td>LOG4J_DISABLE_THREAD_CONTEXT_MAP</td> |
| |
| <td>false</td> |
| |
| <td> |
| If <code>true</code>, the ThreadContext map is disabled. |
| (May be ignored if a custom ThreadContext map is specified.) |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>ThreadContextMap</code> implementation class. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="isThreadContextMapInheritable"></a>log4j2.isThreadContextMapInheritable |
| <br /> |
| (isThreadContextMapInheritable) |
| </td> |
| |
| <td>LOG4J_IS_THREAD_CONTEXT_MAP_INHERITABLE</td> |
| |
| <td>false</td> |
| |
| <td> |
| If <code>true</code> use a <code>InheritableThreadLocal</code> to implement the ThreadContext map. |
| Otherwise, use a plain <code>ThreadLocal</code>. |
| (May be ignored if a custom ThreadContext map is specified.) |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>ContextDataInjector</code> implementation class. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 align="left"><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 <code>true</code>, 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 align="left"><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 <code>true</code>, log4j's JMX notifications are sent from a separate background thread, |
| otherwise they are sent from the caller thread. |
| If system property <code>log4j2.is.webapp</code> is <code>true</code> or the <code>javax.servlet.Servlet</code> |
| class is on the classpath, the default behaviour |
| is to use the caller thread to send JMX notifications. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>true</code>, the ConsoleAppender will not try to use the Jansi output stream on Windows. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>true</code>, 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 align="left"><a name="enableJndiContextSelector"></a>log4j2.enableJndiContextSelector</td> |
| |
| <td>LOG4J_ENABLE_JNDI_CONTEXT_SELECTOR</td> |
| |
| <td>false</td> |
| |
| <td> |
| When true, the Log4j context selector that uses the JNDI java protocol is enabled. When false, the default, they are disabled. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="enableJndiJdbc"></a>log4j2.enableJndiJdbc</td> |
| |
| <td>LOG4J_ENABLE_JNDI_JDBC</td> |
| |
| <td>false</td> |
| |
| <td> |
| When true, a Log4j JDBC Appender configured with a <code>DataSource</code> which uses JNDI's java protocol is enabled. When false, the default, they are disabled. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="enableJndiJms"></a>log4j2.enableJndiJms</td> |
| |
| <td>LOG4J_ENABLE_JNDI_JMS</td> |
| |
| <td>false</td> |
| |
| <td> |
| When true, a Log4j JMS Appender that uses JNDI's java protocol is enabled. When false, the default, they are disabled. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="enableJndiLookup"></a>log4j2.enableJndiLookup</td> |
| |
| <td>LOG4J_ENABLE_JNDI_LOOKUP</td> |
| |
| <td>false</td> |
| |
| <td> |
| When true, a Log4j lookup that uses JNDI's java protocol is enabled. When false, the default, they are disabled. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 align="left"><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 <code>true</code>, the full ThreadContext map is included in each SimpleLogger log message.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 <code>true</code>, the logger name is included in each SimpleLogger log message.</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>true</code>, 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 align="left"><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 <code>true</code>, SimpleLogger log messages contain timestamp information. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>org.apache.logging.log4j .simplelog.showdatetime</code> is <code>false</code>. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 align="left"><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 align="left">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 align="left"><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 |
| <code>StatusLogger.getLogger() .setLevel(someLevel)</code>. |
| Note that the StatusLogger level is only used to determine the status log output level |
| until a listener is registered. In practice, a listener is registered when a configuration is found, |
| and from that point onwards, status messages are only sent to the listeners (depending on their statusLevel).</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 align="left"><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 |
| <code><Configuration status="trace"></code>, a listener with statusLevel TRACE is registered |
| and the StatusLogger listenerLevel is set to TRACE, resulting in verbose status messages displayed on the console. |
| </p> |
| <p> |
| If no listeners are registered, the listenersLevel is not used, and the StatusLogger output level |
| is determined by <code>StatusLogger.getLogger().getLevel()</code> |
| (see property <code>org.apache.logging.log4j.simplelog .StatusLogger.level</code>).</p> |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 |
| <code>StatusLogger.getStatusData()</code>. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>java.text.SimpleDateFormat</code> for supported formats. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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 align="left"><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 align="left"><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 align="left"><a name="asyncLoggerTimeout"></a>log4j2.asyncLoggerTimeout |
| <br /> |
| (<a name="AsyncLogger.Timeout"></a>AsyncLogger.Timeout) |
| </td> |
| |
| <td>LOG4J_ASYNC_LOGGER_TIMEOUT</td> |
| |
| <td> |
| 10 |
| </td> |
| |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="asyncLoggerSleepTimeNs"></a>log4j2.asyncLoggerSleepTimeNs |
| <br /> |
| (<a name="AsyncLogger.SleepTimeNs"></a>AsyncLogger.SleepTimeNs) |
| </td> |
| |
| <td>LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS</td> |
| |
| <td> |
| 100 |
| </td> |
| |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="asyncLoggerRetries"></a>log4j2.asyncLoggerRetries |
| <br /> |
| (<a name="AsyncLogger.Retries"></a>AsyncLogger.Retries) |
| </td> |
| |
| <td>LOG4J_ASYNC_LOGGER_SLEEP_TIME_NS</td> |
| |
| <td> |
| 200 |
| </td> |
| |
| <td> |
| See <a href="async.html#SysPropsAllAsync">Async Logger System Properties</a> for details. |
| </td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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 |
| <code>org.apache.logging.log4j.jul .CoreLoggerAdapter</code> will be used. Otherwise, the |
| <code>ApiLoggerAdapter</code> will be used. Custom implementations must provide a public default constructor. |
| </td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left"><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 <code>false</code> (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="b"> |
| |
| <td align="left"><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 <code>Discard</code> 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="a"> |
| |
| <td align="left"><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, <code>INFO</code>, <code>DEBUG</code> and <code>TRACE</code> level |
| events are discarded when the queue is full. |
| This property only has effect if <code>Discard</code> is specified as the |
| <code>log4j2.AsyncQueueFullPolicy</code>.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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 <code>Servlet</code> 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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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 <code>true</code> 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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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 <code>org.apache.logging.log4j.util.Unbox</code> utility |
| manages a small thread-local ring buffer of StringBuilders. |
| Each time one of the <code>box()</code> 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 <code>log4j.unbox.ringbuffer.size</code> 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="a"> |
| |
| <td align="left"><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="b"> |
| |
| <td align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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 align="left"><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> |
| |
| <tr class="a"> |
| |
| <td align="left"><a name="log4j2.Script.enableLanguages"></a>log4j2.Script.enableLanguages</td> |
| |
| <td></td> |
| |
| <td></td> |
| |
| <td>The list of script languages that are allowed to execute. The names specified must have a ScriptEngine installed |
| that advertises the same language(s) in order for scripting to be enabled. If no languages are specified, which is |
| the default, the ScriptManager will not be installed.</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left"><a name="log4j2.disableCloudConfigLoggingSystem"></a>log4j2.disableCloudConfigLoggingSystem</td> |
| |
| <td></td> |
| |
| <td></td> |
| |
| <td>Disables the usage of the Spring Boot <code>Log4j2CloudConfigLoggingSystem</code>. Defaults to <code>false</code>.</td> |
| </tr> |
| </table> |
| |
| </section> |
| </section> |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2024 <a class="external" href="https://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> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |