| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/customloglevels.xml.vm at 2024-03-06 |
| | Rendered using Apache Maven Fluido Skin 1.11.2 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> |
| <meta name="author" content="Remko Popma" /> |
| <title>Log4j – Custom Log Levels</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.11.2.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.11.2.min.js"></script> |
| </head> |
| <body class="topBarDisabled"> |
| <div class="container-fluid"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../../.." id="bannerLeft"><img src="../images/ls-logo.jpg" alt="" style="" /></a></div> |
| <div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/logo.png" alt="" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2024-03-06<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 2.23.1</li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://github.com/apache/logging-log4j2" class="externalLink" title="GitHub">GitHub</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="../../../" title="Logging Services">Logging Services</a></li> |
| <li class="pull-right"><span class="divider">|</span> |
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a></li> |
| <li class="pull-right"><a href="https://cwiki.apache.org/confluence/display/LOGGING/Log4j" class="externalLink" title="Logging Wiki">Logging Wiki</a></li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/home.png" alt="Apache Log4j™ 2" style="border: 0;" /> Apache Log4j™ 2</li> |
| <li><a href="../index.html" title="About"><span class="none"></span>About</a></li> |
| <li><a href="../download.html" title="Download"><span class="none"></span>Download</a></li> |
| <li><a href="../support.html" title="Support"><span class="none"></span>Support</a></li> |
| <li><a href="../maven-artifacts.html" title="Maven, Ivy, Gradle Artifacts"><span class="icon-chevron-right"></span>Maven, Ivy, Gradle Artifacts</a></li> |
| <li><a href="../release-notes.html" title="Release Notes"><span class="none"></span>Release Notes</a></li> |
| <li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a></li> |
| <li><a href="../performance.html" title="Performance"><span class="icon-chevron-right"></span>Performance</a></li> |
| <li><a href="../articles.html" title="Articles and Tutorials"><span class="none"></span>Articles and Tutorials</a></li> |
| <li><a href="../security.html" title="Security"><span class="icon-chevron-right"></span>Security</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/book.png" alt="Manual" style="border: 0;" /> Manual</li> |
| <li><a href="../manual/index.html" title="Introduction"><span class="none"></span>Introduction</a></li> |
| <li><a href="../manual/architecture.html" title="Architecture"><span class="none"></span>Architecture</a></li> |
| <li><a href="../manual/api-separation.html" title="API Separation"><span class="none"></span>API Separation</a></li> |
| <li><a href="../manual/migration.html" title="Log4j 1.x Migration"><span class="icon-chevron-right"></span>Log4j 1.x Migration</a></li> |
| <li><a href="../manual/api.html" title="Java API"><span class="icon-chevron-right"></span>Java API</a></li> |
| <li><a href="../../kotlin" title="Kotlin API"><span class="none"></span>Kotlin API</a></li> |
| <li><a href="../../scala" title="Scala API"><span class="none"></span>Scala API</a></li> |
| <li><a href="../manual/configuration.html" title="Configuration"><span class="icon-chevron-right"></span>Configuration</a></li> |
| <li><a href="../manual/usage.html" title="Usage"><span class="icon-chevron-right"></span>Usage</a></li> |
| <li><a href="../manual/webapp.html" title="Web Applications and JSPs"><span class="icon-chevron-right"></span>Web Applications and JSPs</a></li> |
| <li><a href="../manual/lookups.html" title="Lookups"><span class="icon-chevron-right"></span>Lookups</a></li> |
| <li><a href="../manual/appenders.html" title="Appenders"><span class="icon-chevron-right"></span>Appenders</a></li> |
| <li><a href="../manual/layouts.html" title="Layouts"><span class="icon-chevron-right"></span>Layouts</a></li> |
| <li><a href="../manual/filters.html" title="Filters"><span class="icon-chevron-right"></span>Filters</a></li> |
| <li><a href="../manual/async.html" title="Async Loggers"><span class="icon-chevron-right"></span>Async Loggers</a></li> |
| <li><a href="../manual/garbagefree.html" title="Garbage-free Logging"><span class="icon-chevron-right"></span>Garbage-free Logging</a></li> |
| <li><a href="../manual/jmx.html" title="JMX"><span class="none"></span>JMX</a></li> |
| <li><a href="../manual/logsep.html" title="Logging Separation"><span class="none"></span>Logging Separation</a></li> |
| <li><a href="../manual/extending.html" title="Extending Log4j"><span class="icon-chevron-right"></span>Extending Log4j</a></li> |
| <li><a href="../manual/plugins.html" title="Plugins"><span class="icon-chevron-right"></span>Plugins</a></li> |
| <li><a href="../manual/customconfig.html" title="Programmatic Log4j Configuration"><span class="icon-chevron-right"></span>Programmatic Log4j Configuration</a></li> |
| <li class="active"><a><span class="icon-chevron-down"></span>Custom Log Levels</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/customloglevels.html#DefiningLevelsInCode" title="In Code"><span class="none"></span>In Code</a></li> |
| <li><a href="../manual/customloglevels.html#DefiningLevelsInConfiguration" title="In Configuration"><span class="none"></span>In Configuration</a></li> |
| <li><a href="../manual/customloglevels.html#AddingOrReplacingLevels" title="Adding or Replacing Levels"><span class="none"></span>Adding or Replacing Levels</a></li> |
| <li><a href="../manual/customloglevels.html#CustomLoggers" title="Custom Loggers"><span class="none"></span>Custom Loggers</a></li> |
| <li><a href="../manual/customloglevels.html#ExampleUsage" title="Custom Logger Example"><span class="none"></span>Custom Logger Example</a></li> |
| <li><a href="../manual/customloglevels.html#CodeGen" title="Code Generation Tool"><span class="none"></span>Code Generation Tool</a></li> |
| </ul></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/pencil.png" alt="For Contributors" style="border: 0;" /> For Contributors</li> |
| <li><a href="../guidelines.html" title="Guidelines"><span class="none"></span>Guidelines</a></li> |
| <li><a href="../javastyle.html" title="Style Guide"><span class="none"></span>Style Guide</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/cog.png" alt="Components" style="border: 0;" /> Components</li> |
| <li><a href="../log4j-api.html" title="API"><span class="none"></span>API</a></li> |
| <li><a href="../log4j-jcl.html" title="Commons Logging Bridge"><span class="none"></span>Commons Logging Bridge</a></li> |
| <li><a href="../log4j-1.2-api.html" title="Log4j 1.2 API"><span class="none"></span>Log4j 1.2 API</a></li> |
| <li><a href="../log4j-slf4j-impl.html" title="SLF4J Binding"><span class="none"></span>SLF4J Binding</a></li> |
| <li><a href="../log4j-jul.html" title="JUL Adapter"><span class="none"></span>JUL Adapter</a></li> |
| <li><a href="../log4j-jpl.html" title="JDK Platform Logger"><span class="none"></span>JDK Platform Logger</a></li> |
| <li><a href="../log4j-to-slf4j.html" title="Log4j 2 to SLF4J Adapter"><span class="none"></span>Log4j 2 to SLF4J Adapter</a></li> |
| <li><a href="../log4j-flume-ng.html" title="Apache Flume Appender"><span class="none"></span>Apache Flume Appender</a></li> |
| <li><a href="../log4j-taglib.html" title="Log4j Tag Library"><span class="none"></span>Log4j Tag Library</a></li> |
| <li><a href="../log4j-jmx-gui.html" title="Log4j JMX GUI"><span class="none"></span>Log4j JMX GUI</a></li> |
| <li><a href="../log4j-web.html" title="Log4j Web Application Support"><span class="none"></span>Log4j Web Application Support</a></li> |
| <li><a href="../log4j-jakarta-web.html" title="Log4j Jakarta Web Application Support"><span class="none"></span>Log4j Jakarta Web Application Support</a></li> |
| <li><a href="../log4j-appserver.html" title="Log4j Application Server Integration"><span class="none"></span>Log4j Application Server Integration</a></li> |
| <li><a href="../log4j-couchdb.html" title="Log4j CouchDB appender"><span class="none"></span>Log4j CouchDB appender</a></li> |
| <li><a href="../log4j-mongodb3.html" title="Log4j MongoDB3 appender"><span class="none"></span>Log4j MongoDB3 appender</a></li> |
| <li><a href="../log4j-mongodb4.html" title="Log4j MongoDB4 appender"><span class="none"></span>Log4j MongoDB4 appender</a></li> |
| <li><a href="../log4j-cassandra.html" title="Log4j Cassandra appender"><span class="none"></span>Log4j Cassandra appender</a></li> |
| <li><a href="../log4j-iostreams.html" title="Log4j IO Streams"><span class="none"></span>Log4j IO Streams</a></li> |
| <li><a href="../log4j-docker.html" title="Log4j Docker Support"><span class="none"></span>Log4j Docker Support</a></li> |
| <li><a href="../log4j-kubernetes.html" title="Log4j Kubernetes Support"><span class="none"></span>Log4j Kubernetes Support</a></li> |
| <li><a href="../log4j-spring-boot.html" title="Log4j Spring Boot"><span class="none"></span>Log4j Spring Boot</a></li> |
| <li><a href="../log4j-spring-cloud-config-client.html" title="Log4j Spring Cloud Config Client"><span class="none"></span>Log4j Spring Cloud Config Client</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/tag.png" alt="Related Projects" style="border: 0;" /> Related Projects</li> |
| <li><a href="../../../chainsaw/2.x/index.html" title="Chainsaw"><span class="none"></span>Chainsaw</a></li> |
| <li><a href="../../../log4cxx/latest_stable/index.html" title="Log4Cxx"><span class="none"></span>Log4Cxx</a></li> |
| <li><a href="../../../log4j-audit/latest/index.html" title="Log4j Audit"><span class="none"></span>Log4j Audit</a></li> |
| <li><a href="../../kotlin" title="Log4j Kotlin"><span class="none"></span>Log4j Kotlin</a></li> |
| <li><a href="../../scala" title="Log4j Scala"><span class="none"></span>Log4j Scala</a></li> |
| <li><a href="../../transform" title="Log4j Transform"><span class="none"></span>Log4j Transform</a></li> |
| <li><a href="../../../log4net/index.html" title="Log4Net"><span class="none"></span>Log4Net</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/link.png" alt="Legacy Sites" style="border: 0;" /> Legacy Sites</li> |
| <li><a href="../../log4j-2.12.4/" title="Log4j 2.12.4 - Java 7"><span class="none"></span>Log4j 2.12.4 - Java 7</a></li> |
| <li><a href="../../log4j-2.3.2/" title="Log4j 2.3.2 - Java 6"><span class="none"></span>Log4j 2.3.2 - Java 6</a></li> |
| <li><a href="../../1.2/" title="Log4j 1.2 - End of Life"><span class="none"></span>Log4j 1.2 - End of Life</a></li> |
| <li class="nav-header"><img class="imageLink" src="../img/glyphicons/info.png" alt="Project Information" style="border: 0;" /> Project Information</li> |
| <li><a href="../team.html" title="Project Team"><span class="none"></span>Project Team</a></li> |
| <li><a href="https://www.apache.org/licenses/LICENSE-2.0" class="externalLink" title="Project License"><span class="none"></span>Project License</a></li> |
| <li><a href="https://github.com/apache/logging-log4j2" class="externalLink" title="Source Repository"><span class="none"></span>Source Repository</a></li> |
| <li><a href="../runtime-dependencies.html" title="Runtime Dependencies"><span class="none"></span>Runtime Dependencies</a></li> |
| <li><a href="../javadoc.html" title="Javadoc"><span class="none"></span>Javadoc</a></li> |
| <li><a href="../thanks.html" title="Thanks"><span class="none"></span>Thanks</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10" > |
| |
| |
| <a name="top"></a> |
| <section> |
| <h2><a name="Custom_Log_Levels"></a>Custom Log Levels</h2> |
| <a name="DefiningLevelsInCode"></a> |
| <section> |
| <h3><a name="Defining_Custom_Log_Levels_in_Code"></a>Defining Custom Log Levels in Code</h3> |
| |
| <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 |
| <code>Level.forName()</code> 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> |
| |
| <div> |
| <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></div> |
| |
| <p>When defining a custom log level, the <code>intLevel</code> 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 <code>intLevel</code> of the built-in log levels. |
| </p> |
| |
| <table border="0" class="table table-striped" style="width: 30%"><caption align="top">Standard log levels built-in to Log4J</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Standard Level</th> |
| |
| <th>intLevel</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">OFF</td> |
| |
| <td align="right">0</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">FATAL</td> |
| |
| <td align="right">100</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">ERROR</td> |
| |
| <td align="right">200</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">WARN</td> |
| |
| <td align="right">300</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">INFO</td> |
| |
| <td align="right">400</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">DEBUG</td> |
| |
| <td align="right">500</td> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">TRACE</td> |
| |
| <td align="right">600</td> |
| </tr> |
| |
| <tr class="a"> |
| |
| <td align="left">ALL</td> |
| |
| <td align="right"><code>Integer.MAX_VALUE</code></td> |
| </tr> |
| </table> |
| </section> |
| <a name="DefiningLevelsInConfiguration"></a> |
| <section> |
| <h3><a name="Defining_Custom_Log_Levels_in_Configuration"></a>Defining Custom Log Levels in Configuration</h3> |
| |
| <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 <code>Level.forName()</code> method discussed above. |
| </p> |
| |
| <table border="0" class="table table-striped"><caption align="top">CustomLevel Parameters</caption> |
| |
| |
| <tr class="a"> |
| |
| <th>Parameter Name</th> |
| |
| <th>Type</th> |
| |
| <th>Description</th> |
| </tr> |
| |
| <tr class="b"> |
| |
| <td align="left">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 class="a"> |
| |
| <td align="left">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> |
| |
| <div> |
| <pre class="prettyprint linenums"> |
| <?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></div> |
| </section> |
| <a name="StandardLoggerInterface"></a> |
| <section> |
| <h3><a name="Convenience_Methods_for_the_Built-in_Log_Levels"></a>Convenience Methods for the Built-in Log Levels</h3> |
| |
| <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 24 <code>debug()</code> methods that support the DEBUG level: |
| </p> |
| |
| <div> |
| <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) |
| // lambda support methods added in 2.4 |
| debug(Marker, MessageSupplier) |
| debug(Marker, MessageSupplier, Throwable) |
| debug(Marker, String, Supplier<?>...) |
| debug(Marker, Supplier<?>) |
| debug(Marker, Supplier<?>, Throwable) |
| debug(MessageSupplier) |
| debug(MessageSupplier, Throwable) |
| debug(String, Supplier<?>...) |
| debug(Supplier<?>) |
| debug(Supplier<?>, Throwable)</pre></div> |
| |
| <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> |
| |
| <div> |
| <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></div> |
| |
| <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> |
| |
| <div> |
| <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"); |
| logger.diag("java 8 lambda expression: {}", () -> someMethod());</pre></div> |
| |
| <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> |
| </section> |
| <a name="AddingOrReplacingLevels"></a> |
| <section> |
| <h3><a name="Adding_or_Replacing_Log_Levels"></a>Adding or Replacing Log Levels</h3> |
| |
| <p> |
| We assume that most users want to <i>add</i> 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 <i>replace</i> |
| the existing trace(), debug(), info(), ... methods with all-custom methods. |
| </p> |
| |
| <p> |
| For example, for medical devices we could have only <code>critical()</code>, <code>warning()</code>, |
| and <code>advisory()</code> methods. |
| Another example could be a game that has only <code>defcon1()</code>, <code>defcon2()</code>, |
| and <code>defcon3()</code> 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> |
| </section> |
| <a name="CustomLoggers"></a> |
| <section> |
| <h3><a name="Generating_Source_Code_for_a_Custom_Logger_Wrapper"></a>Generating Source Code for a Custom Logger Wrapper</h3> |
| |
| <p> |
| Common Log4J usage is to get an instance of the <code>Logger</code> interface from the |
| <code>LogManager</code> 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 <i><b>extend</b></i> the Logger |
| API (adding methods to the built-in levels) and ones that <i><b>customize</b></i> |
| 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 <code>intLevel</code> relative strength |
| </li> |
| |
| <li>whether to extend <code>Logger</code> (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> |
| </section> |
| <a name="ExampleUsage"></a> |
| <section> |
| <h3><a name="Example_Usage_of_a_Generated_Logger_Wrapper"></a>Example Usage of a Generated Logger Wrapper</h3> |
| |
| <p> |
| Here is an example of how one would use a generated logger wrapper with |
| custom levels DIAG, NOTICE and VERBOSE: |
| </p> |
| |
| <div> |
| <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 demoExtendedLogger() { |
| // ... |
| 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"); |
| logger.notice("java 8 lambda expression only executed if NOTICE is enabled: {}", () -> someMethod()); |
| // ... |
| } |
| ... |
| }</pre></div> |
| </section> |
| <a name="CodeGen"></a> |
| <section> |
| <h3><a name="Generating_Extended_Loggers"></a>Generating Extended Loggers</h3> |
| |
| <p> |
| Use the following command to generate a logger wrapper that adds methods to the built-in ones: |
| </p> |
| |
| <div> |
| <pre class="prettyprint"> |
| java -cp log4j-core-2.23.1.jar org.apache.logging.log4j.core.tools.ExtendedLoggerGenerator \ |
| com.mycomp.ExtLogger DIAG=350 NOTICE=450 VERBOSE=550 > com/mycomp/ExtLogger.java</pre></div> |
| |
| <p> |
| This will generate source code for a logger wrapper that has the convenience methods |
| for the built-in levels <i>as well as</i> the specified custom levels. The tool prints the |
| generated source code to the console. |
| By appending " > <i>filename</i>" the output can be redirected to a file. |
| </p> |
| <p> |
| NOTE: Prior to log4j-2.9, this tool was an inner class <code>Generate$ExtendedLogger</code>.<br /> |
| Under the bash shell on Unix/Mac/Linux the dollar character $ needs to be escaped, so the class name should |
| be between single quotes 'org.apache.logging.log4j.core.tools.Generate$ExtendedLogger’. |
| </p> |
| </section> |
| <section> |
| <h3><a name="Generating_Custom_Loggers"></a>Generating Custom Loggers</h3> |
| |
| <p> |
| Use the following command to generate a logger wrapper that hides the built-in levels and has only custom levels: |
| </p> |
| |
| <div> |
| <pre class="prettyprint"> |
| java -cp log4j-core-2.23.1.jar org.apache.logging.log4j.core.tools.CustomLoggerGenerator \ |
| com.mycomp.MyLogger DEFCON1=350 DEFCON2=450 DEFCON3=550 > com/mycomp/MyLogger.java</pre></div> |
| |
| <p> |
| This will generate source code for a logger wrapper that <i>only</i> has convenience |
| methods for the specified custom levels, <i>not</i> for the built-in levels. |
| The tool prints the generated source code to the console. |
| By appending " > <i>filename</i>" the output can be redirected to a file. |
| </p> |
| <p> |
| NOTE: Prior to log4j-2.9, this tool was an inner class <code>Generate$ExtendedLogger</code>.<br /> |
| Under the bash shell on Unix/Mac/Linux the dollar character $ needs to be escaped, so the class name should |
| be between single quotes 'org.apache.logging.log4j.core.tools.Generate$CustomLogger’. |
| </p> |
| </section> |
| </section> |
| |
| |
| |
| </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| <p align="center">Copyright © 1999-2024 <a class="external" href="https://www.apache.org">The Apache Software Foundation</a>. All Rights Reserved.<br> |
| Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </div> |
| </footer> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |
