| <?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 xmlns="http://maven.apache.org/XDOC/2.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| <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="../log4j-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> |
| <subsection name="ContextMapLookup"> |
| <a 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> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <File name="Application" fileName="application.log"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] $${ctx:loginId} %m%n</pattern> |
| </PatternLayout> |
| </File>]]></pre> |
| </subsection> |
| <subsection name="DateLookup"> |
| <a 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> |
| <pre class="prettyprint linenums"><![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>]]></pre> |
| </subsection> |
| <subsection name="EnvironmentLookup"> |
| <a 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> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <File name="Application" fileName="application.log"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] $${env:USER} %m%n</pattern> |
| </PatternLayout> |
| </File>]]></pre> |
| </subsection> |
| <subsection name="JndiLookup"> |
| <a name="JndiLookup"/> |
| <p> |
| The JndiLookup allows variables to be retrieved via JNDI. By default the key will be prefixed with |
| java:comp/env/, however if the key contains a ":" no prefix will be added. |
| </p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <File name="Application" fileName="application.log"> |
| <PatternLayout> |
| <pattern>%d %p %c{1.} [%t] $${jndi:logging/context-name} %m%n</pattern> |
| </PatternLayout> |
| </File>]]></pre> |
| </subsection> |
| <subsection name="MapLookup"> |
| <a name="MapLookup"/> |
| <p> |
| The MapLookup serves several purposes. |
| </p> |
| <ol> |
| <li>Provide the base for Properties declared in the configuration file.</li> |
| <li>Retrieve values from MapMessages in LogEvents.</li> |
| <li>Retrieve values set with <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/lookup/MapLookup.html#setMainArguments%28java.lang.String[]%29">MapLookup.setMainArguments(String[])</a></li> |
| </ol> |
| <p> |
| 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="../log4j-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> |
| <pre class="prettyprint linenums"><![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>]]></pre> |
| </subsection> |
| <subsection name="StructuredDataLookup"> |
| <a 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="../log4j-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> |
| <pre class="prettyprint linenums"><![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>]]></pre> |
| </subsection> |
| <subsection name="SystemPropertiesLookup"> |
| <a 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> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <Appenders> |
| <File name="ApplicationLog" fileName="${sys:logPath}/app.log"/> |
| </Appenders>]]></pre> |
| </subsection> |
| <subsection name="WebLookup"> |
| <a name="WebLookup"/> |
| <p> |
| The WebLookup allows applications to retrieve variables that are associated with the ServletContext. |
| In addition to being able to retrieve various fields in the ServletContext, WebLookup supports looking |
| up values stored as attributes or configured as initialization parameters. The following table lists |
| various keys that can be retrieved: |
| </p> |
| <table> |
| <tr> |
| <th>Key</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>attr.<i>name</i></td> |
| <td>Returns the ServletContext attribute with the specified name</td> |
| </tr> |
| <tr> |
| <td>contextPath</td> |
| <td>The context path of the web application</td> |
| </tr> |
| <tr> |
| <td>effectiveMajorVersion</td> |
| <td>Gets the major version of the Servlet specification that the application represented by this |
| ServletContext is based on.</td> |
| </tr> |
| <tr> |
| <td>effectiveMinorVersion</td> |
| <td>Gets the minor version of the Servlet specification that the application represented by this |
| ServletContext is based on.</td> |
| </tr> |
| <tr> |
| <td>initParam.<i>name</i></td> |
| <td>Returns the ServletContext initialization parameter with the specified name</td> |
| </tr> |
| <tr> |
| <td>majorVersion</td> |
| <td>Returns the major version of the Servlet API that this servlet container supports.</td> |
| </tr> |
| <tr> |
| <td>minorVersion</td> |
| <td>Returns the minor version of the Servlet API that this servlet container supports.</td> |
| </tr> |
| <tr> |
| <td>rootDir</td> |
| <td>Returns the result of calling getRealPath with a value of "/".</td> |
| </tr> |
| <tr> |
| <td>serverInfo</td> |
| <td>Returns the name and version of the servlet container on which the servlet is running.</td> |
| </tr> |
| <tr> |
| <td>servletContextName</td> |
| <td>Returns the name of the web application as defined in the display-name element of the |
| deployment descriptor</td> |
| </tr> |
| </table> |
| <p>Any other key names specified will first be checked to see if a ServletContext attribute exists with |
| that name and then will be checked to see if an initialization parameter of that name exists. If the |
| key is located then the corresponding value will be returned.</p> |
| <pre class="prettyprint linenums"><![CDATA[ |
| <Appenders> |
| <File name="ApplicationLog" fileName="${web:rootDir}/app.log"/> |
| </Appenders>]]></pre> |
| </subsection> |
| |
| </section> |
| </body> |
| </document> |
