ConfigurationInserting 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. Configuration of Log4j 2 can be accomplished in 1 of 4 ways:
This page focuses primarily on configuring Log4j through a configuration file. Information on programmatically configuring Log4j can be found at Extending Log4j 2. 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. Automatic ConfigurationLog4j has the ability to automatically configure itself during initialization. When Log4j starts it will locate all the ConfigurationFactory plugins and arrange then in weighted order from highest to lowest. As delivered, Log4j contains three ConfigurationFactory implementations: one for JSON, one for YAML, and one for XML.
An example application named MyApp that uses log4j can be used to illustrate how this is done. 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."); } } MyApp begins by importing log4j related classes. It then defines a static logger variable with the name MyApp which happens to be the fully qualified name of the class. MyApp uses the Bar class defined in the packagecom.foo. 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); } } Log4j will provide a default configuration if it cannot locate a configuration file. The default configuration, provided in the DefaultConfiguration class, will set up:
Note that by default Log4j assigns the root logger to Level.ERROR. The output of MyApp would be similar to: 17:13:01.540 [main] ERROR com.foo.Bar - Did it again! 17:13:01.540 [main] ERROR MyApp - Didn't do it. As was described previously, Log4j will first attempt to configure itself from configuration files. A configuration equivalent to the default would look like: <?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> 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: 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. Note that status logging is disabled when the default configuration is used. Perhaps it is desired to eliminate all the TRACE output from everything except com.foo.Bar. Simply changing the log level would not accomplish the task. Instead, the solution is to add a new logger definition to the configuration: <Logger name="com.foo.Bar" level="TRACE"/> <Root level="ERROR"> <AppenderRef ref="STDOUT"> </Root> With this configuration all log events from com.foo.Bar will be recorded while only error events will be recorded from all other components. AdditivityIn the previous example all the events from com.foo.Bar were still written to the Console. This is because the logger for com.foo.Bar did not have any appenders configured while its parent did. In fact, the following configuration <?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> would result in 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. Notice that the trace messages from com.foo.Bar appear twice. This is because the appender associated with logger com.foo.Bar is first used, which writes the first instance to the Console. Next, the parent of com.foo.Bar, which in this case is the root logger, is referenced. The event is then passed to its appender, which is also writes to the Console, resulting in the second instance. This is known as additivity. While additivity can be quite a convenient feature (as in the first previous example where no appender reference needed to be configured), in many cases this behavior is considered undesirable and so it is possible to disable it by setting the additivity attribute on the logger to false: <?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> 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. Automatic ReconfigurationWhen configured from a File, Log4j has the ability to automatically detect changes to the configuration file and reconfigure itself. If the monitorInterval attribute is specified on the configuration element and is set to a non-zero value then the file will be checked the next time a log event is evaluated and/or logged and the monitorInterval has elapsed since the last check. The example below shows how to configure the attribute so that the configuration file will be checked for changes only after at least 30 seconds have elapsed. The minimum interval is 5 seconds. <?xml version="1.0" encoding="UTF-8"?> <Configuration monitorInterval="30"> ... </Configuration> Chainsaw can automatically process your log files (Advertising appender configurations)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. 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. Log4j provides one Advertiser implementation, a 'multicastdns' Advertiser, which advertises appender configuration details via IP multicast using the http://jmdns.sourceforge.net library. 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. To advertise an appender configuration:
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 (http://commons.apache.org/proper/commons-vfs/) 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. 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): Please note, you must add the JmDns library from http://jmdns.sourceforge.net to your application classpath in order to advertise with the 'multicastdns' advertiser. <?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> Configuration SyntaxAs 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. The configuration element in the XML file accepts several attributes:
Log4j can be configured using two XML flavors; concise and strict. The concise format makes configuration very easy as the element names match the components they represent however it cannot be validated with an XML schema. For example, the ConsoleAppender is configured by declaring an XML element named Console under its parent appenders element. However, element and attribute names are are not case sensitive. In addition, attributes can either be specified as an XML attribute or as an XML element that has no attributes and has a text value. So <PatternLayout pattern="%m%n"/> and <PatternLayout> <Pattern>%m%n</Pattern> </PatternLayout> are equivalent. 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. <?xml version="1.0" encoding="UTF-8"?>; <Configuration> <Properties> <Property name="name1">value</property> <Property name="name2" value="value2"/> </Properties> <filter ... /> <Appenders> <appender ... > <filter ... /> </appender> ... </Appenders> <Loggers> <Logger name="name1"> <filter ... /> </Logger> ... <Root level="level"> <AppenderRef ref="name"/> </Root> </Loggers> </Configuration> See the many examples on this page for sample appender, filter and logger declarations. Strict XMLIn addition to the concise XML format above, Log4j allows configurations to be specified in a more "normal" XML manner that can be validated using an XML Schema. This is accomplished by replacing the friendly element names above with their object type as shown below. For example, instead of the ConsoleAppender being configuerd using an element named Console it is instead configured as an appender element with a type attribute containing "Console". <?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> Below is a sample configuration using the strict format. <?xml version="1.0" encoding="UTF-8"?> <Configuration status="debug" strict="true" name="XMLConfigTest" packages="org.apache.logging.log4j.test"> <Properties> <Property name="filename">target/test.log</Property> </Properties> <Filter type="ThresholdFilter" level="trace"/> <Appenders> <Appender type="Console" name="STDOUT"> <Layout type="PatternLayout" pattern="%m MDC%X%n"/> <Filters> <Filter type="MarkerFilter" marker="FLOW" onMatch="DENY" onMismatch="NEUTRAL"/> <Filter type="MarkerFilter" marker="EXCEPTION" onMatch="DENY" onMismatch="ACCEPT"/> </Filters> </Appender> <Appender type="Console" name="FLOW"> <Layout type="PatternLayout" pattern="%C{1}.%M %m %ex%n"/><!-- class and line number --> <Filters> <Filter type="MarkerFilter" marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/> <Filter type="MarkerFilter" marker="EXCEPTION" onMatch="ACCEPT" onMismatch="DENY"/> </Filters> </Appender> <Appender type="File" name="File" fileName="${filename}"> <Layout type="PatternLayout"> <Pattern>%d %p %C{1.} [%t] %m%n</Pattern> </Layout> </Appender> <Appender type="List" name="List"> </Appender> </Appenders> <Loggers> <Logger name="org.apache.logging.log4j.test1" level="debug" additivity="false"> <Filter type="ThreadContextMapFilter"> <KeyValuePair key="test" value="123"/> </Filter> <AppenderRef ref="STDOUT"/> </Logger> <Logger name="org.apache.logging.log4j.test2" level="debug" additivity="false"> <AppenderRef ref="File"/> </Logger> <Root level="trace"> <AppenderRef ref="List"/> </Root> </Loggers> </Configuration> Configuration with JSONIn 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. { "configuration": { "status": "error", "name": "RoutingTest", "packages": "org.apache.logging.log4j.test", "properties": { "property": { "name": "filename", "value" : "target/rolling1/rollingtest-$${sd:type}.log" } }, "ThresholdFilter": { "level": "debug" }, "appenders": { "Console": { "name": "STDOUT", "PatternLayout": { "pattern": "%m%n" } }, "List": { "name": "List", "ThresholdFilter": { "level": "debug" } }, "Routing": { "name": "Routing", "Routes": { "pattern": "$${sd:type}", "Route": [ { "RollingFile": { "name": "Rolling-${sd:type}", "fileName": "${filename}", "filePattern": "target/rolling1/test1-${sd:type}.%i.log.gz", "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"}, "SizeBasedTriggeringPolicy": { "size": "500" } } }, { "AppenderRef": "STDOUT", "key": "Audit"}, { "AppenderRef": "List", "key": "Service"} ] } } }, "loggers": { "logger": { "name": "EventLogger", "level": "info", "additivity": "false", "AppenderRef": { "ref": "Routing" }}, "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }} } } } 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. { "configuration": { "status": "debug", "name": "RoutingTest", "packages": "org.apache.logging.log4j.test", "properties": { "property": { "name": "filename", "value" : "target/rolling1/rollingtest-$${sd:type}.log" } }, "ThresholdFilter": { "level": "debug" }, "appenders": { "appender": [ { "type": "Console", "name": "STDOUT", "PatternLayout": { "pattern": "%m%n" }}, { "type": "List", "name": "List", "ThresholdFilter": { "level": "debug" }}, { "type": "Routing", "name": "Routing", "Routes": { "pattern": "$${sd:type}", "Route": [ { "RollingFile": { "name": "Rolling-${sd:type}", "fileName": "${filename}", "filePattern": "target/rolling1/test1-${sd:type}.%i.log.gz", "PatternLayout": {"pattern": "%d %p %c{1.} [%t] %m%n"}, "SizeBasedTriggeringPolicy": { "size": "500" } } }, { "AppenderRef": "STDOUT", "key": "Audit"}, { "AppenderRef": "List", "key": "Service"} ] } } ] }, "loggers": { "logger": [ { "name": "EventLogger", "level": "info", "additivity": "false", "AppenderRef": { "ref": "Routing" }}, { "name": "com.foo.bar", "level": "error", "additivity": "false", "AppenderRef": { "ref": "Console" }} ], "root": { "level": "error", "AppenderRef": { "ref": "STDOUT" }} } } } The JSON support uses the Jackson Data Processor to parse the JSON files. These dependencies must be added to a project that wants to use JSON for configuration: <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.6.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.6.2</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-annotations</artifactId> <version>2.6.2</version> </dependency> Configuring loggersAn understanding of how loggers work in Log4j is critical before trying to configure them. Please reference the Log4j architecture if more information is required. Trying to configure Log4j without understanding those concepts will lead to frustration. A LoggerConfig is configured using the logger element. The logger element must have a name attribute specified, will usually have a level attribute specified and may also have an additivity attribute specified. The level may be configured with one of TRACE, DEBUG, INFO, WARN, ERROR, ALL or OFF. If no level is specified it will default to ERROR. The additivity attribute may be assigned a value of true or false. If the attribute is omitted the default value of false will be used. 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 Property Substitution for more information on using variables. 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. Every configuration must have a root logger. 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
Configuring AppendersAn appender is configured either using the specific appender plugin's name or with an appender element and the type attibute containing the appender plugin's name. In addition each appender must have a name attribute specified with a value that is unique within the set of appenders. The name will be used by loggers to reference the appender as described in the previous section. 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. Configuring FiltersLog4j allows a filter to be specified in any of 4 places:
Although only a single filter element can be configured, that element may be the filters element which represents the CompositeFilter. The filters element allows any number of filter elements to be configured within it. The following example shows how multiple filters can be configured on the ConsoleAppender. <?xml version="1.0" encoding="UTF-8"?> <Configuration status="debug" name="XMLConfigTest" packages="org.apache.logging.log4j.test"> <Properties> <Property name="filename">target/test.log</Property> </Properties> <ThresholdFilter level="trace"/> <Appenders> <Console name="STDOUT"> <PatternLayout pattern="%m MDC%X%n"/> </Console> <Console name="FLOW"> <!-- this pattern outputs class name and line number --> <PatternLayout pattern="%C{1}.%M %m %ex%n"/> <filters> <MarkerFilter marker="FLOW" onMatch="ACCEPT" onMismatch="NEUTRAL"/> <MarkerFilter marker="EXCEPTION" onMatch="ACCEPT" onMismatch="DENY"/> </filters> </Console> <File name="File" fileName="${filename}"> <PatternLayout> <pattern>%d %p %C{1.} [%t] %m%n</pattern> </PatternLayout> </File> <List name="List"> </List> </Appenders> <Loggers> <Logger name="org.apache.logging.log4j.test1" level="debug" additivity="false"> <ThreadContextMapFilter> <KeyValuePair key="test" value="123"/> </ThreadContextMapFilter> <AppenderRef ref="STDOUT"/> </Logger> <Logger name="org.apache.logging.log4j.test2" level="debug" additivity="false"> <Property name="user">${sys:user.name}</Property> <AppenderRef ref="File"> <ThreadContextMapFilter> <KeyValuePair key="test" value="123"/> </ThreadContextMapFilter> </AppenderRef> <AppenderRef ref="STDOUT" level="error"/> </Logger> <Root level="trace"> <AppenderRef ref="List"/> </Root> </Loggers> </Configuration> Configuration with PropertiesAs 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. 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 component.identifier. 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. Each individual component MUST have a "type" attribute specified that identifies the component's Plugin type. 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. Properties configuration files support the advertiser, monitorInterval, name, packages, shutdownHook, status, and verbose attrbutes. See Configuration Syntax for the definitions of these attributes. status = error name = PropertiesConfig property.filename = target/rolling/rollingtest.log filters = threshold filter.threshold.type = ThresholdFilter filter.threshold.level = debug appenders = console, rolling, list appender.console.type = Console appender.console.name = STDOUT appender.console.layout.type = PatternLayout appender.console.layout.pattern = %m%n 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.list.type = List appender.list.name = List appender.list.filters = threshold appender.list.filter.threshold.type = ThresholdFilter appender.list.filter.threshold.level = error loggers = rolling logger.rolling.name = org.apache.logging.log4j.core.appender.rolling logger.rolling.level = debug logger.rolling.additivity = false logger.rolling.appenderRefs = rolling logger.rolling.appenderRef.rolling.ref = RollingFile rootLogger.level = info rootLogger.appenderRefs = stdout rootLogger.appenderRef.stdout.ref = STDOUT Property SubstitutionLog4j 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 Apache Commons Lang's StrSubstitutor and StrLookup classes. In a manner similar to Ant or Maven, this allows variables declared as ${name} to be resolved using properties declared in the configuration itself. For example, the following example shows the filename for the rolling file appender being declared as a property. <?xml version="1.0" encoding="UTF-8"?> <Configuration status="debug" name="RoutingTest" packages="org.apache.logging.log4j.test"> <Properties> <Property name="filename">target/rolling1/rollingtest-$${sd:type}.log</Property> </Properties> <ThresholdFilter level="debug"/> <Appenders> <Console name="STDOUT"> <PatternLayout pattern="%m%n"/> </Console> <List name="List"> <ThresholdFilter level="debug"/> </List> <Routing name="Routing"> <Routes pattern="$${sd:type}"> <Route> <RollingFile name="Rolling-${sd:type}" fileName="${filename}" filePattern="target/rolling1/test1-${sd:type}.%i.log.gz"> <PatternLayout> <pattern>%d %p %c{1.} [%t] %m%n</pattern> </PatternLayout> <SizeBasedTriggeringPolicy size="500" /> </RollingFile> </Route> <Route ref="STDOUT" key="Audit"/> <Route ref="List" key="Service"/> </Routes> </Routing> </Appenders> <Loggers> <Logger name="EventLogger" level="info" additivity="false"> <AppenderRef ref="Routing"/> </Logger> <Root level="error"> <AppenderRef ref="STDOUT"/> </Root> </Loggers> </Configuration> While this is useful, there are many more places properties can originate from. To accommodate this, Log4j also supports the syntax ${prefix:name} where the prefix identifies tells Log4j that variable name should be evaluated in a specific context. The contexts that are built in to Logj4 are:
A default property map can be declared in the configuration file. If the value cannot be located in the specified lookup the value in the default property map will be used. The default map is pre-populated with a value for "hostName" that is the current system's host name or IP address and the "contextName" with is the value of the current logging context. An interesting feature of StrLookup processing is that when a variable reference is declared with multiple leading '$' characters each time the variable is resolved the leading '$' is simply removed. In the previous example the "Routes" element is capable of resolving the variable at runtime. To allow this the prefix value is specified as a variable with two leading '$' characters. When the configuration file is first processed the first variable is simply removed. Thus, when the Routes element is evaluated at runtime it is the variable declaration "${sd:type}" which causes the event to be inspected for a StructuredDataMessage and if one is present the value of its type attribute to be used as the routing key. Not all elements support resolving variables at runtime. Components that do will specifically call that out in their documentation. 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: <?xml version="1.0" encoding="UTF-8"?> <Configuration> <Properties> <Property name="type">Audit</property> </Properties> ... </Configuration> 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 RoutingAppender for more information. XIncludeXML configuration files can include other files with XInclude. Here is an example log4j2.xml file that includes two other files: <?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> log4j-xinclude-appenders.xml: <?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> log4j-xinclude-loggers.xml: <?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> Status Messages
Just as it is desirable to be able to diagnose problems in applications, it is frequently necessary to be able to diagnose problems in the logging configuration or in the configured components. Since logging has not been configured, "normal" logging cannot be used during initialization. In addition, normal logging within appenders could create infinite recursion which Log4j will detect and cause the recursive events to be ignored. To accomodate this need, the Log4j 2 API includes a StatusLogger. Components declare an instance of the StatusLogger similar to: protected final static Logger logger = StatusLogger.getLogger(); Since StatusLogger implements the Log4j 2 API's Logger interface, all the normal Logger methods may be used. 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. <?xml version="1.0" encoding="UTF-8"?>; <Configuration status="debug" name="RoutingTest"> <Properties> <Property name="filename">target/rolling1/rollingtest-$${sd:type}.log</Property> </Properties> <ThresholdFilter level="debug"/> <Appenders> <Console name="STDOUT"> <PatternLayout pattern="%m%n"/> </Console> <List name="List"> <ThresholdFilter level="debug"/> </List> <Routing name="Routing"> <Routes pattern="$${sd:type}"> <Route> <RollingFile name="Rolling-${sd:type}" fileName="${filename}" filePattern="target/rolling1/test1-${sd:type}.%i.log.gz"> <PatternLayout> <pattern>%d %p %c{1.} [%t] %m%n</pattern> </PatternLayout> <SizeBasedTriggeringPolicy size="500" /> </RollingFile> </Route> <Route ref="STDOUT" key="Audit"/> <Route ref="List" key="Service"/> </Routes> </Routing> </Appenders> <Loggers> <Logger name="EventLogger" level="info" additivity="false"> <AppenderRef ref="Routing"/> </Logger> <Root level="error"> <AppenderRef ref="STDOUT"/> </Root> </Loggers> </Configuration> During startup this configuration produces: 2011-11-23 17:08:00,769 DEBUG Generated plugins in 0.003374000 seconds 2011-11-23 17:08:00,789 DEBUG Calling createProperty on class org.apache.logging.log4j.core.config.Property for element property with params(name="filename", value="target/rolling1/rollingtest-${sd:type}.log") 2011-11-23 17:08:00,792 DEBUG Calling configureSubstitutor on class org.apache.logging.log4j.core.config.PropertiesPlugin for element properties with params(properties={filename=target/rolling1/rollingtest-${sd:type}.log}) 2011-11-23 17:08:00,794 DEBUG Generated plugins in 0.001362000 seconds 2011-11-23 17:08:00,797 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null") 2011-11-23 17:08:00,800 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout with params(pattern="%m%n", Configuration(RoutingTest), null, charset="null") 2011-11-23 17:08:00,802 DEBUG Generated plugins in 0.001349000 seconds 2011-11-23 17:08:00,804 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.ConsoleAppender for element Console with params(PatternLayout(%m%n), null, target="null", name="STDOUT", ignoreExceptions="null") 2011-11-23 17:08:00,804 DEBUG Calling createFilter on class org.apache.logging.log4j.core.filter.ThresholdFilter for element ThresholdFilter with params(level="debug", onMatch="null", onMismatch="null") 2011-11-23 17:08:00,806 DEBUG Calling createAppender on class org.apache.logging.log4j.test.appender.ListAppender for element List with params(name="List", entryPerNewLine="null", raw="null", null, ThresholdFilter(DEBUG)) 2011-11-23 17:08:00,813 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="null", key="null", Node=Route) 2011-11-23 17:08:00,823 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="STDOUT", key="Audit", Node=Route) 2011-11-23 17:08:00,824 DEBUG Calling createRoute on class org.apache.logging.log4j.core.appender.routing.Route for element Route with params(AppenderRef="List", key="Service", Node=Route) 2011-11-23 17:08:00,825 DEBUG Calling createRoutes on class org.apache.logging.log4j.core.appender.routing.Routes for element Routes with params(pattern="${sd:type}", routes={Route(type=dynamic default), Route(type=static Reference=STDOUT key='Audit'), Route(type=static Reference=List key='Service')}) 2011-11-23 17:08:00,827 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.routing.RoutingAppender for element Routing with params(name="Routing", ignoreExceptions="null", Routes({Route(type=dynamic default),Route(type=static Reference=STDOUT key='Audit'),Route(type=static Reference=List key='Service')}), Configuration(RoutingTest), null, null) 2011-11-23 17:08:00,827 DEBUG Calling createAppenders on class org.apache.logging.log4j.core.config.AppendersPlugin for element appenders with params(appenders={STDOUT, List, Routing}) 2011-11-23 17:08:00,828 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element AppenderRef with params(ref="Routing") 2011-11-23 17:08:00,829 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig for element logger with params(additivity="false", level="info", name="EventLogger", AppenderRef={Routing}, null) 2011-11-23 17:08:00,830 DEBUG Calling createAppenderRef on class org.apache.logging.log4j.core.config.plugins.AppenderRefPlugin for element AppenderRef with params(ref="STDOUT") 2011-11-23 17:08:00,831 DEBUG Calling createLogger on class org.apache.logging.log4j.core.config.LoggerConfig$RootLogger for element root with params(additivity="null", level="error", AppenderRef={STDOUT}, null) 2011-11-23 17:08:00,833 DEBUG Calling createLoggers on class org.apache.logging.log4j.core.config.LoggersPlugin for element loggers with params(loggers={EventLogger, root}) 2011-11-23 17:08:00,834 DEBUG Reconfiguration completed 2011-11-23 17:08:00,846 DEBUG Calling createLayout on class org.apache.logging.log4j.core.layout.PatternLayout for element PatternLayout with params(pattern="%d %p %c{1.} [%t] %m%n", Configuration(RoutingTest), null, charset="null") 2011-11-23 17:08:00,849 DEBUG Calling createPolicy on class org.apache.logging.log4j.core.appender.rolling.SizeBasedTriggeringPolicy for element SizeBasedTriggeringPolicy with params(size="500") 2011-11-23 17:08:00,851 DEBUG Calling createAppender on class org.apache.logging.log4j.core.appender.RollingFileAppender for element RollingFile with params(fileName="target/rolling1/rollingtest-Unknown.log", filePattern="target/rolling1/test1-Unknown.%i.log.gz", append="null", name="Rolling-Unknown", bufferedIO="null", immediateFlush="null", SizeBasedTriggeringPolicy(SizeBasedTriggeringPolicy(size=500)), null, PatternLayout(%d %p %c{1.} [%t] %m%n), null, ignoreExceptions="null") 2011-11-23 17:08:00,858 DEBUG Generated plugins in 0.002014000 seconds 2011-11-23 17:08:00,889 DEBUG Reconfiguration started for context sun.misc.Launcher$AppClassLoader@37b90b39 2011-11-23 17:08:00,890 DEBUG Generated plugins in 0.001355000 seconds 2011-11-23 17:08:00,959 DEBUG Generated plugins in 0.001239000 seconds 2011-11-23 17:08:00,961 DEBUG Generated plugins in 0.001197000 seconds 2011-11-23 17:08:00,965 WARN No Loggers were configured, using default 2011-11-23 17:08:00,976 DEBUG Reconfiguration completed 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: <logger name="EventLogger" level="info" additivity="false"> <AppenderRef ref="Routng"/> </logger> the following error message will be produced. 2011-11-24 23:21:25,517 ERROR Unable to locate appender Routng for logger EventLogger 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: StatusConsoleListener listener = new StatusConsoleListener(Level.ERROR); StatusLogger.getLogger().registerListener(listener); Testing in MavenMaven can run unit and functional tests during the build cycle. By default, any files placed in src/test/resources are automatically copied to target/test-classes and are included in the classpath during execution of any tests. As such, placing a log4j2-test.xml into this directory will cause it to be used instead of a log4j2.xml or log4j2.json that might be present. Thus a different log configuration can be used during testing than what is used in production. 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. A third approach, also used extensively by Log4j 2, is to use the InitialLoggerContext JUnit test rule which provides additional convenience methods for testing. This requires adding the log4j-core test-jar dependency to your test scope dependencies. For example: public class AwesomeTest { @Rule public InitialLoggerContext init = new InitialLoggerContext("MyTestConfig.xml"); @Test public void testSomeAwesomeFeature() { final LoggerContext ctx = init.getContext(); final Logger logger = init.getLogger("org.apache.logging.log4j.my.awesome.test.logger"); final Configuration cfg = init.getConfiguration(); final ListAppender app = init.getListAppender("List"); logger.warn("Test message"); final List<LogEvent> events = app.getEvents(); // etc. } } System PropertiesBelow follows a number of system properties that can be used to control Log4j 2 behaviour. Any spaces present in the property name are for visual flow and should be removed.
|