Google Git
Sign in
apache / logging-log4j-site / d0d0de55986756593c08e5d2b8059541eacaf428 / . / log4j-2.0-beta5 / manual / api.html
blob: 1dde280b95f2900c49997edc9dc0b112b0d5bd37 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Generated by Apache Maven Doxia at Apr 20, 2013 -->
<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" />
<title>
Log4j 2 API - Apache Log4j 2</title>
<link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="../css/site.css" type="text/css" />
<script type="text/javascript" src="../js/jquery.min.js"></script>
<script type="text/javascript" src="../js/bootstrap.min.js"></script>
<script type="text/javascript" src="../js/prettify.min.js"></script>
<script type="text/javascript" src="../js/site.js"></script>
<meta name="author" content="Ralph Goers" />
<meta name="author" content="Gary Gregory" />
<meta name="Date-Revision-yyyymmdd" content="20130420" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="composite">
<img class="logo-left" src="../images/ls-logo.jpg" alt="Apache logging services logo" />
<img class="logo-right" src="../images/logo.jpg" alt="Apache log4j logo" />
<div class="clear"></div>
<div class="navbar">
<div class="navbar-inner">
<div class="container-fluid">
<a class="brand" href="http://logging.apache.org/log4j/2.x/">Apache Log4j 2 &trade;</a>
<ul class="nav">
<li>
<a href="http://wiki.apache.org/logging" class="external" target="_blank" title="Logging Wiki">Logging Wiki</a>
</li>
<li>
<a href="http://www.apache.org/" class="external" target="_blank" title="Apache">Apache</a>
</li>
<li>
<a href="../../../" title="Logging Services">Logging Services</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container-fluid">
<table class="layout-table">
<tr>
<td class="sidebar">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-home"></i>Apache Log4j™ 2</li>
<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>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-book"></i>Manual</li>
<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="none">
<a href="../manual/migration.html" title="Log4j 1.x Migration">Log4j 1.x Migration</a>
</li>
<li class="expanded active">
<a href="../manual/api.html" title="API">API</a>
<ul>
<li class="none">
<a href="../manual/flowtracing.html" title="Flow Tracing">Flow Tracing</a>
</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="collapsed">
<a href="../manual/async.html" title="Async Loggers">Async Loggers</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>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Components</li>
<li class="none">
<a href="../log4j-api/index.html" title="API">API</a>
</li>
<li class="none">
<a href="../log4j-core/index.html" title="Implementation">Implementation</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="../log4j-1.2-api/index.html" title="Log4J 1.2 API">Log4J 1.2 API</a>
</li>
<li class="none">
<a href="../log4j-slf4j-impl/index.html" title="SLF4J Binding">SLF4J Binding</a>
</li>
<li class="none">
<a href="../log4j-to-slf4j/index.html" title="Log4j 2 to SLF4J Adapter">Log4j 2 to SLF4J Adapter</a>
</li>
<li class="none">
<a href="../log4j-flume-ng/index.html" title="Apache Flume">Apache Flume</a>
</li>
<li class="none">
<a href="../log4j-web/index.html" title="Log4j Web">Log4j Web</a>
</li>
<li class="none">
<a href="../log4j-taglib/index.html" title="Log4j Tag Library">Log4j Tag Library</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-info-sign"></i>Project Information</li>
<li class="none">
<a href="../dependencies.html" title="Dependencies">Dependencies</a>
</li>
<li class="none">
<a href="../dependency-convergence.html" title="Dependency Convergence">Dependency Convergence</a>
</li>
<li class="none">
<a href="../dependency-management.html" title="Dependency Management">Dependency Management</a>
</li>
<li class="none">
<a href="../team-list.html" title="Project Team">Project Team</a>
</li>
<li class="none">
<a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
</li>
<li class="none">
<a href="../license.html" title="Project License">Project License</a>
</li>
<li class="none">
<a href="../source-repository.html" title="Source Repository">Source Repository</a>
</li>
<li class="none">
<a href="../project-summary.html" title="Project Summary">Project Summary</a>
</li>
</ul>
<ul class="nav nav-list">
<li class="nav-header"><i class="icon-cog"></i>Project Reports</li>
<li class="none">
<a href="../changes-report.html" title="Changes Report">Changes Report</a>
</li>
<li class="none">
<a href="../jira-report.html" title="JIRA Report">JIRA Report</a>
</li>
<li class="none">
<a href="../surefire-report.html" title="Surefire Report">Surefire Report</a>
</li>
<li class="none">
<a href="../rat-report.html" title="RAT Report">RAT Report</a>
</li>
</ul>
</div>
<div id="poweredBy">
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="../images/maven-feather.png" />
</a>
</div>
</td>
<td class="content">
<!-- 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="Overview"></a>
<div class="section"><h3>Overview<a name="Overview"></a></h3>
<p>
The Log4Jj 2 API provides the interface that applications should code to and provides the
adapter components required for implementers to create a logging implementation. Although Log4j 2
is broken up between an API and an implementation, the primary purpose of doing so was not to
allow multiple implementations, although that is certainly possible, but to clearly define
what classes and methods are safe to use in &quot;normal&quot; application code.
</p>
<div class="section"><h4>Hello World!<a name="Hello_World"></a></h4>
<p>
No introduction would be complete without the customary Hello, World example. Here is ours. First,
a Logger with the name &quot;HelloWorld&quot; is obtained from the
<a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html">LogManager</a>.
Next, the logger is used to write the &quot;Hello, World!&quot; message, however the message will be written
only if the Logger is configured to allow informational messages.
</p>
<div class="prettyprint linenums"><pre>import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
public class HelloWorld {
private static Logger logger = LogManager.getLogger(&quot;HelloWorld&quot;);
public static void main(String[] args) {
logger.info(&quot;Hello, World!&quot;);
}
}</pre></div>
<p>
The output from the call to logger.info() will vary significantly depending on the configuration
used. See the <a href="./configuration.html">Configuration</a> section for more details.
</p>
</div><div class="section"><h4>Substituting Parameters<a name="Substituting_Parameters"></a></h4>
<p>
Frequently the purpose of logging is to provide information about what is happening in the system,
which requires including information about the objects being manipulated. In Log4j 1.x this could
be accomplished by doing:
</p>
<div class="prettyprint linenums"><pre>if (logger.isDebugEnabled()) {
logger.debug(&quot;Logging in user &quot; + user.getName() + &quot; with birthday &quot; + user.getBirthdayCalendar());
}</pre></div>
<p>
Doing this repeatedly has the effect of making the code feel like it is more about logging than the
actual task at hand. In addition, it results in the logging level being checked twice; once on the
call to isDebugEnabled and once on the debug method. A better alternative would be:
</p>
<div class="prettyprint"><pre>logger.debug(&quot;Logging in user {} with birthday {}&quot;, user.getName(), user.getBirthdayCalendar());</pre></div>
<p>
With the code above the logging level will only be checked once and the String construction will
only occur when debug logging is enabled.
</p>
</div><div class="section"><h4>Formatting Parameters<a name="Formatting_Parameters"></a></h4>
<p>
Substituting parameters leaves formatting up to you if <tt>toString()</tt> is not what you want.
To facilitate formatting, you can use the same format strings as Java's
<a class="externalLink" href="http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Formatter.html#syntax">Formatter</a>.
For example:
</p>
<div class="prettyprint linenums"><pre>public static Logger logger = LogManager.getFormatterLogger(&quot;Foo&quot;);
logger.debug(&quot;Logging in user %s with birthday %s&quot;, user.getName(), user.getBirthdayCalendar());
logger.debug(&quot;Logging in user %1$s with birthday %2$tm %2$te,%2$tY&quot;, user.getName(), user.getBirthdayCalendar());
logger.debug(&quot;Integer.MAX_VALUE = %,d&quot;, Integer.MAX_VALUE);
logger.debug(&quot;Long.MAX_VALUE = %,d&quot;, Long.MAX_VALUE);
</pre></div>
<p>
To use a formatter Logger, you must call one of the LogManager
<a href="../log4j-api/apidocs/org/apache/logging/log4j/LogManager.html#getFormatterLoggerjava.lang.Class">getFormatterLogger</a>
method. The output for this example shows that Calendar toString() is verbose compared to custom formatting:
</p>
<div class="prettyprint linenums"><pre>2012-12-12 11:56:19,633 [main] DEBUG: User John Smith with birthday java.util.GregorianCalendar[time=?,areFieldsSet=false,areAllFieldsSet=false,lenient=true,zone=sun.util.calendar.ZoneInfo[id=&quot;America/New_York&quot;,offset=-18000000,dstSavings=3600000,useDaylight=true,transitions=235,lastRule=java.util.SimpleTimeZone[id=America/New_York,offset=-18000000,dstSavings=3600000,useDaylight=true,startYear=0,startMode=3,startMonth=2,startDay=8,startDayOfWeek=1,startTime=7200000,startTimeMode=0,endMode=3,endMonth=10,endDay=1,endDayOfWeek=1,endTime=7200000,endTimeMode=0]],firstDayOfWeek=1,minimalDaysInFirstWeek=1,ERA=?,YEAR=1995,MONTH=4,WEEK_OF_YEAR=?,WEEK_OF_MONTH=?,DAY_OF_MONTH=23,DAY_OF_YEAR=?,DAY_OF_WEEK=?,DAY_OF_WEEK_IN_MONTH=?,AM_PM=0,HOUR=0,HOUR_OF_DAY=0,MINUTE=0,SECOND=0,MILLISECOND=?,ZONE_OFFSET=?,DST_OFFSET=?]
2012-12-12 11:56:19,643 [main] DEBUG: User John Smith with birthday 05 23, 1995
2012-12-12 11:56:19,643 [main] DEBUG: Integer.MAX_VALUE = 2,147,483,647
2012-12-12 11:56:19,643 [main] DEBUG: Long.MAX_VALUE = 9,223,372,036,854,775,807
</pre></div>
</div></div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &copy; 1999-2013 <a class="external" href="http://www.apache.org">Apache Software Foundation</a>. All Rights Reserved.</p>
<p>Apache Logging, Apache Log4j, Log4j, Apache, the Apache feather logo, and the Apache Logging project logo are trademarks of The Apache Software Foundation.</p>
<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from <a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</div>
</body>
</html>