rgoers/src/site/xdoc/manual/lookups.xml - logging-log4j1 - Git at Google

 <?xml version="1.0"?>
 <!--
     Licensed to the Apache Software Foundation (ASF) under one or more
     contributor license agreements.  See the NOTICE file distributed with
     this work for additional information regarding copyright ownership.
     The ASF licenses this file to You under the Apache License, Version 2.0
     (the "License"); you may not use this file except in compliance with
     the License.  You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.
 -->

 <document>
     <properties>
         <title>Log4j 2 Lookups</title>
         <author email="rgoers@apache.org">Ralph Goers</author>
     </properties>

     <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="DateLookup"/>
         <subsection name="DateLookup">
           <p>
             The DateLookup is somewhat unusual from the other lookups as it doesn't use the key to locate an item.
             Instead, the key can be used to specify a date format string that is valid for
             <a href="http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a>.
             The current date, or the date associated with the current log event will be formatted as specified.
           </p>
           <source><![CDATA[    <RollingFile name="Rolling-${map:type}" fileName="${filename}"
                  filePattern="target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz">
       <PatternLayout>
         <pattern>%d %p %C{1.} [%t] %m%n</pattern>
       </PatternLayout>
       <SizeBasedTriggeringPolicy size="500" />
     </RollingFile>]]></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="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>
 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<document>
	<properties>
	<title>Log4j 2 Lookups</title>
	<author email="rgoers@apache.org">Ralph Goers</author>
	</properties>

	<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="DateLookup"/>
	<subsection name="DateLookup">
	<p>
	The DateLookup is somewhat unusual from the other lookups as it doesn't use the key to locate an item.
	Instead, the key can be used to specify a date format string that is valid for
	<a href="http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a>.
	The current date, or the date associated with the current log event will be formatted as specified.
	</p>
	<source><![CDATA[ <RollingFile name="Rolling-${map:type}" fileName="${filename}"
	filePattern="target/rolling1/test1-$${date:MM-dd-yyyy}.%i.log.gz">
	<PatternLayout>
	<pattern>%d %p %C{1.} [%t] %m%n</pattern>
	</PatternLayout>
	<SizeBasedTriggeringPolicy size="500" />
	</RollingFile>]]></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="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>
	</document>