<commit_before><?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="<EMAIL>"><NAME></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>
        <a name="AppMainArgsLookup"/>
        <subsection name="Application main arguments lookup">
          <p>
             You can access the main arguments of an application if they have been set with:
          </p>
<pre class="prettyprint linenums"><![CDATA[
import org.apache.logging.log4j.core.lookup.MapLookup;

public static void main(String args[]) {
  //...
  MapLookup.setMainArguments(args);
  //...
}]]></pre>
        <p>        
          Then, if your static void main String[] arguments are:
        </p>
        <pre>--file foo.txt --verbose -x bar</pre>
        <p>
          I can use the following substitutions with the <code>main</code> prefix with a 0-based index or a string:
        </p>
        <table>
          <tr>
            <th>Expression</th>
            <th>Result</th>
          </tr>
          <tr>
            <td>${main:0}</td>
            <td>
              <p><code>--file</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:1}</td>
            <td>
              <p><code>foo.txt</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:2}</td>
            <td>
              <p><code>--verbose</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:3}</td>
            <td>
              <p><code>-x</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:4}</td>
            <td>
              <p><code>bar</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:--file}</td>
            <td>
              <p><code>foo.txt</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:-x}</td>
            <td>
              <p><code>bar</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:bar}</td>
            <td>
              <p><code>null</code></p>
            </td>
          </tr>
        </table>        
        <p>
          Using <code>${main:string}</code> gives you the next value in the argument list after the given string.
        </p>
        </subsection>  
        <a name="ContextMapLookup"/>
        <subsection name="Context Map Lookup">
          <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>
        <a name="DateLookup"/>
        <subsection name="Date Lookup">
          <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><commit_msg>LOG4J2-771 (Main Args Lookup) minor text fixes and clarifications; added usage example<commit_after><?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="<EMAIL>"><NAME></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>
        <a name="AppMainArgsLookup"/>
        <subsection name="Application main arguments lookup">
          <p>
             This lookup requires a manual step.
             You can access the main arguments of an application if they have been set with:
          </p>
<pre class="prettyprint linenums"><![CDATA[
import org.apache.logging.log4j.core.lookup.MapLookup;

public static void main(String args[]) {
  //...
  MapLookup.setMainArguments(args);
  //...
}]]></pre>
        <p>        
          Then, if your static void main String[] arguments are:
        </p>
        <pre>--file foo.txt --verbose -x bar</pre>
        <p>
          You can use the following substitutions with the <code>main</code> prefix with a 0-based index or a string.
          Using <code>${main:string}</code> gives you the next value in the argument list after the given <code>string</code>.
        </p>
        <table style="width: 40%">
          <tr>
            <th>Expression</th>
            <th>Result</th>
          </tr>
          <tr>
            <td>${main:0}</td>
            <td>
              <p><code>--file</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:1}</td>
            <td>
              <p><code>foo.txt</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:2}</td>
            <td>
              <p><code>--verbose</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:3}</td>
            <td>
              <p><code>-x</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:4}</td>
            <td>
              <p><code>bar</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:--file}</td>
            <td>
              <p><code>foo.txt</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:-x}</td>
            <td>
              <p><code>bar</code></p>
            </td>
          </tr>
          <tr>
            <td>${main:bar}</td>
            <td>
              <p><code>null</code></p>
            </td>
          </tr>
        </table>
          <p>
            Example usage:
          </p>
          <pre class="prettyprint linenums"><![CDATA[
<File name="Application" fileName="application.log">
  <PatternLayout header="File: ${main:--file}">
    <Pattern>%d %m%n</Pattern>
  </PatternLayout>
</File>]]></pre>
        </subsection>  
        <a name="ContextMapLookup"/>
        <subsection name="Context Map Lookup">
          <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>
        <a name="DateLookup"/>
        <subsection name="Date Lookup">
          <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>
{'fraction_non_alphanumeric': 0.12987684092670743, 'fraction_numerical': 0.006631642408061321, 'mean_word_length': 1.9675440838231535, 'pattern_counts': {'":': 0, '<': 320, '<?xml version=': 2, '>': 318, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 6}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3809121', 'n_tokens_mistral': 3299, 'n_tokens_neox': 3238, 'n_words': 1019}