logging-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgo...@apache.org
Subject svn commit: r1206960 - in /logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site: site.xml xdoc/manual/configuration.xml xdoc/manual/lookups.xml
Date Mon, 28 Nov 2011 01:43:08 GMT
Author: rgoers
Date: Mon Nov 28 01:43:07 2011
New Revision: 1206960

URL: http://svn.apache.org/viewvc?rev=1206960&view=rev
Log:
Add documentation for lookups

Modified:
    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
    logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml

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=1206960&r1=1206959&r2=1206960&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 Mon Nov 28 01:43:07
2011
@@ -59,6 +59,8 @@
       </item>
       <item name="Lookups" href="/manual/lookups.html" collapse="true">
         <item name="ContextMap" href="/manual/lookups.html#ContextMapLookup"/>
+        <item name="Environment" href="/manual/lookups.html#EnvironmentLookup"/>
+        <item name="Map" href="/manual/lookups.html#MapLookup"/>
         <item name="StructuredData" href="/manual/lookups.html#StructuredDataLookup"/>
         <item name="SystemProperties" href="/manual/lookups.html#SystemPropertiesLookup"/>
       </item>

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=1206960&r1=1206959&r2=1206960&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
Mon Nov 28 01:43:07 2011
@@ -735,6 +735,19 @@
             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>
+ <source><![CDATA[<?xml version="1.0" encoding="UTF-8"?>;
+<configuration>
+  <properties>
+    <property name="type">Audit</property>
+  </properties>
+  ...
+</configuration>]]></source>
+          <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.

Modified: logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml
URL: http://svn.apache.org/viewvc/logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml?rev=1206960&r1=1206959&r2=1206960&view=diff
==============================================================================
--- logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml
(original)
+++ logging/log4j/branches/BRANCH_2_0_EXPERIMENTAL/rgoers/src/site/xdoc/manual/lookups.xml
Mon Nov 28 01:43:07 2011
@@ -25,27 +25,112 @@
     <body>
       <section name="Lookups">
         <p>
-
+          Lookups provide a way to add values to the Log4j configuration at arbitrary places.
They are
+          a particular type of Plugin that implements the
+          <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/lookup/StrLookup.html">StrLookup</a>
interface.
+          Information on how to use Lookups in configuration files can be found in the
+          <a href="./configuration.html#PropertySubstitution">Property Substitution</a>
section of the
+          <a href="./configuration.html">Configuration</a> page.
         </p>
         <a name="ContextMapLookup"/>
         <subsection name="ContextMapLookup">
-
+          <p>
+            The ContextMapLookup allows applications to store data in the Log4j ThreadContext
Map and
+            then retrieve the values in the Log4j configuration. In the example below, the
application
+            would store the current user's login id in the ThreadContext Map with the key
"loginId". During
+            initial configuration processing the first '$' will be removed. The PatternLayout
supports
+            interpolation with Lookups and will then resolve the variable for each event.
 Note that
+            the pattern "%X{loginId}" would achieve the same result.
+          </p>
+          <source><![CDATA[    <File name="Application" fileName="application.log">
+      <PatternLayout>
+        <pattern>%d %p %C{1.} [%t] $${ctx:loginId} %m%n</pattern>
+      </PatternLayout>
+    </File>]]></source>
         </subsection>
         <a name="EnvironmentLookup"/>
         <subsection name="EnvironmentLookup">
-
+          <p>
+            The EnvironmentLookup allows systems to configure environment variables, either
in global files
+            such as /etc/profile or in the startup scripts for applications, and then retrieve
those variables
+            from within the logging configuration. The example below includes the name of
the currently logged
+            in user in the application log.
+          </p>
+          <source><![CDATA[    <File name="Application" fileName="application.log">
+      <PatternLayout>
+        <pattern>%d %p %C{1.} [%t] $${env:USER} %m%n</pattern>
+      </PatternLayout>
+    </File>]]></source>
         </subsection>
         <a name="MapLookup"/>
         <subsection name="MapLookup">
-
+          <p>
+            The MapLookup serves two purposes.
+            <ol>
+              <li>Provide the base for Properties declared in the configuration file.</li>
+              <li>Retrieve values from MapMessages in LogEvents.</li>
+            </ol>
+            The first item simply means that the MapLookup is used to substitute properties
that are defined
+            in the configuration file. These variables are specified without a prefix - e.g.
<code>${name}</code>.
+            The second usage allows a value from the current
+            <a href="../log4j2-api/apidocs/org/apache/logging/log4j/message/MapMessage.html">MapMessage</a>,
+            if one is part of the current log event, to be substituted. In the example below
the RoutingAppender will
+            use a different RollingFileAppender for each unique value of the key named "type"
in the MapMessage. Note
+            that when used this way a  value for "type" should be declared in the properties
declaration to provide
+            a default value in case the message is not a MapMessage or the MapMessage does
not contain the key. See the
+            <a href="./configuration.html#PropertySubstitution">Property Substitution</a>
section of the
+            <a href="./configuration.html">Configuration</a> page for information
on how to set the default values.
+          </p>
+          <source><![CDATA[    <Routing name="Routing">
+      <Routes pattern="$${map:type}">
+        <Route>
+          <RollingFile name="Rolling-${map:type}" fileName="${filename}"
+                       filePattern="target/rolling1/test1-${map:type}.%i.log.gz">
+            <PatternLayout>
+              <pattern>%d %p %C{1.} [%t] %m%n</pattern>
+            </PatternLayout>
+            <SizeBasedTriggeringPolicy size="500" />
+          </RollingFile>
+        </Route>
+      </Routes>
+    </Routing>
+          ]]></source>
         </subsection>
-        <a name="StructuredDtaLookup"/>
+        <a name="StructuredDataLookup"/>
         <subsection name="StructuredDataLookup">
-
+          <p>
+            The StructuredDataLookup is very similar to the MapLookup in that it will retrieve
values from
+            StructuredDataMessages. In addition to the Map values it will also return the
name portion of the
+            id (not including the enterprise number) and the type field. The main difference
between the
+            example below and the example for MapMessage is that the "type" is an attribute
of the
+            <a href="../log4j2-api/apidocs/org/apache/logging/log4j/message/StructuredDataMessage.html">StructuredDataMessage</a>
+            while "type" would have to be an item in the Map in a MapMessage.
+          </p>
+          <source><![CDATA[    <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>
+      </Routes>
+    </Routing>
+          ]]></source>
         </subsection>
         <a name="SystemPropertiesLookup"/>
         <subsection name="SystemPropertiesLookup">
-
+          <p>
+            As it is quite common to define values inside and outside the application by
using System Properties,
+            it is only natural that they should be accessible via a Lookup. As system properties
are often
+            defined outside the application it would be quite common to see something like:
+          </p>
+          <source><![CDATA[  <appenders>
+    <File name="ApplicationLog" fileName="${sys:logPath}/app.log"/>
+  </appenders>]]></source>
         </subsection>
       </section>
     </body>



Mime
View raw message