<?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.
-->
#set($dollar = '$')

<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>Custom Log Levels</title>
        <author email="rpopma@apache.org">Remko Popma</author>
    </properties>

    <body>
      <a name="top" />
      <section name="Custom Log Levels">
        <a name="DefiningLevelsInCode" />
        <subsection name="Defining Custom Log Levels in Code">
        <p>
          Log4J 2 supports custom log levels. Custom log levels can be defined in code
          or in configuration. To define a custom log level in code, use the
          <tt>Level.forName()</tt> method. This method creates a new
          level for the specified name. After a log level is defined you can log
          messages at this level by calling the Logger.log() method and passing
          the custom log level:
        </p>
            <pre class="prettyprint">
// This creates the "VERBOSE" level if it does not exist yet.
final Level VERBOSE = Level.forName("VERBOSE", 550);

final Logger logger = LogManager.getLogger();
logger.log(VERBOSE, "a verbose message"); // use the custom VERBOSE level

// Create and use a new custom level "DIAG".
logger.log(Level.forName("DIAG", 350), "a diagnostic message");

// Use (don't create) the "DIAG" custom level.
// Only do this *after* the custom level is created!
logger.log(Level.getLevel("DIAG"), "another diagnostic message");

// Using an undefined level results in an error: Level.getLevel() returns null,
// and logger.log(null, "message") throws an exception.
logger.log(Level.getLevel("FORGOT_TO_DEFINE"), "some message"); // throws exception!</pre>
        <p>When defining a custom log level, the <tt>intLevel</tt> parameter (550 and 350 in the example above) determines
           where the custom level exists in relation to the standard levels built-in to Log4J 2.
           For reference, the table below shows the <tt>intLevel</tt> of the built-in log levels.
         </p>
         <table style="width: 30%">
          <caption align="top">Standard log levels built-in to Log4J</caption>
          <tr>
            <th>Standard Level</th>
            <th>intLevel</th>
          </tr>
          <tr>
            <td>OFF</td>
            <td align="right">0</td>
          </tr>
          <tr>
            <td>FATAL</td>
            <td align="right">100</td>
          </tr>
          <tr>
            <td>ERROR</td>
            <td align="right">200</td>
          </tr>
          <tr>
            <td>WARN</td>
            <td align="right">300</td>
          </tr>
          <tr>
            <td>INFO</td>
            <td align="right">400</td>
          </tr>
          <tr>
            <td>DEBUG</td>
            <td align="right">500</td>
          </tr>
          <tr>
            <td>TRACE</td>
            <td align="right">600</td>
          </tr>
          <tr>
            <td>ALL</td>
            <td align="right"><tt>Integer.MAX_VALUE</tt></td>
          </tr>
        </table>
        </subsection>
        <a name="DefiningLevelsInConfiguration" />
        <subsection name="Defining Custom Log Levels in Configuration">
          <p>
          Custom log levels can also be defined in configuration.
          This is convenient for using a custom level in a logger filter
          or an appender filter. Similar to defining log levels in code,
          a custom level must be defined first, before it can be used.
          If a logger or appender is configured with an undefined level,
          that logger or appender will be invalid and will not process any log events.
          </p>
          <p>
            The <b>CustomLevel</b> configuration element creates a custom level.
            Internally it calls the same <tt>Level.forName()</tt> method discussed above.
          </p>
          <table>
            <caption align="top">CustomLevel Parameters</caption>
            <tr>
              <th>Parameter Name</th>
              <th>Type</th>
              <th>Description</th>
            </tr>
            <tr>
              <td>name</td>
              <td>String</td>
              <td>The name of the custom level. Note that level names are case sensitive.
                The convention is to use all upper-case names.</td>
            </tr>
            <tr>
              <td>intLevel</td>
              <td>integer</td>
              <td>Determines where the custom level exists in relation to the
                standard levels built-in to Log4J 2 (see the table above).</td>
            </tr>
          </table>
          <p>
          The following example shows a configuration that defines some custom
          log levels and uses a custom log level to filter log events sent to the console.
          </p>
          <pre class="prettyprint linenums"><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
  <!-- Define custom levels before using them for filtering below. -->
  <CustomLevels>
    <CustomLevel name="DIAG" intLevel="350" />
    <CustomLevel name="NOTICE" intLevel="450" />
    <CustomLevel name="VERBOSE" intLevel="550" />
  </CustomLevels>

  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout pattern="%d %-7level %logger{36} - %msg%n"/>
    </Console>
    <File name="MyFile" fileName="logs/app.log">
      <PatternLayout pattern="%d %-7level %logger{36} - %msg%n"/>
    </File>
  </Appenders>
  <Loggers>
    <Root level="trace">
      <!-- Only events at DIAG level or more specific are sent to the console. -->
      <AppenderRef ref="Console" level="diag" />
      <AppenderRef ref="MyFile" level="trace" />
    </Root>
  </Loggers>
</Configuration>]]></pre>
        </subsection>
          <a name="StandardLoggerInterface" />
          <subsection name="Convenience Methods for the Built-in Log Levels">
            <p>
              The built-in log levels have a set of convenience methods on the Logger
              interface that makes them easier to use. For example, the Logger interface
              has fourteen <tt>debug()</tt> methods that support the DEBUG level:
            </p>
            <pre class="prettyprint">
// convenience methods for the built-in DEBUG level
debug(Marker, Message)
debug(Marker, Message, Throwable)
debug(Marker, Object)
debug(Marker, Object, Throwable)
debug(Marker, String)
debug(Marker, String, Object...)
debug(Marker, String, Throwable)
debug(Message)
debug(Message, Throwable)
debug(Object)
debug(Object, Throwable)
debug(String)
debug(String, Object...)
debug(String, Throwable)</pre>
            <p>
              Similar methods exist for the other built-in levels.
              Custom levels, in contrast, need to pass in the log level as an extra parameter.
            </p>
            <pre class="prettyprint">
// need to pass the custom level as a parameter
logger.log(VERBOSE, "a verbose message");
logger.log(Level.forName("DIAG", 350), "another message");</pre>
            <p>It would be nice to have the same ease of use with custom levels,
               so that after declaring the custom VERBOSE/DIAG levels, we could
               use code like this:
            </p>
            <pre class="prettyprint">
// nice to have: descriptive methods and no need to pass the level as a parameter
logger.verbose("a verbose message");
logger.diag("another message");</pre>
            <p>The standard Logger interface cannot provide convenience methods for
              custom levels, but the next few sections introduce a code generation tool
              to create loggers that aim to make custom levels as easy to use
              as built-in levels.</p>
          </subsection>
          <a name="AddingOrReplacingLevels" />
          <subsection name="Adding or Replacing Log Levels">
            <p>
              We assume that most users want to <em>add</em> custom level methods to the Logger interface,
               in addition to the existing trace(), debug(), info(), ... methods for the built-in log levels.
            </p>
            <p>There is another use case, Domain Specific Language loggers, where we want to <em>replace</em>
               the existing trace(), debug(), info(), ... methods with all-custom methods.
            </p>
            <p>
              For example, for medical devices we could have only <tt>critical()</tt>, <tt>warning()</tt>,
              and <tt>advisory()</tt> methods.
              Another example could be a game that has only <tt>defcon1()</tt>, <tt>defcon2()</tt>,
              and <tt>defcon3()</tt> levels.
            </p>
            <p>
              If it were possible to hide existing log levels, users could customize the
              Logger interface to match their requirements. Some people may not want to
              have a FATAL or a TRACE level, for example. They would like to be able to
              create a custom Logger that only has debug(), info(), warn() and error() methods.
            </p>
          </subsection>
          <a name="CustomLoggers" />
          <subsection name="Generating Source Code for a Custom Logger Wrapper">
            <p>
              Common Log4J usage is to get an instance of the <tt>Logger</tt> interface from the
              <tt>LogManager</tt> and call the methods on this interface.
              However, the custom log Levels are not known in advance, so Log4J cannot provide
              an interface with convenience methods for these custom log Levels.
            </p>
            <p>
              To solve this, Log4J ships with a tool that generates source code for a
              Logger wrapper. The generated wrapper class has convenience methods for each
              custom log level, making custom levels just as easy to use as the built-in levels.
            </p>
            <p>
              There are two flavors of wrappers: ones that <em><b>extend</b></em> the Logger
              API (adding methods to the built-in levels) and ones that <em><b>customize</b></em>
              the Logger API (replacing the built-in methods).
            </p>
            <p>When generating the source code for a wrapper class, you need to specify:</p>
            <ul>
              <li>the fully qualified name of the class to generate
              </li>
              <li>the list of custom levels to support and their <tt>intLevel</tt> relative strength
              </li>
              <li>whether to extend <tt>Logger</tt> (and keep the existing built-in methods)
                or have only methods for the custom log levels
              </li>
            </ul>
            <p>You would then include the generated source code in the project
              where you want to use custom log levels.</p>
          </subsection>
          <a name="ExampleUsage" />
          <subsection name="Example Usage of a Generated Logger Wrapper">
            <p>
              Here is an example of how one would use a generated logger wrapper with
              custom levels DIAG, NOTICE and VERBOSE:
            </p>
            <pre class="prettyprint linenums">
// ExtLogger is a generated logger wrapper
import com.mycompany.myproject.ExtLogger;

public class MyService {
    // instead of Logger logger = LogManager.getLogger(MyService.class):
    private static final ExtLogger logger = ExtLogger.create(MyService.class);

    public void someMethod() {
        // ...
        logger.trace("the built-in TRACE level");
        logger.verbose("a custom level: a VERBOSE message");
        logger.debug("the built-in DEBUG level");
        logger.notice("a custom level: a NOTICE message");
        logger.info("the built-in INFO level");
        logger.diag("a custom level: a DIAG message");
        logger.warn("the built-in WARN level");
        logger.error("the built-in ERROR level");
        logger.fatal("the built-in FATAL level");
        // ...
    }
    ...
}</pre>
          </subsection>
          <a name="CodeGen" />
          <subsection name="Generating Extended Loggers">
            <p>
              Use the following command to generate a logger wrapper that adds methods to the built-in ones:
            </p>
            <pre class="prettyprint">
java -cp log4j-core-${Log4jReleaseVersion}.jar org.apache.logging.log4j.core.tools.Generate${dollar}ExtendedLogger} \
        com.mycomp.ExtLogger DIAG=350 NOTICE=450 VERBOSE=550 > com/mycomp/ExtLogger.java</pre>
            <p>
              This will generate source code for a logger wrapper that has the convenience methods
              for the built-in levels <em>as well as</em> the specified custom levels. The tool prints the
              generated source code to the console.
              By appending " &gt; <em>filename</em>" the output can be redirected to a file.
            </p>
          </subsection>
          <subsection name="Generating Custom Loggers">
            <p>
              Use the following command to generate a logger wrapper that hides the built-in levels and has only custom levels:
            </p>
            <pre class="prettyprint">
java -cp log4j-core-${Log4jReleaseVersion}.jar org.apache.logging.log4j.core.tools.Generate${dollar}CustomLogger \
        com.mycomp.MyLogger DEFCON1=350 DEFCON2=450 DEFCON3=550 > com/mycomp/MyLogger.java</pre>
            <p>
              This will generate source code for a logger wrapper that <em>only</em> has convenience
              methods for the specified custom levels, <em>not</em> for the built-in levels.
              The tool prints the generated source code to the console.
              By appending " &gt; <em>filename</em>" the output can be redirected to a file.
            </p>
          </subsection>
      </section>

    </body>
</document>
