org.perf4j.log4j.package-info Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of perf4j Show documentation
Performance statistics logging and monitoring toolkit extension to log4j and the java.util.logging framework.
There is a newer version: 0.9.16
/* Copyright (c) 2008-2009 HomeAway, Inc.
 * All rights reserved.  http://www.perf4j.org
 *
 * Licensed 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.
 */
/**
 * Provides the log4j appenders that can be used to automatically aggregate and analyze
 * {@link org.perf4j.StopWatch} timing statements logged to an org.apache.log4j.Logger. Normally, though, if
 * log4j is your logging framework of choice you should use the {@link org.perf4j.log4j.Log4JStopWatch} as your
 * StopWatch implementation. Three appenders are provided:
 *
 * 
 * {@link org.perf4j.log4j.AsyncCoalescingStatisticsAppender} - This appender is used to group logged
 * StopWatch messages over a specified time span (defaults to 30 seconds) into single
 * {@link org.perf4j.GroupedTimingStatistics} messages. Other appenders are designed to be attached to this
 * appender, and these downstream appenders are then only notified of this single GroupedTimingStatistics
 * message at the specified interval. Note that this appender cannot be configured with a log4j.properties file but
 * must instead be configured with a log4j.xml file (if auto-configuration is used in your application).
 * {@link org.perf4j.log4j.JmxAttributeStatisticsAppender} - This appender, when attached to an
 * AsyncCoalescingStatisticsAppender described above, can be used to expose timing statistics (such as mean,
 * min and max values) as attributes on a JMX MBean. Since there are many 3rd party tools designed to interact through
 * JMX, this provides a way to allow monitoring and notification when application runtime performance degrades.
 * {@link org.perf4j.log4j.GraphingStatisticsAppender} - This appender is used to output graphs (as a URL to the
 * graph object) backed by the logged GroupedTimingStatistics instances (thus, it is also designed to be
 * attached to an AsyncCoalescingStatisticsAppender). In addition, these graphs can be made available through
 * a web server using a {@link org.perf4j.log4j.servlet.GraphingServlet} instance in concert with this class.
 * 
 *
 * The following example shows how logging could be configured using a log4j.xml file:
 *
 *  * <?xml version="1.0" encoding="UTF-8" ?>
 * <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
 *
 * <log4j:configuration debug="false" xmlns:log4j="http://jakarta.apache.org/log4j/">
 *   <!-- Main file output appender -->
 *   <appender name="rolling" class="org.apache.log4j.DailyRollingFileAppender">
 *     <param name="File" value="./logs/application.log"/>
 *     <param name="DatePattern" value="'.'yyyy-MM-dd-HH"/>
 *     <layout class="org.apache.log4j.PatternLayout">
 *       <param name="ConversionPattern" value="%-5p[%d{yyyy-MM-dd HH:mm:ss}][%-24t] : %m%n"/>
 *     </layout>
 *   </appender>
 *
 *   <!-- Perf4J appenders -->
 *   <!-- CoalescingStatistics appender used to group StopWatch logs into GroupedTimingStatistics logs -->
 *   <appender name="CoalescingStatistics" class="org.perf4j.log4j.AsyncCoalescingStatisticsAppender">
 *     <param name="TimeSlice" value="10000"/> <!-- 10 second time slice -->
 *     <!-- The appenders defined below are attached here -->
 *     <appender-ref ref="Perf4jJMX"/>
 *     <appender-ref ref="PageTimes"/>
 *     <appender-ref ref="PageTPS"/>
 *   </appender>
 *
 *   <!-- This appender exposes the timing statistics as an MBean through the default platform MBean server -->
 *   <appender name="Perf4jJMX" class="org.perf4j.log4j.JmxAttributeStatisticsAppender">
 *     <param name="TagNamesToExpose" value="operation1,dbcall,servicecall"/>
 *     <param name="MBeanName" value="org.perf4j.beans:type=Perf4J,name=ApplicationPerf"/>
 *   </appender>
 *
 *   <!--
 *     This appender exposes mean execution times as a graph. You would most likely want to use
 *     a {@link org.perf4j.log4j.servlet.GraphingServlet} (set up through a web.xml file) in addition to this appender
 *   -->
 *   <appender name="PageTimes" class="org.perf4j.log4j.GraphingStatisticsAppender">
 *     <param name="GraphType" value="Mean"/>
 *     <param name="TagNamesToGraph" value="operation1,dbcall,servicecall"/>
 *   </appender>
 *
 *   <!--
 *     This appender exposes transactions per second values as a graph, and would also most likely be used
 *     with a {@link org.perf4j.log4j.servlet.GraphingServlet}.
 *   -->
 *   <appender name="PageTPS" class="org.perf4j.log4j.GraphingStatisticsAppender">
 *     <param name="GraphType" value="TPS"/>
 *     <param name="TagNamesToGraph" value="search,propDetails,landingPage,propertyCounts"/>
 *   </appender>
 *
 *   <!-- Loggers -->
 *   <!-- Perf4J logger -->
 *   <logger name="org.perf4j.TimingLogger" additivity="false">
 *     <level value="info"/>
 *     <appender-ref ref="CoalescingStatistics"/>
 *     <appender-ref ref="rolling"/>
 *   </logger>
 *
 *   <root>
 *     <level value="ERROR"/>
 *     <appender-ref ref="rolling"/>
 *   </root>
 * </log4j:configuration>
 *  *
 * @see log4j
 */
package org.perf4j.log4j;