| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| | (Unfortunately) copied from the Fluido skin to allow the footer to be centered. |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <title> |
| Log4j 2 API</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| |
| |
| <script type="text/javascript" src="../js/apache-maven-fluido.min.js"></script> |
| |
| |
| <meta name="author" content="Ralph Goers" /> |
| <meta name="Date-Revision-yyyymmdd" content="20120729" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| </head> |
| <body class="topBarDisabled"> |
| |
| |
| |
| |
| <div class="container-fluid"> |
| <div id="banner"> |
| <div class="pull-left"> |
| <a href="../../../" id="bannerLeft"> |
| <img src="../images/ls-logo.jpg" alt="Apache Logging Services™"/> |
| </a> |
| </div> |
| <div class="pull-right"> <div id="bannerRight"> |
| <img src="../images/logo.jpg" /> |
| </div> |
| </div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| |
| |
| <li id="publishDate">Last Published: 2012-07-29</li> |
| <li class="divider">|</li> <li id="projectVersion">Version: 2.0-alpha1</li> |
| |
| |
| |
| |
| |
| <li class="pull-right"> <a href="../../../" title="Logging Services">Logging Services</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="http://www.apache.org/" class="externalLink" title="Apache">Apache</a> |
| </li> |
| |
| <li class="divider pull-right">|</li> |
| |
| <li class="pull-right"> <a href="http://wiki.apache.org/logging" class="externalLink" title="Logging Wiki">Logging Wiki</a> |
| </li> |
| |
| </ul> |
| </div> |
| |
| <div class="row-fluid"> |
| <div id="leftColumn" class="span2"> |
| <div class="well sidebar-nav"> |
| |
| |
| <h3>Apache Log4j™ 2</h3> |
| <ul> |
| <li class="none"> |
| <a href="../index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="../download.html" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="../build.html" title="Build and Install">Build and Install</a> |
| </li> |
| <li class="none"> |
| <a href="../changelog.html" title="Changelog">Changelog</a> |
| </li> |
| </ul> |
| <h3>Manual</h3> |
| <ul> |
| <li class="none"> |
| <a href="../manual/index.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/architecture.html" title="Architecture">Architecture</a> |
| </li> |
| <li class="expanded"> |
| <a href="../manual/api.html" title="API">API</a> |
| <ul> |
| <li class="none"> |
| <a href="../manual/api.html#Overview" title="Overview">Overview</a> |
| </li> |
| <li class="none"> |
| <strong>Flow Tracing</strong> |
| </li> |
| <li class="none"> |
| <a href="../manual/markers.html" title="Markers">Markers</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/eventlogging.html" title="Event Logging">Event Logging</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/messages.html" title="Messages">Messages</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/thread-context.html" title="ThreadContext">ThreadContext</a> |
| </li> |
| </ul> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/configuration.html" title="Configuration">Configuration</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/plugins.html" title="Plugins">Plugins</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/lookups.html" title="Lookups">Lookups</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/appenders.html" title="Appenders">Appenders</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/layouts.html" title="Layouts">Layouts</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/filters.html" title="Filters">Filters</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/jmx.html" title="JMX">JMX</a> |
| </li> |
| <li class="none"> |
| <a href="../manual/logsep.html" title="Logging Separation">Logging Separation</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../manual/extending.html" title="Extending Log4j">Extending Log4j</a> |
| </li> |
| </ul> |
| <h3>Logging Adapters</h3> |
| <ul> |
| <li class="none"> |
| <a href="../log4j12-api/api.html" title="Log4j 1.x API">Log4j 1.x API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j2-jcl/api.html" title="Commons Logging">Commons Logging</a> |
| </li> |
| <li class="none"> |
| <a href="../slf4j-impl/api.html" title="SLF4J">SLF4J</a> |
| </li> |
| </ul> |
| <h3>Components</h3> |
| <ul> |
| <li class="none"> |
| <a href="../log4j-api/index.html" title="API">API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-core/index.html" title="Impl">Impl</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j12-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-jcl/index.html" title="Commons Logging Bridge">Commons Logging Bridge</a> |
| </li> |
| <li class="none"> |
| <a href="../slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a> |
| </li> |
| <li class="none"> |
| <a href="../log4j-flume-ng/index.html" title="Apache Flume">Apache Flume</a> |
| </li> |
| </ul> |
| <h3>Site Documentation</h3> |
| <ul> |
| <li class="collapsed"> |
| <a href="../project-info.html" title="Project Information">Project Information</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../project-reports.html" title="Project Reports">Project Reports</a> |
| </li> |
| </ul> |
| |
| |
| |
| <hr class="divider" /> |
| |
| <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="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| </div> |
| </div> |
| </div> |
| |
| <div id="bodyColumn" class="span10" > |
| |
| <!-- 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. --> |
| |
| <div class="section"><h2>Log4j 2 API<a name="Log4j_2_API"></a></h2> |
| <a name="FlowTracing"></a> |
| <div class="section"><h3>Flow Tracing<a name="Flow_Tracing"></a></h3> |
| <p> |
| The Logger class provides logging methods that are quite useful for following the |
| execution path of applications. These methods generate logging events that can be filtered |
| separately from other debug logging. Liberal use of these methods is encouraged as the output has |
| been found to |
| </p><ul> |
| <li>aid in problem diagnosis in development without requiring a debug session</li> |
| <li>aid in problem diagnosis in production where no debugging is possible</li> |
| <li>help educate new deveopers in learning the application.</li> |
| </ul> |
| |
| <p> |
| The two most used methods are the entry() and exit() methods. entry() should be placed at the |
| beginning of methods, except perhaps ofr simple getters and setters. entry() can be called |
| passing from 0 to 4 parameters. Typically these will be parameters passed to the method. |
| The entry() method logs with a level of TRACE and uses a Marker with a name of "ENTER" which |
| is also a "FLOW" Marker. |
| </p> |
| <p> |
| The exit() method should be placed before any return statement or as the last statement of |
| methods without a return. exit() can be called with or without a parameter. Typically, methods |
| that return void will use exit() while methods that return an Object will use exit(Object obj). |
| The entry() method logs with a level of TRACE and uses a Marker with a name of "EXIT" which is |
| also a "FLOW" Marker. |
| </p> |
| <p> |
| The throwing() method can be used by an application when it is throwing an exception that is |
| unlikely to be handled, such as a RuntimeExcpetion. This will insure that proper diagnostics |
| are available if needed. The logging event generated will have a level of ERROR and will have |
| an associated Marker with a name of "THROWING" which is also an "EXCEPTION" Marker. |
| </p> |
| <p> |
| The catching() method can be used by an application when it catches an Exception that it is not |
| going to rethrow, either explicitely or attached to another Exception. The logging event generated |
| will have a level of ERROR and will have an associated Marker with a name of "CATCHING" which is |
| also an "EXCEPTION" Marker. |
| </p> |
| <p> |
| The following example shows a simple application using these methods in a fairly typcial manner. The |
| throwing() is not present since no Exceptions are explicitely thrown and not handled. |
| </p> |
| <div class="source"><pre class="prettyprint"> package com.test; |
| |
| import org.apache.logging.log4j.Logger; |
| import org.apache.logging.log4j.LogManager; |
| |
| import java.util.Random; |
| |
| public class TestService { |
| private Logger logger = LogManager.getLogger(TestService.class.getName()); |
| |
| private String[] messages = new String[] { |
| "Hello, World", |
| "Goodbye Cruel World", |
| "You had me at hello" |
| }; |
| private Random rand = new Random(1); |
| |
| public String retrieveMessage() { |
| logger.entry(); |
| |
| String testMsg = getMessage(getKey()); |
| |
| return logger.exit(testMsg); |
| } |
| |
| public void exampleException() { |
| logger.entry(); |
| try { |
| String msg = messages[messages.length]; |
| logger.error("An exception should have been thrown"); |
| } catch (Exception ex) { |
| logger.catching(ex); |
| } |
| logger.exit(); |
| } |
| |
| public String getMessage(int key) { |
| logger.entry(key); |
| |
| String value = messages[key]; |
| |
| return logger.exit(value); |
| } |
| |
| private int getKey() { |
| logger.entry(); |
| int key = rand.nextInt(messages.length); |
| return logger.exit(key); |
| } |
| }</pre></div> |
| <p> |
| This test application uses the preceding service to generate logging events. |
| </p> |
| <div class="source"><pre class="prettyprint"> package com.test; |
| |
| public class App { |
| |
| public static void main( String[] args ) { |
| TestService service = new TestService(); |
| service.retrieveMessage(); |
| service.retrieveMessage(); |
| service.exampleException(); |
| } |
| }</pre></div> |
| <p> |
| The configuration below will cause all output to be routed to target/test.log. The pattern for |
| the FileAppender includes the class name, line number and method name. Including these |
| in the pattern are critical for the log to be of value. |
| </p> |
| <div class="source"><pre class="prettyprint"> <?xml version="1.0" encoding="UTF-8"?> |
| <configuration status="error"> |
| <appenders> |
| <Console name="Console" target="SYSTEM_OUT"> |
| <ThresholdFilter level="ERROR" onMatch="ACCEPT" onMismatch="DENY"/> |
| <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level %class{36} %L %M - %msg%xEx%n"/> |
| </Console> |
| <File name="log" fileName="target/test.log" append="false"> |
| <PatternLayout pattern="%d{HH:mm:ss.SSS} %-5level %class{36} %L %M - %msg%xEx%n"/> |
| </File> |
| </appenders> |
| <loggers> |
| <root level="trace"> |
| <appender-ref ref="log"/> |
| </root> |
| </loggers> |
| </configuration></pre></div> |
| <p> |
| Here is the output that results from the Java classes and configuration above. |
| </p> |
| <div class="source"><pre class="prettyprint"> |
| 19:08:07.056 TRACE com.test.TestService 19 retrieveMessage - entry |
| 19:08:07.060 TRACE com.test.TestService 46 getKey - entry |
| 19:08:07.060 TRACE com.test.TestService 48 getKey - exit with (0) |
| 19:08:07.060 TRACE com.test.TestService 38 getMessage - entry parms(0) |
| 19:08:07.060 TRACE com.test.TestService 42 getMessage - exit with (Hello, World) |
| 19:08:07.060 TRACE com.test.TestService 23 retrieveMessage - exit with (Hello, World) |
| 19:08:07.061 TRACE com.test.TestService 19 retrieveMessage - entry |
| 19:08:07.061 TRACE com.test.TestService 46 getKey - entry |
| 19:08:07.061 TRACE com.test.TestService 48 getKey - exit with (1) |
| 19:08:07.061 TRACE com.test.TestService 38 getMessage - entry parms(1) |
| 19:08:07.061 TRACE com.test.TestService 42 getMessage - exit with (Goodbye Cruel World) |
| 19:08:07.061 TRACE com.test.TestService 23 retrieveMessage - exit with (Goodbye Cruel World) |
| 19:08:07.062 TRACE com.test.TestService 27 exampleException - entry |
| 19:08:07.077 DEBUG com.test.TestService 32 exampleException - catching java.lang.ArrayIndexOutOfBoundsException: 3 |
| at com.test.TestService.exampleException(TestService.java:29) [classes/:?] |
| at com.test.App.main(App.java:9) [classes/:?] |
| at com.test.AppTest.testApp(AppTest.java:15) [test-classes/:?] |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29] |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29] |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29] |
| at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29] |
| at org.junit.internal.runners.TestMethodRunner.executeMethodBody(TestMethodRunner.java:99) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestMethodRunner.runUnprotected(TestMethodRunner.java:81) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestMethodRunner.runMethod(TestMethodRunner.java:75) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestMethodRunner.run(TestMethodRunner.java:45) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassMethodsRunner.invokeTestMethod(TestClassMethodsRunner.java:66) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassMethodsRunner.run(TestClassMethodsRunner.java:35) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassRunner$1.runUnprotected(TestClassRunner.java:42) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassRunner.run(TestClassRunner.java:52) [junit-4.3.1.jar:?] |
| at org.apache.maven.surefire.junit4.JUnit4TestSet.execute(JUnit4TestSet.java:35) [surefire-junit4-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:115) [surefire-junit4-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:97) [surefire-junit4-2.7.2.jar:2.7.2] |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29] |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29] |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29] |
| at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29] |
| at org.apache.maven.surefire.booter.ProviderFactory$ClassLoaderProxy.invoke(ProviderFactory.java:103) [surefire-booter-2.7.2.jar:2.7.2] |
| at $Proxy0.invoke(Unknown Source) [?:?] |
| at org.apache.maven.surefire.booter.SurefireStarter.invokeProvider(SurefireStarter.java:150) [surefire-booter-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.booter.SurefireStarter.runSuitesInProcess(SurefireStarter.java:91) [surefire-booter-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:69) [surefire-booter-2.7.2.jar:2.7.2] |
| 19:08:07.087 TRACE com.test.TestService 34 exampleException - exit</pre></div> |
| <p> |
| Simply changing the root logger level to DEBUG in the example above will reduce the output |
| considerably. |
| </p> |
| <div class="source"><pre class="prettyprint"> |
| 19:13:24.963 DEBUG com.test.TestService 32 exampleException - catching java.lang.ArrayIndexOutOfBoundsException: 3 |
| at com.test.TestService.exampleException(TestService.java:29) [classes/:?] |
| at com.test.App.main(App.java:9) [classes/:?] |
| at com.test.AppTest.testApp(AppTest.java:15) [test-classes/:?] |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29] |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29] |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29] |
| at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29] |
| at org.junit.internal.runners.TestMethodRunner.executeMethodBody(TestMethodRunner.java:99) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestMethodRunner.runUnprotected(TestMethodRunner.java:81) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestMethodRunner.runMethod(TestMethodRunner.java:75) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestMethodRunner.run(TestMethodRunner.java:45) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassMethodsRunner.invokeTestMethod(TestClassMethodsRunner.java:66) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassMethodsRunner.run(TestClassMethodsRunner.java:35) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassRunner$1.runUnprotected(TestClassRunner.java:42) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.BeforeAndAfterRunner.runProtected(BeforeAndAfterRunner.java:34) [junit-4.3.1.jar:?] |
| at org.junit.internal.runners.TestClassRunner.run(TestClassRunner.java:52) [junit-4.3.1.jar:?] |
| at org.apache.maven.surefire.junit4.JUnit4TestSet.execute(JUnit4TestSet.java:35) [surefire-junit4-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.junit4.JUnit4Provider.executeTestSet(JUnit4Provider.java:115) [surefire-junit4-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.junit4.JUnit4Provider.invoke(JUnit4Provider.java:97) [surefire-junit4-2.7.2.jar:2.7.2] |
| at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[?:1.6.0_29] |
| at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) ~[?:1.6.0_29] |
| at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) ~[?:1.6.0_29] |
| at java.lang.reflect.Method.invoke(Method.java:597) ~[?:1.6.0_29] |
| at org.apache.maven.surefire.booter.ProviderFactory$ClassLoaderProxy.invoke(ProviderFactory.java:103) [surefire-booter-2.7.2.jar:2.7.2] |
| at $Proxy0.invoke(Unknown Source) [?:?] |
| at org.apache.maven.surefire.booter.SurefireStarter.invokeProvider(SurefireStarter.java:150) [surefire-booter-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.booter.SurefireStarter.runSuitesInProcess(SurefireStarter.java:91) [surefire-booter-2.7.2.jar:2.7.2] |
| at org.apache.maven.surefire.booter.ForkedBooter.main(ForkedBooter.java:69) [surefire-booter-2.7.2.jar:2.7.2]</pre></div> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <footer> |
| <div class="container-fluid"> |
| <div class="row footer">Copyright © 1999-2012 <a href="http://www.apache.org">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.</div> |
| </div> |
| </footer> |
| </body> |
| </html> |
