logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
Subject svn commit: r1206675 - in /logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers: log4j2-core/src/main/java/org/apache/logging/log4j/core/config/ log4j2-core/src/main/java/org/apache/logging/log4j/core/lookup/ log4j2-core/src/test/java/org/apache/loggi...
Date Sun, 27 Nov 2011 07:22:47 GMT
Author: rgoers
Date: Sun Nov 27 07:22:46 2011
New Revision: 1206675

URL: http://svn.apache.org/viewvc?rev=1206675&view=rev
Log:
Finish first draft of configuration documentation.

Added:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppender2Test.java
      - copied, changed from r1204693, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppenderTest.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing2.json
      - copied, changed from r1204693, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing.json
Modified:
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/JSONConfiguration.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/XMLConfiguration.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/lookup/MapLookup.java
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/JSONConfiguration.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/JSONConfiguration.java?rev=1206675&r1=1206674&r2=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/JSONConfiguration.java
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/JSONConfiguration.java
Sun Nov 27 07:22:46 2011
@@ -148,10 +148,15 @@ public class JSONConfiguration extends B
                 if (n.isArray()) {
                     logger.debug("Processing node for array " + entry.getKey());
                     for (int i=0; i < n.size(); ++i) {
-                        PluginType entryType = getPluginManager().getPluginType(entry.getKey());
+                        String pluginType = getType(n.get(i), entry.getKey());
+                        PluginType entryType = getPluginManager().getPluginType(pluginType);
                         Node item = new Node(node, entry.getKey(), entryType);
                         processAttributes(item, n.get(i));
-                        logger.debug("Processing " + entry.getKey() + "[" + i + "]");
+                        if (pluginType.equals(entry.getKey())) {
+                            logger.debug("Processing " + entry.getKey() + "[" + i + "]");
+                        } else {
+                            logger.debug("Processing " + pluginType + " " + entry.getKey()
+ "[" + i + "]");
+                        }
                         Iterator<Map.Entry<String, JsonNode>> itemIter = n.get(i).getFields();
                         List<Node> itemChildren = item.getChildren();
                         while (itemIter.hasNext()) {
@@ -167,8 +172,6 @@ public class JSONConfiguration extends B
                     logger.debug("Processing node for object " + entry.getKey());
                     children.add(constructNode(entry.getKey(), node, n));
                 }
-
-
             }
         }
 
@@ -184,14 +187,30 @@ public class JSONConfiguration extends B
         return node;
     }
 
+    private String getType(JsonNode node, String name) {
+        Iterator<Map.Entry<String, JsonNode>> iter = node.getFields();
+        while (iter.hasNext()) {
+            Map.Entry<String, JsonNode> entry = iter.next();
+            if (entry.getKey().equalsIgnoreCase("type")) {
+                JsonNode n = entry.getValue();
+                if (n.isValueNode()) {
+                    return n.asText();
+                }
+            }
+        }
+        return name;
+    }
+
     private void processAttributes(Node parent, JsonNode node) {
         Map<String, String> attrs = parent.getAttributes();
         Iterator<Map.Entry<String, JsonNode>> iter = node.getFields();
         while (iter.hasNext()) {
             Map.Entry<String, JsonNode> entry = iter.next();
-            JsonNode n = entry.getValue();
-            if (n.isValueNode()) {
-                attrs.put(entry.getKey(), n.asText());
+            if (!entry.getKey().equalsIgnoreCase("type")) {
+                JsonNode n = entry.getValue();
+                if (n.isValueNode()) {
+                    attrs.put(entry.getKey(), n.asText());
+                }
             }
         }
     }

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/XMLConfiguration.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/XMLConfiguration.java?rev=1206675&r1=1206674&r2=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/XMLConfiguration.java
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/config/XMLConfiguration.java
Sun Nov 27 07:22:46 2011
@@ -62,6 +62,8 @@ public class XMLConfiguration extends Ba
 
     private boolean strict = false;
 
+    private String schema = null;
+
     private static final String[] verboseClasses = new String[] { ResolverUtil.class.getName()
};
 
     private Validator validator;
@@ -95,6 +97,8 @@ public class XMLConfiguration extends Ba
                     setName(entry.getValue());
                 } else if ("strict".equalsIgnoreCase(entry.getKey())) {
                     strict = Boolean.parseBoolean(entry.getValue());
+                } else if ("schema".equalsIgnoreCase(entry.getKey())) {
+                    schema = entry.getValue();
                 } else if ("monitorInterval".equalsIgnoreCase(entry.getKey())) {
                     int interval = Integer.parseInt(entry.getValue());
                     if (interval > 0 && configFile != null) {
@@ -129,24 +133,31 @@ public class XMLConfiguration extends Ba
         } catch (ParserConfigurationException pex) {
             logger.error("Error parsing " + source.getSystemId(), pex);
         }
-        if (strict && buffer != null) {
-            InputStream is = getClass().getClassLoader().getResourceAsStream(LOG4J_XSD);
-            Source src = new StreamSource(is, LOG4J_XSD);
-            SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
-            Schema schema = null;
+        if (strict && schema != null && buffer != null) {
+            InputStream is = null;
             try {
-                schema = factory.newSchema(src);
-            } catch (SAXException ex) {
-                logger.error("Error parsing Log4j schema", ex);
-            }
-            if (schema != null) {
-                validator = schema.newValidator();
+                is = getClass().getClassLoader().getResourceAsStream(schema);
+            } catch (Exception ex) {
+                logger.error("Unable to access schema " + schema);
+            }
+            if (is != null) {
+                Source src = new StreamSource(is, LOG4J_XSD);
+                SchemaFactory factory = SchemaFactory.newInstance(XMLConstants.W3C_XML_SCHEMA_NS_URI);
+                Schema schema = null;
                 try {
-                    validator.validate(new StreamSource(new ByteArrayInputStream(buffer)));
-                } catch (IOException ioe) {
-                    logger.error("Error reading configuration for validation", ioe);
+                    schema = factory.newSchema(src);
                 } catch (SAXException ex) {
-                    logger.error("Error validating configuration", ex);
+                    logger.error("Error parsing Log4j schema", ex);
+                }
+                if (schema != null) {
+                    validator = schema.newValidator();
+                    try {
+                        validator.validate(new StreamSource(new ByteArrayInputStream(buffer)));
+                    } catch (IOException ioe) {
+                        logger.error("Error reading configuration for validation", ioe);
+                    } catch (SAXException ex) {
+                        logger.error("Error validating configuration", ex);
+                    }
                 }
             }
         }

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/lookup/MapLookup.java
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/lookup/MapLookup.java?rev=1206675&r1=1206674&r2=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/lookup/MapLookup.java
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/main/java/org/apache/logging/log4j/core/lookup/MapLookup.java
Sun Nov 27 07:22:46 2011
@@ -17,12 +17,15 @@
 package org.apache.logging.log4j.core.lookup;
 
 import org.apache.logging.log4j.core.LogEvent;
+import org.apache.logging.log4j.core.config.plugins.Plugin;
+import org.apache.logging.log4j.message.MapMessage;
 
 import java.util.Map;
 
 /**
  * The basis for a lookup based on a Map.
  */
+@Plugin(name="map",type="Lookup")
 public class MapLookup<V> implements StrLookup<V> {
     /**
      * Map keys are variable names and value.
@@ -30,7 +33,7 @@ public class MapLookup<V> implements Str
     private final Map<String, V> map;
 
     /**
-     * Creates a new instance backed by a Map.
+     * Creates a new instance backed by a Map. Used by the default lookup.
      *
      * @param map the map of keys to values, may be null
      */
@@ -39,6 +42,13 @@ public class MapLookup<V> implements Str
     }
 
     /**
+     * Constructor when used directly as a plugin.
+     */
+    public MapLookup() {
+        this.map = null;
+    }
+
+    /**
      * Looks up a String key to a String value using the map.
      * <p/>
      * If the map is null, then null is returned.
@@ -59,6 +69,18 @@ public class MapLookup<V> implements Str
     }
 
     public String lookup(LogEvent event, String key) {
-        return lookup(key);
+        if (map == null && !(event.getMessage() instanceof MapMessage)) {
+            return null;
+        }
+        if (map != null && map.containsKey(key)) {
+            Object obj = map.get(key);
+            if (obj != null) {
+                return obj.toString();
+            }
+        }
+        if (event.getMessage() instanceof MapMessage) {
+            return ((MapMessage) event.getMessage()).get(key);
+        }
+        return null;
     }
 }

Copied: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppender2Test.java
(from r1204693, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppenderTest.java)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppender2Test.java?p2=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppender2Test.java&p1=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppenderTest.java&r1=1204693&r2=1206675&rev=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppenderTest.java
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/java/org/apache/logging/log4j/core/appender/routing/JSONRoutingAppender2Test.java
Sun Nov 27 07:22:46 2011
@@ -40,8 +40,8 @@ import static org.junit.Assert.assertTru
 /**
  *
  */
-public class JSONRoutingAppenderTest {
-    private static final String CONFIG = "log4j-routing.json";
+public class JSONRoutingAppender2Test {
+    private static final String CONFIG = "log4j-routing2.json";
     private static Configuration config;
     private static ListAppender app;
     private static LoggerContext ctx;

Copied: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing2.json
(from r1204693, logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing.json)
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing2.json?p2=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing2.json&p1=logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing.json&r1=1204693&r2=1206675&rev=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing.json
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/log4j2-core/src/test/resources/log4j-routing2.json
Sun Nov 27 07:22:46 2011
@@ -4,31 +4,32 @@
       },
     "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" }
-              }
-            },
-            { "appender-ref": "STDOUT", "key": "Audit"},
-            { "appender-ref": "List", "key": "Service"}
-          ]
+      "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" }
+                }
+              },
+              { "appender-ref": "STDOUT", "key": "Audit"},
+              { "appender-ref": "List", "key": "Service"}
+            ]
+          }
         }
-      }
+      ]
     },
     "loggers": {
-      "logger": { "name": "EventLogger", "level": "info", "additivity": "false", "appender-ref":
{ "ref": "Routing" }},
+      "logger": [
+        { "name": "EventLogger", "level": "info", "additivity": "false", "appender-ref":
{ "ref": "Routing" }},
+        { "name": "com.foo.bar", "level": "error", "additivity": "false", "appender-ref":
{ "ref": "Console" }}
+      ],
       "root": { "level": "error", "appender-ref": { "ref": "STDOUT" }}
     }
   }

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml?rev=1206675&r1=1206674&r2=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml (original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/site.xml Sun Nov 27 07:22:46
2011
@@ -45,7 +45,7 @@
       <item name="Architecture" href="/manual/architecture.html"/>
       <item name="Configuration" href="/manual/configuration.html" collapse="true">
         <item name="Automatic Configuration" href="/manual/configuration.html#AutomaticConfiguration"/>
-        <item name="Additivity" href="/manual/configuration.html#Additvity"/>
+        <item name="Additivity" href="/manual/configuration.html#Additivity"/>
         <item name="Automatic Reconfiguration" href="/manual/configuration.html#AutomaticReconfiguration"/>
         <item name="Configuration Syntax" href="/manual/configuration.html#ConfigurationSyntax"/>
         <item name="Property Substitution" href="/manual/configuration.html#PropertySubstitution"/>

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml?rev=1206675&r1=1206674&r2=1206675&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/configuration.xml
Sun Nov 27 07:22:46 2011
@@ -40,6 +40,8 @@
               components to the default configuration.</li>
             <li>Programmatically, by calling methods on the internal Logger class.</li>
           </ol>
+        </p>
+        <p>
           This page focuses primarily on configuring Log4j through a configuration file.
Information on
           programmatically configuring Log4j can be found at <a href="../extending.html">Extending
Log4j 2</a>.
         </p>
@@ -246,16 +248,498 @@
             When configured from a File, Log4j has the ability to automatically detect changes
to the configuration
             file and reconfigure itself. If the monitorInterval attribute is specified on
the configuration element
             and is set to a non-zero value then the file will be checked the next time a
log event is evaluated
-            and/or logged and the monitorInterval has elapsed since the last check.
+            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, and default, interval is 30 seconds.
           </p>
+          <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration monitorInterval="30">
+...
+</configuration>]]></source>
         </subsection>
         <a name="ConfigurationSyntax"/>
         <subsection name="Configuration Syntax">
+          <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>
+          <h4>Configuration with XML</h4>
+          <p>
+            The configuration element in the XML file accetps several attributes:
+            <table>
+              <tr>
+                <th>Attribute Name</th>
+                <th>Description</th>
+              </tr>
+              <tr>
+                <td>monitorInterval</td>
+                <td>The minimum amount of time, in seconds, that must elapse before
the file configuration
+                  is checked for changes.</td>
+              </tr>
+              <tr>
+                <td>name</td>
+                <td>The name of the configuration.</td>
+              </tr>
+              <tr>
+                <td>packages</td>
+                <td>A comma separated list of package names to search for plugins.
Plugins are only loaded
+                  once per classloader so changing this value may not have any effect upon
reconfiguration.</td>
+              </tr>
+              <tr>
+                <td>schema</td>
+                <td>Identifies the location for the classloader to located the XML
Schema to use to validate
+                  the configuration. Only valid when strict is set to true. If not set no
schema validation
+                  will take place.</td>
+              </tr>
+              <tr>
+                <td>status</td>
+                <td>The level of internal Log4j events that should be logged to the
console.</td>
+              </tr>
+              <tr>
+                <td>strict</td>
+                <td>Enables the use of the strict XML format. Not supported in JSON
configurations.</td>
+              </tr>
+              <tr>
+                <td>verbose</td>
+                <td>Enables diagnostic information while loading plugins.</td>
+              </tr>
+            </table>
+          </p>
+          <p>
+            Log4j can be configured using two XML flavors; concise and strict. The concise
format makes
+            configuration very easy as the element names match the components they represent
however it
+            cannot be validated with an XML schema. For example, the ConsoleAppender is configured
by
+            declaring an XML element named Console under its parent appenders element. However,
element
+            and attribute names are are not case sensitive. In addition, attributes can either
be specified
+            as an XML attribute or as an XML element that has no attributes and has a text
value. So
+          </p>
+          <source><![CDATA[<patternLayout pattern="%m%n"/>]]></source>
+          <p>and</p>
+          <source><![CDATA[<PatternLayout>
+  <pattern>%m%n</pattern>
+</PatternLayout>]]></source>
+          <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>
+
+          <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>;
+<configuration>
+  <properties>
+    <property name="name1">value</property>
+    <property name="name2" value="value2"/>
+  </properties>
+  <]]><i>filter</i>  ... <![CDATA[/>
+  <appenders>
+    <]]><i>appender</i> ... <![CDATA[>
+      <]]><i>filter</i>  ... <![CDATA[/>
+    </]]><i>appender</i><![CDATA[>
+    ...
+  </appenders>
+  <loggers>
+    <logger name="name1">
+      <]]><i>filter</i>  ... <![CDATA[/>
+    </logger>
+    ...
+    <root level="level">
+      <appender-ref ref="name"/>
+    </root>
+  </loggers>
+</configuration>]]></source>
+          <p>
+            See the many examples on this page for sample appender, filter and logger declarations.
+          </p>
+            <h5>Strict XML</h5>
+          <p>
+            In addition to the concise XML format above, Log4j allows configurations to be
specified in a
+            more "normal" XML manner that can be validated using an XML Schema. This is accomplished
by
+            replacing the friendly element names above with their object type as shown below.
For example,
+            instead of the ConsoleAppender being configuerd using an element named Console
it is instead
+            configured as an appender element with a type attribute containing "Console".
+          </p>
+          <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>;
+<configuration>
+  <properties>
+    <property name="name1">value</property>
+    <property name="name2" value="value2"/>
+  </properties>
+  <filter type="type" ... />
+  <appenders>
+    <appender type="type" name="name">
+      <filter type="type" ... />
+    </appender>
+    ...
+  </appenders>
+  <loggers>
+    <logger name="name1">
+      <filter type="type" ... />
+    </logger>
+    ...
+    <root level="level">
+      <appender-ref ref="name"/>
+    </root>
+  </loggers>
+</configuration>]]></source>
+          <p>
+            Below is a sample configuration using the strict format.
+          </p>
+          <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="debug" strict="true" name="XMLConfigTest" packages="org.apache.logging.log4j.test">
+  <properties>
+    <property name="filename">target/test.log</property>
+  </properties>
+  <filter type="ThresholdFilter" level="trace"/>
+
+  <appenders>
+    <appender type="Console" name="STDOUT">
+      <layout type="PatternLayout" pattern="%m MDC%X%n"/>
+      <filters>
+        <filter type="MarkerFilter" marker="FLOW" onMatch="DENY" onMismatch="NEUTRAL"/>
+        <filter type="MarkerFilter" marker="EXCEPTION" onMatch="DENY" onMismatch="ACCEPT"/>
+      </filters>
+    </appender>
+    <appender type="Console" name="FLOW">
+      <layout type="PatternLayout" pattern="%C{1}.%M %m %ex%n"/>
+      <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>
+      <appender-ref ref="STDOUT"/>
+    </logger>>
+
+    <logger name="org.apache.logging.log4j.test2" level="debug" additivity="false">
+      <appender-ref ref="File"/>
+    </logger>>
+
+    <root level="trace">
+      <appender-ref ref="List"/>
+    </root>
+  </loggers>
+
+</configuration>]]></source>
+          <h4>Configuration with JSON</h4>
+          <p>
+            In addition to XML, Log4j can be configured using JSON. The JSON format is very
similar to the
+            concise XML format. Each key represents the name of a plugin and the key/value
pairs associated
+            with it are its attributes. Where a key contains more than a simple value it
itself will be a
+            subordinate plugin. In the example below, ThresholdFilter, Console, and PatternLayout
are all
+            plugins while the Console plugin will be assigned a value of STDOUT for its name
attribute and the
+            ThresholdFilter will be assigned a level of debug.
+          </p>
+          <source>{ "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" }
+              }
+            },
+            { "appender-ref": "STDOUT", "key": "Audit"},
+            { "appender-ref": "List", "key": "Service"}
+          ]
+        }
+      }
+    },
+    "loggers": {
+      "logger": { "name": "EventLogger", "level": "info", "additivity": "false", "appender-ref":
{ "ref": "Routing" }},
+      "root": { "level": "error", "appender-ref": { "ref": "STDOUT" }}
+    }
+  }
+}</source>
+           <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>
+           <source>{ "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" }
+                }
+              },
+              { "appender-ref": "STDOUT", "key": "Audit"},
+              { "appender-ref": "List", "key": "Service"}
+            ]
+          }
+        }
+      ]
+    },
+    "loggers": {
+      "logger": [
+        { "name": "EventLogger", "level": "info", "additivity": "false", "appender-ref":
{ "ref": "Routing" }},
+        { "name": "com.foo.bar", "level": "error", "additivity": "false", "appender-ref":
{ "ref": "Console" }}
+      ],
+      "root": { "level": "error", "appender-ref": { "ref": "STDOUT" }}
+    }
+  }
+}</source>
+          <h4>Configuring loggers</h4>
+          <p>
+            An understanding of how loggers work in Log4j is critical before trying to configure
them.
+            Please reference the Log4j <a href="../architecture.html">architecture</a>
if more information is
+            required. Trying to configure Log4j without understanding those concepts will
lead to frustration.
+          </p>
+          <p>
+            A LoggerConfig is configured using the <code>logger</code> element.
The <code>logger</code> eleemnt
+            must have a name attribute specified, will usually have a level attribute specified
and may
+            also have an additivity attribute specified.  The level may be configured with
one of TRACE,
+            DEBUG, INFO, WARN, ERROR, ALL or OFF. If no level is specified it will default
to ERROR. The
+            additivity attribute may be assigned a value of true or false. If the attribute
is omitted
+            the default value of false will be used.
+          </p>
+          <p>
+            The LoggerConfig may also be configured with one or more appender-ref 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>
+            Every configuration must have a root logger. If one is not configured the default
root LoggerConfig,
+            which has a level of ERROR but with no appenders attached, will be used. The
main differences
+            between the root logger and other loggers are
+            <ol>
+              <li>The root logger does not have a name attribute.</li>
+              <li>The root logger does not support the additivity attribute since it
has no parent.</li>
+            </ol>
+          </p>
+          <h4>Configuring Appenders</h4>
+          <p>
+            An appender is configured either using the specific appender plugin's name or
with an appender
+            element and the type attibute containing the appender plugin's name. In addition
each appender
+            must have a name attribute specified with a value that is unique within the set
of appenders.
+            The name will be used by loggers to reference the appender as described in the
previous section.
+          </p>
+          <p>
+            Most appenders also support a layout to be configured (which again may be specified
either
+            using the specific Layout plugin's name as the eleemnt 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>
+          <h4>Configuring Filters</h4>
+          <p>
+            Log4j allows a filter to be specified in any of 3 places:
+            <ol>
+              <li>At the same level as the appenders, loggers and properties elements.
These filters can accept
+              or reject events before they have been passed to a LoggerConfig.</li>
+              <li>In a logger element. These filters can accept or reject events for
specific loggers.</li>
+              <li>In an appender element. These filters can prevent or cause events
to be processed by
+                the appender.</li>
+            </ol>
+          </p>
+          <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>
+          <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="debug" name="XMLConfigTest" packages="org.apache.logging.log4j.test">
+  <properties>
+    <property name="filename">target/test.log</property>
+  </properties>
+  <ThresholdFilter level="trace"/>
+
+  <appenders>
+    <Console name="STDOUT">
+      <PatternLayout pattern="%m MDC%X%n"/>
+      <filters>
+        <MarkerFilter marker="FLOW" onMatch="DENY" onMismatch="NEUTRAL"/>
+        <MarkerFilter marker="EXCEPTION" onMatch="DENY" onMismatch="ACCEPT"/>
+      </filters>
+    </Console>
+    <Console name="FLOW">
+      <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>
+      <appender-ref ref="STDOUT"/>
+    </logger>>
+
+    <logger name="org.apache.logging.log4j.test2" level="debug" additivity="false">
+      <appender-ref ref="File"/>
+    </logger>>
+
+    <root level="trace">
+      <appender-ref ref="List"/>
+    </root>
+  </loggers>
+
+</configuration>]]></source>
         </subsection>
         <a name="PropertySubstitution"/>
         <subsection name="Property Substitution">
+          <p>
+            Log4j 2 supports the ability to specify tokens in the configuration as references
to properties defined
+            elsewhere. Some of these properties will be resolved when the configuration file
is interpreted while
+            others may be passed to components where they will be evaluated at runtime. To
accomplish this, Log4j
+            uses variations Apache Commons Lang's
+            <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/lookup/StrSubstitutor">StrSubstitutor</a>
+            and <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup">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>
+<source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<configuration status="debug" name="RoutingTest" packages="org.apache.logging.log4j.test">
+  <properties>
+    <property name="filename">target/rolling1/rollingtest-$${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 appender-ref="STDOUT" key="Audit"/>
+        <Route appender-ref="List" key="Service"/>
+      </Routes>
+    </Routing>
+  </appenders>
 
+  <loggers>
+    <logger name="EventLogger" level="info" additivity="false">
+      <appender-ref ref="Routing"/>
+    </logger>
+
+    <root level="error">
+      <appender-ref ref="STDOUT"/>
+    </root>
+  </loggers>
+
+</configuration>]]></source>
+          <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. The contexts that
are built in to Logj4
+            are:
+            <table>
+              <tr>
+                <th>Prefix</th>
+                <th>Context</th>
+              </tr>
+              <tr>
+                <td>ctx</td>
+                <td>Thread Context Map (MDC)</td>
+              </tr>
+              <tr>
+                <td>env</td>
+                <td>System environment variables</td>
+              </tr>
+              <tr>
+                <td>map</td>
+                <td>A value from a MapMessage</td>
+              </tr>
+              <tr>
+                <td>sd</td>
+                <td>A value from a StructuredDataMessage. The key "id" will return
the name of the StructuredDataId
+                  without the enterprise number. The key "type" will return the message type.
Other keys will
+                  retrieve individual elements from the Map.</td>
+              </tr>
+              <tr>
+                <td>sys</td>
+                <td>System properties</td>
+              </tr>
+            </table>
+          </p>
+          <p>
+            An interesting feature of StrLookup processing is that when a variable reference
is declared with
+            multiple leading '$' characters each time the variable is resolved the leading
'$' is simply removed.
+            In the previous example the "Routes" element is capable of resolving the variable
at runtime. To allow
+            this the prefix value is specified as a variable with two leading '$' characters.
When the configuration
+            file is first processed the first variable is simply removed. Thus, when the
Routes element is evaluated
+            at runtime it is the variable declaration "${sd:type}" which causes the event
to be inspected for a
+            StructuredDataMessage and if one is present the value of its type attribute to
be used as the routing key.
+            Not all elements support resolving variables at runtime. Components that do will
specifically call that
+            out in their documentation.
+          </p>
+          <p>
+            <i>As a footnote, it is worth pointing out that the variables in the RollingFile
appender declaration
+            will also not be evaluated when the configuration is processed. This is simply
because the resolution
+            of the whole RollingFile element is deferred until a match occurs.
+            See <a href="../appenders.html#RoutingAppender">RoutingAppender</a>
for more information.</i>
+          </p>
         </subsection>
         <a name="StatusMessages"/>
         <subsection name="Status Messages">
@@ -378,9 +862,19 @@
           </p>
         </subsection>
         <a name="UnitTestingInMaven"/>
-        <subsection name="Unit Testing in Maven">
-
-
+        <subsection name="Testing in Maven">
+        <p>
+          Maven can run unit and functional tests during the build cycle. By default, any
files placed in
+          <code>src/test/resources</code> are automatically copied to target/test-classes
and are included
+          in the classpath during execution of any tests. As such, placing a log4j-test.xml
into this directory
+          will cause it to be used instead of a log4j.xml or log4j.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>
         </subsection>
       </section>
     </body>



Mime
View raw message