Google Git
Sign in
apache / logging-log4j-site / d0d0de55986756593c08e5d2b8059541eacaf428 / . / log4j-2.0-alpha1-SNAPSHOT / manual / eventlogging.html
blob: c3c0e477fb39b783d6b343bba18ac8bad431d091 [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 Jun 9, 2012
| Rendered using Apache Maven Fluido Skin
-->
<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="20120609" />
<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-06-09</li>
<li class="divider">|</li> <li id="projectVersion">Version: 2.0-alpha1-SNAPSHOT</li>
<li class="pull-right"> <a href="http://wiki.apache.org/logging" class="externalLink" title="Logging Wiki">Logging Wiki</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="../../../" title="Logging Services">Logging Services</a>
</li>
<li class="divider pull-right">|</li>
<li class="pull-right"> <a href="../../" title="Log4j">Log4j</a>
</li>
<li class="divider pull-right">|</li>
<li class="pull-right"> <a href="../../companions" title="Log4j Companions">Log4j Companions</a>
</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span3">
<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-og/index.html" title="Flume OG">Flume OG</a>
</li>
<li class="none">
<a href="../log4j-flume-ng/index.html" title="Flume NG">Flume NG</a>
</li>
</ul>
<h3>Project 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="span9" >
<!-- 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 = &quot;timezoneOffset&quot;;
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(&quot;ipAddress&quot;, 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(&quot;LoginId&quot;);
if (loginId != null) {
ThreadContext.put(&quot;loginId&quot;, 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(&quot;GMT&quot;);
timeZone.setRawOffset((int)(tzOffsetMinutes * DateUtils.MILLIS_PER_MINUTE));
request.getSession().setAttribute(TZ_NAME, tzOffsetMinutes);
cookie.setMaxAge(0);
response.addCookie(cookie);
}
}
}
}
}
ThreadContext.put(&quot;hostname&quot;, servletRequest.getServerName());
ThreadContext.put(&quot;productName&quot;, filterConfig.getInitParameter(&quot;ProductName&quot;));
Threadcontext.put(&quot;locale&quot;, servletRequest.getLocale().getDisplayName());
if (timeZone == null) {
timeZone = TimeZone.getDefault();
}
ThreadContext.put(&quot;timezone&quot;, 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, &quot;transfer&quot;);
msg.put(&quot;toAccount&quot;, toAccount);
msg.put(&quot;fromAccount&quot;, fromAccount);
msg.put(&quot;amount&quot;, amount);
EventLogger.logEvent(data);
return confirm;
}
}</pre></div>
<p>The EventLogger class uses a Logger named &quot;EventLogger&quot;. 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 span16">Copyright &copy; 1999-2012
<a href="http://www.apache.org">Apache Software Foundation</a>.
All Rights Reserved.
</div>
</div>
</footer>
</body>
</html>