| <?xml version="1.0"?> |
| <!-- |
| 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. |
| --> |
| |
| <document> |
| <properties> |
| <title>Log4J 2.0 API</title> |
| <author email="rgoers@apache.org">Ralph Goers</author> |
| </properties> |
| |
| <body> |
| <section name="Log4j 2.0 API"> |
| <a name="EventLogging"/> |
| <subsection name="Event Logging"> |
| <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> |
| |
| <source> 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() { |
| } |
| }</source> |
| <p>Sample class that uses EventLogger.</p> |
| <source> 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; |
| } |
| }</source> |
| <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> |
| </subsection> |
| </section> |
| </body> |
| </document> |
