| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from target/generated-sources/site/xdoc/manual/usage.xml 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="Ralph Goers" /> |
| <title>Log4j – Log4j 2 Usage</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 class="active"><a><span class="icon-chevron-down"></span>Usage</a> |
| <ul class="nav nav-list"> |
| <li><a href="../manual/usage.html#StaticVsNonStatic" title="Static vs non-Static Loggers"><span class="none"></span>Static vs non-Static Loggers</a></li> |
| <li><a href="../manual/usage.html#LoggerVsClass" title="Logger Name vs Class Name"><span class="none"></span>Logger Name vs Class Name</a></li> |
| <li><a href="../manual/cloud.html" title="Logging in the Cloud"><span class="none"></span>Logging in the Cloud</a></li> |
| </ul></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><a href="../manual/customloglevels.html" title="Custom Log Levels"><span class="icon-chevron-right"></span>Custom Log Levels</a></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" > |
| |
| |
| <section> |
| <h2><a name="Usage"></a>Usage</h2> |
| <a name="StaticVsNonStatic"></a> |
| <section> |
| <h3><a name="Static_vs_Non-Static_Loggers"></a>Static vs Non-Static Loggers</h3> |
| |
| <p>As with any variable in Java, Loggers may be declared as static variables or class member variables. However, |
| there are a few factors to consider when choosing to declare a logger as static vs non-static. Generally, it |
| is better to declare Loggers as static. |
| </p> |
| <ol style="list-style-type: decimal"> |
| |
| <li> |
| Instantiation of a new Logger is a fairly expensive operation when using the default ContextSelector, |
| <a href="../log4j-core/apidocs/org/apache/logging/log4j/core/selector/ClassLoaderContextSelector.html" class="javadoc">ClassLoaderContextSelector</a>. |
| When the Logger is created the <code>ClassLoaderContextSelector</code> will locate the ClassLoader for the Class the Logger |
| is associated with and add the Logger to the LoggerContext associated with that ClassLoader. |
| </li> |
| |
| <li> |
| Once a Logger is created it will not be deleted until the <code>LoggerContext</code> it is associated with |
| is deleted. Typically, this will only happen when the application is shut down or un-deployed. Each call |
| to getLogger with the same logger name will return the same Logger instance. Thus, there is very little |
| difference between a static or non-static Logger. |
| </li> |
| |
| <li> |
| There is no behavioral difference between a static and non-static Logger. Both will have the Logger name |
| assigned when they are created, which usually will be the name of the class they are associated with. See |
| the discussion below on logger names vs class names and the example for more information. |
| </li> |
| </ol> |
| |
| </section> |
| <a name="LoggerVsClass"></a> |
| <section> |
| <h3><a name="Logging_the_Logger_name_vs_the_Class_name"></a>Logging the Logger name vs the Class name</h3> |
| |
| <p> |
| The logger name of a Logger is specified when the Logger is created. When a log method is called the |
| class name value in the log event will reflect the name of the class the log method was called from, which is |
| not necessarily the same as the class that created the Logger. The following example illustrations this. |
| </p> |
| |
| |
| <p>The base class creates a static Logger and a logger variable that is initialized as that same Logger. |
| It has a method that performs logging, but provides access to two Loggers, one that is static and one |
| that can be overridden. |
| </p> |
| |
| |
| |
| <div> |
| <pre class="prettyprint"> |
| package org.apache.logging; |
| |
| import org.apache.logging.log4j.LogManager; |
| import org.apache.logging.log4j.Logger; |
| import org.apache.logging.log4j.Marker; |
| |
| /** |
| * |
| */ |
| public abstract class Parent { |
| |
| // The name of this Logger will be "org.apache.logging.Parent" |
| protected static final Logger parentLogger = LogManager.getLogger(); |
| |
| private Logger logger = parentLogger; |
| |
| protected Logger getLogger() { |
| return logger; |
| } |
| |
| protected void setLogger(Logger logger) { |
| this.logger = logger; |
| } |
| |
| |
| public void log(Marker marker) { |
| logger.debug(marker,"Parent log message"); |
| } |
| } |
| </pre></div> |
| |
| |
| <p> |
| This class extends the base class. It provides its own logger and has three methods, one that uses the |
| logger in this class,one that uses the static logger from the base class, and one that where the logger |
| may be set to either the parent or the child. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint"> |
| package org.apache.logging; |
| |
| import org.apache.logging.log4j.LogManager; |
| import org.apache.logging.log4j.Logger; |
| import org.apache.logging.log4j.Marker; |
| |
| /** |
| * |
| */ |
| public class Child extends Parent { |
| |
| // The name of this Logger will be "org.apache.logging.Child" |
| public Logger childLogger = LogManager.getLogger(); |
| |
| public void childLog(Marker marker) { |
| childLogger.debug(marker,"Child logger message"); |
| } |
| |
| public void logFromChild(Marker marker) { |
| getLogger().debug(marker,"Log message from Child"); |
| } |
| |
| public void parentLog(Marker marker) { |
| parentLogger.debug(marker,"Parent logger, message from Child"); |
| } |
| } |
| </pre></div> |
| |
| <p> |
| The application exercises all the logging methods four times. The first two times the Logger in the base |
| class is set to the static Logger. The second two times the Logger in the base class is set to use the |
| Logger in the subclass. In the first and third invocation of each method a null Marker is passed. In the |
| second and fourth a Marker named "CLASS" is passed. |
| </p> |
| |
| |
| <div> |
| <pre class="prettyprint"> |
| package org.apache.logging; |
| |
| import org.apache.logging.log4j.Marker; |
| import org.apache.logging.log4j.MarkerManager; |
| |
| public class App { |
| |
| public static void main( String[] args ) { |
| Marker marker = MarkerManager.getMarker("CLASS"); |
| Child child = new Child(); |
| |
| System.out.println("------- Parent Logger ----------"); |
| child.log(null); |
| child.log(marker); |
| child.logFromChild(null); |
| child.logFromChild(marker); |
| child.parentLog(null); |
| child.parentLog(marker); |
| |
| child.setLogger(child.childLogger); |
| |
| System.out.println("------- Parent Logger set to Child Logger ----------"); |
| child.log(null); |
| child.log(marker); |
| child.logFromChild(null); |
| child.logFromChild(marker); |
| } |
| }</pre></div> |
| |
| |
| <p> |
| The configuration takes advantage of Log4j's ability to select a pattern based upon attributes of the log event. |
| In this case %C, the class name pattern, is used when the CLASS Marker is present, and %c, the logger name |
| is used when the CLASS marker is not present. |
| </p> |
| |
| <div> |
| <pre class="prettyprint linenums"><?xml version="1.0" encoding="UTF-8"?> |
| <Configuration status="error"> |
| <Appenders> |
| <Console name="Console" target="SYSTEM_OUT"> |
| <PatternLayout> |
| <MarkerPatternSelector defaultPattern="%sn. %msg: Logger=%logger%n"> |
| <PatternMatch key="CLASS" pattern="%sn. %msg: Class=%class%n"/> |
| </MarkerPatternSelector> |
| </PatternLayout> |
| </Console> |
| </Appenders> |
| <Loggers> |
| <Root level="TRACE"> |
| <AppenderRef ref="Console" /> |
| </Root> |
| </Loggers> |
| </Configuration></pre></div> |
| |
| |
| <p> |
| The output below illustrates the difference between using the Logger name and the Class name in the pattern. All |
| the odd numbered items print the name of the logger (%c) while all the even numbered items print the |
| name of the class that called the logging method (%C). The numbers in the description of the outcomes in the |
| following list match the corresponding numbers shown in the output. |
| </p> |
| <ol style="list-style-type: decimal"> |
| |
| <li>Logging is performed in the parent class using the static logger with the Logger name pattern. The |
| logger name matches the name of the parent class.</li> |
| |
| <li>Logging is performed in the parent class using the static logger with the Class name pattern. Although |
| the method was called against the Child instance it is implemented in Parent so that is what |
| appears.</li> |
| |
| <li>Logging is performed in Child using the logger in the parent, so the name of the |
| parent is printed as the logger name.</li> |
| |
| <li>Logging is performed in Child using the logger in the parent. Since the method calling the logging |
| method is in Child that is the class name that appears.</li> |
| |
| <li>Logging is performed in Child using the static logger in the parent, so the name of the |
| parent is printed as the logger name.</li> |
| |
| <li>Logging is performed in Child using the static logger in the parent. Since the method calling the logging |
| method is in Child that is the class name that appears.</li> |
| |
| |
| <li>Logging is performed in the parent class using the logger of the Child. The |
| logger name matches the name of the child and so it is printed.</li> |
| |
| <li>Logging is performed in the parent class using the logger of the Child. Although |
| the method was called against the Child instance it is implemented in Parent so that is what |
| appears as the class name.</li> |
| |
| <li>Logging is performed in Child using the logger in the parent which is set to the child logger, |
| so the name of the child is printed as the logger name.</li> |
| |
| <li>Logging is performed in Child using the logger in the parent, which is set to the child logger. Since |
| the method calling the logging method is in Child that is the class name that appears.</li> |
| </ol> |
| |
| |
| <div> |
| <pre class="prettyprint"> |
| ------- Parent Logger ---------- |
| 1. Parent log message: Logger=org.apache.logging.Parent |
| 2. Parent log message: Class=org.apache.logging.Parent |
| 3. Log message from Child: Logger=org.apache.logging.Parent |
| 4. Log message from Child: Class=org.apache.logging.Child |
| 5. Parent logger, message from Child: Logger=org.apache.logging.Parent |
| 6. Parent logger, message from Child: Class=org.apache.logging.Child |
| ------- Parent Logger set to Child Logger ---------- |
| 7. Parent log message: Logger=org.apache.logging.Child |
| 8. Parent log message: Class=org.apache.logging.Parent |
| 9. Log message from Child: Logger=org.apache.logging.Child |
| 10. Log message from Child: Class=org.apache.logging.Child |
| </pre></div> |
| |
| |
| <p> |
| In the example above there are two Loggers declared. One is static and one is non-static. When looking at |
| the results it is clear that the outcomes would be exactly the same regardless of whether how the loggers |
| are declared. The name of the logger will always originate from the class in which it is created and the |
| Class name in each log event will always reflect the Class from which the logging method was called. |
| </p> |
| |
| <p> |
| It should be noted that there is a substantial performance penalty for printing the location information |
| (class name, method name, and line number). If the method name and line number are not important it is |
| usually better to make sure that each class has its own Logger so the logger name accurately reflects the |
| class performing the logging. |
| </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> |
