| <!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"> |
| <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"> |
| <strong>Event Logging</strong> |
| </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="EventLogging"></a> |
| <div class="section"><h3>Event Logging<a name="Event_Logging"></a></h3> |
| <p> |
| The EventLogger class provides a simple mechansim for logging events that occur in an application. |
| While the EventLogger is useful as a way of initiating events that should be processed by an audit |
| Logging system, by itself it does not implement any of the features an audit logging system would require |
| such as guaranteed delivery. |
| </p> |
| <p>The recommended way of using the EventLogger in a typcial web application is to populate |
| the ThreadContext Map with data that is related to the entire lifespan of the request such as the user's |
| id, the user's ip address, the product name, etc. This can easily be done in a servlet fileter where |
| the ThreadContext Map can also be cleared at the end of the request. When an event that needs to be |
| recorded occurs a StructuredDataMessage should be created and populated. |
| Then call EventLogger.logEvent(msg) where msg is a reference to the StructuredDataMessage.</p> |
| |
| <div class="source"><pre class="prettyprint"> import org.apache.logging.log4j.ThreadContext; |
| import org.apache.commons.lang.time.DateUtils; |
| |
| import javax.servlet.Filter; |
| import javax.servlet.FilterConfig; |
| import javax.servlet.ServletException; |
| import javax.servlet.ServletRequest; |
| import javax.servlet.ServletResponse; |
| import javax.servlet.FilterChain; |
| import javax.servlet.http.HttpSession; |
| import javax.servlet.http.HttpServletRequest; |
| import javax.servlet.http.Cookie; |
| import javax.servlet.http.HttpServletResponse; |
| import java.io.IOException; |
| import java.util.TimeZone; |
| |
| public class RequestFilter implements Filter { |
| private FilterConfig filterConfig; |
| private static String TZ_NAME = "timezoneOffset"; |
| |
| public void init(FilterConfig filterConfig) throws ServletException { |
| this.filterConfig = filterConfig; |
| } |
| |
| /** |
| * Sample filter that populates the MDC on every request. |
| */ |
| public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) |
| throws IOException, ServletException { |
| HttpServletRequest request = (HttpServletRequest)servletRequest; |
| HttpServletResponse response = (HttpServletResponse)servletResponse; |
| ThreadContext.put("ipAddress", request.getRemoteAddr()); |
| HttpSession session = request.getSession(false); |
| TimeZone timeZone = null; |
| if (session != null) { |
| // Something should set this after authentication completes |
| String loginId = (String)session.getAttribute("LoginId"); |
| if (loginId != null) { |
| ThreadContext.put("loginId", loginId); |
| } |
| // This assumes there is some javascript on the user's page to create the cookie. |
| if (session.getAttribute(TZ_NAME) == null) { |
| if (request.getCookies() != null) { |
| for (Cookie cookie : request.getCookies()) { |
| if (TZ_NAME.equals(cookie.getName())) { |
| int tzOffsetMinutes = Integer.parseInt(cookie.getValue()); |
| timeZone = TimeZone.getTimeZone("GMT"); |
| timeZone.setRawOffset((int)(tzOffsetMinutes * DateUtils.MILLIS_PER_MINUTE)); |
| request.getSession().setAttribute(TZ_NAME, tzOffsetMinutes); |
| cookie.setMaxAge(0); |
| response.addCookie(cookie); |
| } |
| } |
| } |
| } |
| } |
| ThreadContext.put("hostname", servletRequest.getServerName()); |
| ThreadContext.put("productName", filterConfig.getInitParameter("ProductName")); |
| Threadcontext.put("locale", servletRequest.getLocale().getDisplayName()); |
| if (timeZone == null) { |
| timeZone = TimeZone.getDefault(); |
| } |
| ThreadContext.put("timezone", timeZone.getDisplayName()); |
| filterChain.doFilter(servletRequest, servletResponse); |
| ThreadContext.clear(); |
| } |
| |
| public void destroy() { |
| } |
| }</pre></div> |
| <p>Sample class that uses EventLogger.</p> |
| <div class="source"><pre class="prettyprint"> import org.apache.logging.log4j.StructuredDataMessage; |
| import org.apache.logging.log4j.EventLogger; |
| |
| import java.util.Date; |
| import java.util.UUID; |
| |
| public class MyApp { |
| |
| public String doFundsTransfer(Account toAccount, Account fromAccount, long amount) { |
| toAccount.deposit(amount); |
| fromAccount.withdraw(amount); |
| String confirm = UUID.randomUUID().toString(); |
| StructuredDataMessage msg = new StructureDataMessage(confirm, null, "transfer"); |
| msg.put("toAccount", toAccount); |
| msg.put("fromAccount", fromAccount); |
| msg.put("amount", amount); |
| EventLogger.logEvent(data); |
| return confirm; |
| } |
| }</pre></div> |
| <p>The EventLogger class uses a Logger named "EventLogger". EventLogger uses a logging level |
| of OFF as the default to indicate that it cannot be filtered. These events can be |
| formatted for printing using the |
| <a href="../log4j2-core/apidocs/org/apache/logging/log4j/core/layout/StructuredDataLayout.html">StructuredDataLayout</a>. |
| </p> |
| </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> |