You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ni...@apache.org on 2008/02/26 10:31:36 UTC
svn commit: r631142 - in /commons/sandbox/monitoring/trunk: ./
src/main/java/org/apache/commons/monitoring/
src/main/java/org/apache/commons/monitoring/impl/
src/main/java/org/apache/commons/monitoring/reporting/
src/main/java/org/apache/commons/monito...
Author: nicolas
Date: Tue Feb 26 01:31:23 2008
New Revision: 631142
URL: http://svn.apache.org/viewvc?rev=631142&view=rev
Log:
documentation
periodic reporting to logs using secondaryRepository
StopWatch redesigned as interface
Added:
commons/sandbox/monitoring/trunk/LICENSE.txt (props changed)
- copied unchanged from r618221, commons/sandbox/monitoring/trunk/src/main/resources/META-INF/LICENSE.txt
commons/sandbox/monitoring/trunk/NOTICE.txt (props changed)
- copied unchanged from r618221, commons/sandbox/monitoring/trunk/src/main/resources/META-INF/NOTICE.txt
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java (contents, props changed)
- copied, changed from r618223, commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/StopWatch.java
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java (with props)
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java (with props)
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java (with props)
commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml (with props)
commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml (with props)
commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml (with props)
commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java (with props)
Removed:
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/StopWatch.java
commons/sandbox/monitoring/trunk/src/main/resources/META-INF/LICENSE.txt
commons/sandbox/monitoring/trunk/src/main/resources/META-INF/NOTICE.txt
Modified:
commons/sandbox/monitoring/trunk/pom.xml
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/ExecutionStack.java
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitor.java
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitoring.java
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Repository.java
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/AbstractRepository.java
commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultRepository.java
commons/sandbox/monitoring/trunk/src/site/site.xml
commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/ExecutionStackTest.java
commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/StopWatchTest.java
Propchange: commons/sandbox/monitoring/trunk/LICENSE.txt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/LICENSE.txt
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/LICENSE.txt
------------------------------------------------------------------------------
svn:mergeinfo =
Propchange: commons/sandbox/monitoring/trunk/NOTICE.txt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/NOTICE.txt
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/NOTICE.txt
------------------------------------------------------------------------------
svn:mergeinfo =
Modified: commons/sandbox/monitoring/trunk/pom.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/pom.xml?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/pom.xml (original)
+++ commons/sandbox/monitoring/trunk/pom.xml Tue Feb 26 01:31:23 2008
@@ -18,14 +18,12 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/maven-v4_0_0.xsd">
-
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.apache.commons</groupId>
<artifactId>commons-sandbox-parent</artifactId>
<version>3</version>
</parent>
-
<artifactId>commons-monitoring</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>
@@ -43,7 +41,6 @@
<version>3.8.1</version>
<scope>test</scope>
</dependency>
-
<dependency>
<groupId>commons-io</groupId>
<artifactId>commons-io</artifactId>
@@ -57,7 +54,6 @@
<scope>test</scope>
</dependency>
</dependencies>
-
<developers>
<developer>
<id>nicolas</id>
@@ -67,13 +63,11 @@
<timezone>+10</timezone>
</developer>
</developers>
-
<scm>
<connection>scm:svn:http://svn.apache.org/repos/asf/commons/sandbox/monitoring/trunk/</connection>
<developerConnection>scm:svn:https://svn.apache.org/repos/asf/commons/sandboxmonitoring/trunk/</developerConnection>
<url>http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/</url>
</scm>
-
<build>
<plugins>
<!-- TODO : investigate OSGi support
@@ -101,86 +95,80 @@
</excludes>
</configuration>
</plugin>
-
- <!--
- FIXME waiting for Retrotranslator 1.2.4 to get deployed on central
- <plugin>
+ <plugin>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.1</version>
<executions>
- <execution>
- <id>backport</id>
- <phase>package</phase>
- <goals>
- <goal>run</goal>
- </goals>
- <configuration>
- <tasks>
- <mkdir dir="${basedir}/target/backport" />
- <java classname="net.sf.retrotranslator.transformer.Retrotranslator" failonerror="true">
- <classpath>
- <path refid="maven.plugin.classpath" />
- <path refid="maven.compile.classpath" />
- </classpath>
- <arg value="-smart" />
- <arg value="-srcdir" />
- <arg value="${basedir}/target/classes" />
- <arg value="-destdir" />
- <arg value="${basedir}/target/backport" />
- <arg value="-target" />
- <arg value="1.3" />
- <arg value="-backport" />
- <arg
- value="java.util.concurrent:edu.emory.mathcs.backport.java.util.concurrent;
+ <execution>
+ <id>backport</id>
+ <phase>package</phase>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ <configuration>
+ <tasks>
+ <mkdir dir="${basedir}/target/backport" />
+ <java classname="net.sf.retrotranslator.transformer.Retrotranslator" failonerror="true">
+ <classpath>
+ <path refid="maven.plugin.classpath" />
+ <path refid="maven.compile.classpath" />
+ </classpath>
+ <arg value="-smart" />
+ <arg value="-srcdir" />
+ <arg value="${basedir}/target/classes" />
+ <arg value="-destdir" />
+ <arg value="${basedir}/target/backport" />
+ <arg value="-target" />
+ <arg value="1.3" />
+ <arg value="-backport" />
+ <arg
+ value="java.util.concurrent:edu.emory.mathcs.backport.java.util.concurrent;
java.lang.System.nanoTime:edu.emory.mathcs.backport.java.util.concurrent.helpers.Utils.nanoTime;
java.lang.StringBuilder:java.lang.StringBuffer;
org.apache.commons.monitoring.support.java13;" />
- </java>
- </tasks>
- </configuration>
- </execution>
+ </java>
+ </tasks>
+ </configuration>
+ </execution>
</executions>
<dependencies>
- <dependency>
- <groupId>net.sf.retrotranslator</groupId>
- <artifactId>retrotranslator-transformer</artifactId>
- <version>1.2.4</version>
- <scope>system</scope>
- </dependency>
- <dependency>
- <groupId>net.sf.retrotranslator</groupId>
- <artifactId>retrotranslator-runtime</artifactId>
- <version>1.2.4</version>
- <scope>system</scope>
- </dependency>
- <dependency>
- <groupId>backport-util-concurrent</groupId>
- <artifactId>backport-util-concurrent</artifactId>
- <version>3.1</version>
- </dependency>
+ <dependency>
+ <groupId>net.sf.retrotranslator</groupId>
+ <artifactId>retrotranslator-transformer</artifactId>
+ <version>1.2.4</version>
+ </dependency>
+ <dependency>
+ <groupId>net.sf.retrotranslator</groupId>
+ <artifactId>retrotranslator-runtime</artifactId>
+ <version>1.2.4</version>
+ </dependency>
+ <dependency>
+ <groupId>backport-util-concurrent</groupId>
+ <artifactId>backport-util-concurrent</artifactId>
+ <version>3.1</version>
+ </dependency>
</dependencies>
- </plugin>
- <plugin>
+ </plugin>
+ <plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2-beta-1</version>
<executions>
- <execution>
- <id>backport</id>
- <phase>package</phase>
- <goals>
- <goal>attached</goal>
- </goals>
- <configuration>
- <descriptors>
- <descriptor>src/assembly/backport.xml</descriptor>
- </descriptors>
- </configuration>
- </execution>
+ <execution>
+ <id>backport</id>
+ <phase>package</phase>
+ <goals>
+ <goal>attached</goal>
+ </goals>
+ <configuration>
+ <descriptors>
+ <descriptor>src/assembly/backport.xml</descriptor>
+ </descriptors>
+ </configuration>
+ </execution>
</executions>
- </plugin> -->
+ </plugin>
</plugins>
</build>
-
<distributionManagement>
<site>
<id>website</id>
@@ -194,17 +182,15 @@
<maven.compile.source>1.5</maven.compile.source>
<maven.compile.target>1.5</maven.compile.target>
</properties>
-
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<configuration>
- <targetJdk>1.5</targetJdk>
+ <targetJdk>1.5</targetJdk>
</configuration>
</plugin>
</plugins>
</reporting>
-
</project>
Modified: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/ExecutionStack.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/ExecutionStack.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/ExecutionStack.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/ExecutionStack.java Tue Feb 26 01:31:23 2008
@@ -20,6 +20,8 @@
import java.util.LinkedList;
import java.util.List;
+import org.apache.commons.monitoring.impl.DefaultStopWatch;
+
/**
* Sometime we need to compare elapsed time from a high level process with fine-grained
* sub-processes to find bottlenecks or errors. The <code>ExecutionStack</code> allows
@@ -41,9 +43,9 @@
super();
}
- private static ThreadLocal<List<StopWatch>> local = new ThreadLocal<List<StopWatch>>();
+ private static ThreadLocal<List<DefaultStopWatch>> local = new ThreadLocal<List<DefaultStopWatch>>();
- public static void push( StopWatch stopWatch )
+ public static void push( DefaultStopWatch stopWatch )
{
getExecution().add( stopWatch );
}
@@ -89,12 +91,12 @@
/**
* @return the ordered list of StopWatches used during execution
*/
- public static List<StopWatch> getExecution()
+ public static List<DefaultStopWatch> getExecution()
{
- List<StopWatch> exec = local.get();
+ List<DefaultStopWatch> exec = local.get();
if (exec == null)
{
- exec = new LinkedList<StopWatch>();
+ exec = new LinkedList<DefaultStopWatch>();
local.set( exec );
}
return local.get();
Modified: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitor.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitor.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitor.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitor.java Tue Feb 26 01:31:23 2008
@@ -52,7 +52,7 @@
*/
public interface Monitor
{
- /** default role key for execution performances */
+ /** default role key for code performances */
String PERFORMANCES = "performances";
/** default role for multi-thread concurrency */
Modified: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitoring.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitoring.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitoring.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Monitoring.java Tue Feb 26 01:31:23 2008
@@ -18,6 +18,7 @@
package org.apache.commons.monitoring;
import org.apache.commons.monitoring.impl.DefaultRepository;
+import org.apache.commons.monitoring.impl.DefaultStopWatch;
/**
* Utility class for simpified application instrumentation
@@ -60,7 +61,7 @@
public static StopWatch start( String name, String category, String subsystem )
{
- return new StopWatch( getMonitor( name, category, subsystem ) );
+ return repository.start( getMonitor( name, category, subsystem ) );
}
public static void setRepository( Repository repository )
Modified: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Repository.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Repository.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Repository.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/Repository.java Tue Feb 26 01:31:23 2008
@@ -77,6 +77,13 @@
void removeListener( Listener listener );
/**
+ * Start a StopWatch to monitor execution
+ * @param monitor the monitor associated with the process
+ * @return a running StopWatch
+ */
+ StopWatch start( Monitor monitor );
+
+ /**
* Listener interface to get notified on repository events
*
* @author <a href="mailto:nicolas@apache.org">Nicolas De Loof</a>
Modified: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/AbstractRepository.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/AbstractRepository.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/AbstractRepository.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/AbstractRepository.java Tue Feb 26 01:31:23 2008
@@ -27,6 +27,7 @@
import org.apache.commons.monitoring.Monitor;
import org.apache.commons.monitoring.Repository;
+import org.apache.commons.monitoring.StopWatch;
import org.apache.commons.monitoring.Monitor.Key;
/**
@@ -134,6 +135,16 @@
{
monitor.reset();
}
+ }
+
+
+ /**
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.Repository#start(org.apache.commons.monitoring.Monitor)
+ */
+ public StopWatch start( Monitor monitor )
+ {
+ return new DefaultStopWatch( monitor );
}
}
Modified: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultRepository.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultRepository.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultRepository.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultRepository.java Tue Feb 26 01:31:23 2008
@@ -65,4 +65,5 @@
{
return new CompositeValuesMonitor( key );
}
+
}
Copied: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java (from r618223, commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/StopWatch.java)
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java?p2=commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java&p1=commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/StopWatch.java&r1=618223&r2=631142&rev=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/StopWatch.java (original)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java Tue Feb 26 01:31:23 2008
@@ -15,15 +15,26 @@
* limitations under the License.
*/
-package org.apache.commons.monitoring;
+package org.apache.commons.monitoring.impl;
+
+import java.util.Stack;
+
+import org.apache.commons.monitoring.ExecutionStack;
+import org.apache.commons.monitoring.Monitor;
+import org.apache.commons.monitoring.StopWatch;
/**
* Estimates the time required for process execution (monitored method, service
- * invocation, database request...)
+ * invocation, database request...).
+ * <p>
+ * The StopWatch maintains a threadLocal stack of active StopWatches. When a new
+ * StopWatch is created by a sub-process, it automatically pause the "parent"
+ * running StopWatch, so that the top-level elapsed time = Sum( all StopWatches
+ * running times ).
*
* @author <a href="mailto:nicolas@apache.org">Nicolas De Loof</a>
*/
-public class StopWatch
+public class DefaultStopWatch implements StopWatch
{
/** Time the probe was started */
private final long startedAt;
@@ -43,7 +54,9 @@
/** Monitor that is notified of process execution state */
private final Monitor monitor;
- private static boolean useExecutionStack;
+ private static boolean traceExecution;
+
+ private static final ThreadLocal<Stack<DefaultStopWatch>> STACK = new ThreadLocal<Stack<DefaultStopWatch>>();
/**
* Constructor.
@@ -53,7 +66,7 @@
*
* @param monitor the monitor associated with the process to be monitored
*/
- public StopWatch( Monitor monitor )
+ public DefaultStopWatch( Monitor monitor )
{
super();
this.monitor = monitor;
@@ -62,33 +75,64 @@
{
monitor.getGauge( Monitor.CONCURRENCY ).increment();
}
- if ( useExecutionStack )
+ push();
+ if ( traceExecution )
{
ExecutionStack.push( this );
}
}
+ private void push()
+ {
+ Stack<DefaultStopWatch> stack = getStack();
+ if ( !stack.empty() )
+ {
+ stack.peek().pause();
+ }
+ stack.push( this );
+ }
+
+ private void pop()
+ {
+ Stack<DefaultStopWatch> stack = getStack();
+ stack.pop();
+ if ( !stack.empty() )
+ {
+ stack.peek().resume();
+ }
+ }
+
+ private Stack<DefaultStopWatch> getStack()
+ {
+ Stack<DefaultStopWatch> stack = STACK.get();
+ if ( stack == null )
+ {
+ stack = new Stack<DefaultStopWatch>();
+ STACK.set( stack );
+ }
+ return stack;
+ }
+
/**
- * @return Elapsed time (in nanoseconds) for the monitored process
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#getElapsedTime()
*/
public long getElapsedTime()
{
- long delay;
if ( stoped || paused )
{
- delay = stopedAt - startedAt - pauseDelay;
+ return stopedAt - startedAt - pauseDelay;
}
else
{
// Still running !
- delay = nanotime() - startedAt - pauseDelay;
+ return nanotime() - startedAt - pauseDelay;
}
- return delay;
}
/**
- * Temporary stop the StopWatch. Elapsed time calculation will not include
- * time spent in paused mode.
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#pause()
*/
public void pause()
{
@@ -100,7 +144,8 @@
}
/**
- * Resume the StopWatch after a pause.
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#resume()
*/
public void resume()
{
@@ -113,8 +158,8 @@
}
/**
- * Stop monitoring the process. A StopWatch created with
- * {@link #start(Monitor)} cannot be re-used after stopped has been called.
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#stop()
*/
public void stop()
{
@@ -132,19 +177,17 @@
monitor.getGauge( Monitor.CONCURRENCY ).decrement();
monitor.getCounter( Monitor.PERFORMANCES ).add( getElapsedTime() );
}
+ pop();
}
- if ( useExecutionStack && ExecutionStack.isFinished() )
+ if ( traceExecution && ExecutionStack.isFinished() )
{
ExecutionStack.clear();
}
}
/**
- * Convenience method to stop or cancel a Stopwatch depending on success of
- * monitored operation
- *
- * @param canceled
- * @return time elapsed since the probe has been started
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#stop(boolean)
*/
public void stop( boolean canceled )
{
@@ -159,17 +202,8 @@
}
/**
- * Cancel monitoring. Elapsed time will not be computed and will not be
- * published to the monitor.
- * <p>
- * In some circumstances you want to monitor time elapsed from early stage
- * of computation, and discover latter if the computed data is relevant. For
- * example, monitoring a messaging system, but beeing interested only by
- * some types of messages. In such case, a StopWatch can be started early
- * and canceled when the application is able to determine it's relevancy.
- * <p>
- * In any way, the probe will still report thread concurrency even if
- * canceled.
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#cancel()
*/
public void cancel()
{
@@ -180,8 +214,9 @@
{
monitor.getGauge( Monitor.CONCURRENCY ).decrement();
}
+ pop();
}
- if ( useExecutionStack && ExecutionStack.isFinished() )
+ if ( traceExecution && ExecutionStack.isFinished() )
{
ExecutionStack.clear();
}
@@ -224,7 +259,8 @@
}
/**
- * @return <code>true</code> if the StopWatch has been stopped
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#isStoped()
*/
public boolean isStoped()
{
@@ -232,7 +268,8 @@
}
/**
- * @return <code>true</code> if the StopWatch has been paused
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#isPaused()
*/
public boolean isPaused()
{
@@ -264,13 +301,22 @@
}
/**
+ * {@inheritDoc}
+ * @see org.apache.commons.monitoring.StopWatch#getMonitor()
+ */
+ public Monitor getMonitor()
+ {
+ return monitor;
+ }
+
+ /**
* Enable automatic registration to the ExecutionStack and cleanup after the
* last stopWatch has been stopped.
*
- * @param useExecutionStack
+ * @param traceExecution
*/
- public static void setUseExecutionStack( boolean useExecutionStack )
+ public static void setTraceExecution( boolean traceExecution )
{
- StopWatch.useExecutionStack = useExecutionStack;
+ DefaultStopWatch.traceExecution = traceExecution;
}
}
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/impl/DefaultStopWatch.java
------------------------------------------------------------------------------
svn:mergeinfo =
Added: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java (added)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java Tue Feb 26 01:31:23 2008
@@ -0,0 +1,97 @@
+/*
+ * 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.
+ */
+
+package org.apache.commons.monitoring.reporting;
+
+import java.io.IOException;
+import java.util.Timer;
+import java.util.TimerTask;
+
+import org.apache.commons.monitoring.Repository;
+import org.apache.commons.monitoring.listeners.SecondaryRepository;
+
+/**
+ * An helper class to build a periodic task that logs the monitored application
+ * state for a period.
+ * <p>
+ * Typical use of this class is to implement the log method to format the
+ * indicators and append the result for each period in a log file.
+ *
+ * @author <a href="mailto:nicolas@apache.org">Nicolas De Loof</a>
+ */
+public abstract class AbstractPeriodicLogger
+ extends TimerTask
+{
+ /** The timer that handles the period */
+ private Timer timer;
+
+ /** The observed repository */
+ private Repository repository;
+
+ /** The observed repository */
+ private SecondaryRepository secondary;
+
+
+ /**
+ * @param period the period (in ms) to log the monitoring state
+ * @param repository the target monitoring repository
+ */
+ public AbstractPeriodicLogger( long period, Repository repository )
+ {
+ super();
+ this.secondary = new SecondaryRepository( repository );
+ timer = new Timer();
+ timer.scheduleAtFixedRate( this, period, period );
+ }
+
+ /**
+ *
+ */
+ public void stop()
+ {
+ timer.cancel();
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * @see java.util.TimerTask#run()
+ */
+ @Override
+ public void run()
+ {
+ try
+ {
+ // Create a new observer for the next period
+ SecondaryRepository period = secondary;
+ period.detach();
+ secondary = new SecondaryRepository( repository );
+
+ log( period );
+ }
+ catch (Exception exception)
+ {
+ // catch any exception, as throwing it will stop the time
+ }
+ }
+
+ /**
+ * Log the data from the (secondary) repository generated during the period
+ * @param period secondary repository that observed the monitored state during the last active period
+ */
+ protected abstract void log( Repository period ) throws IOException;
+}
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AbstractPeriodicLogger.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java (added)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java Tue Feb 26 01:31:23 2008
@@ -0,0 +1,80 @@
+/*
+ * 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.
+ */
+
+package org.apache.commons.monitoring.reporting;
+
+import java.io.File;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.io.Writer;
+
+import org.apache.commons.monitoring.Repository;
+
+/**
+ * An abstract periodic logger implementation that uses a predefine set of
+ * "indicators" to output monitored state in a log.
+ * <p>
+ * Typical use case is to produce a fixed format (CSV, Excel-like, tabular...)
+ * in a log file, with a new line for each period.
+ *
+ * @author <a href="mailto:nicolas@apache.org">Nicolas De Loof</a>
+ */
+public abstract class AppendToFilePeriodicLogger
+ extends AbstractPeriodicLogger
+{
+
+ private File output;
+
+ /**
+ * @param period the period (in ms) to log the monitoring state
+ * @param repository the target monitoring repository
+ * @param output the output file
+ */
+ public AppendToFilePeriodicLogger( long period, Repository repository, File output )
+ {
+ super( period, repository );
+ this.output = output;
+ }
+
+ /**
+ * Log the data from the (secondary) repository generated during the period
+ *
+ * @param period secondary repository that observed the monitored state
+ * during the last active period
+ */
+ @Override
+ protected final void log( Repository period )
+ throws IOException
+ {
+ output.mkdirs();
+ Writer writer = new FileWriter( output, true );
+ // Log the detached state
+ log( period, writer );
+ writer.close();
+ }
+
+ /**
+ * Log the data from the (secondary) repository generated during the period
+ *
+ * @param period secondary repository that observed the monitored state
+ * during the last active period
+ * @param writer the output to log repository
+ * @throws IOException any I/O error during log
+ */
+ protected abstract void log( Repository period, Writer writer ) throws IOException;
+
+}
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/reporting/AppendToFilePeriodicLogger.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java (added)
+++ commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java Tue Feb 26 01:31:23 2008
@@ -0,0 +1,31 @@
+/*
+ * 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.
+ */
+
+package org.apache.commons.monitoring.support.java13.java.io;
+
+import java.io.File;
+
+/**
+ * @author <a href="mailto:nicolas@apache.org">Nicolas De Loof</a>
+ */
+public class _FileWriter
+{
+ public static Object[] convertConstructorArguments( File file, boolean append )
+ {
+ return new Object[] { file.getAbsolutePath(), append };
+ }
+}
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/main/java/org/apache/commons/monitoring/support/java13/java/io/_FileWriter.java
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: commons/sandbox/monitoring/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/site/site.xml?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/site/site.xml (original)
+++ commons/sandbox/monitoring/trunk/src/site/site.xml Tue Feb 26 01:31:23 2008
@@ -27,8 +27,13 @@
<menu name="Monitoring">
<item name="Overview" href="/index.html"/>
<item name="Proposal" href="/PROPOSAL.html"/>
- <item name="Tutorial" href="/tutorial.html"/>
<item name="Wiki" href="http://wiki.apache.org/commons/Monitoring"/>
+ </menu>
+ <menu name="User Guide">
+ <item name="Quick Tutorial" href="/tutorial.html"/>
+ <item name="Instrumentation" href="/instrumentation.html"/>
+ <item name="Listeners" href="/listeners.html"/>
+ <item name="Reporting" href="/reporting.html"/>
</menu>
</body>
Added: commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml (added)
+++ commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml Tue Feb 26 01:31:23 2008
@@ -0,0 +1,181 @@
+<?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>Instrumentation of the monitored application</title>
+ </properties>
+
+ <body>
+
+ <section name="Introduction">
+ <p>
+ Before anything can be reported, the application have to expose it's state to the monitoring
+ infrastructure. In Commons Monitoring vocabulary this is called <b>instrumentation</b> of the
+ application. Commons Monitoring defines a simple lightweight API for this purpose.
+ </p>
+ </section>
+
+ <section name="Concepts">
+ <subsection name="Monitors">
+ <p>
+ The application exposes it's state based on <b>monitors</b>. A monitor is an abstraction for any
+ element in the application that can expose state or resource consumption. It is identified by :
+ <ul>
+ <li>a <b>name</b> that is the human readable representation of the exposed state</li>
+ <li>a <b>category</b> that matches technical layering of the application
+ ("web", "model", "dao"...)</li>
+ <li>a <b>subsystem</b> that associate the monitor to a functional subsystem in the application
+ ("admin", "accounts management" ...)</li>
+ </ul>
+ </p>
+ <p>
+
+ Only the name is required, but category and subsystem is a nice way to group monitors by technical
+ or functional criteria.
+ </p>
+ </subsection>
+ <subsection name="Repository">
+ <p>
+ Monitors are registered in a repository, that ensure a monitor is unique for a name/category/subsytem
+ Key. The repository is used to retrieve existing monitors and create new ones. The default repository
+ implementation <code>org.apache.commons.monitoring.impl.DefaultRepository</code> creates new Monitor
+ instance when a non-existing one is requested, so you don't have to worry about monitors management.
+ <pre>
+ Monitor monitor = repository.getMonitor( "MyService.myMethod" );
+ Monitor monitor = repository.getMonitor( "SoapEndpoint.process", "soap" );
+ Monitor monitor = repository.getMonitor( "/admin/userEdit.do", "struts", "user management" );
+ </pre>
+ </p>
+ </subsection>
+ <subsection name="Counters and Gauges">
+ <p>
+ Monitors manage a set of <code>StatValues</code> that the application uses to expose state.
+ There is two types of values that application can use, depending on the data to be exposed :
+ <ul>
+ <li>a <b>Counter</b> is used to expose cumulative events. The value a counter maintains
+ will grow during the application life : time elapsed by some code to execute, number of bytes or
+ lines proceeded by a batch process, number of requests on a web URI...
+ <br/>
+ A counter is used by application using the <code>add()</code> method
+ to expose how the counter must increment when some operation have proceeded.
+ </li>
+ <li>a <b>Gauge</b> is used to expose an internal state that increases and decreases
+ during application life : concurrent threads, open connections, active users...
+ <br/>
+ A gauge is used by the application using the <code>incremenet()</code> and <code>decrement()</code>
+ methods to expose the application state changes. The <code>set()</code> method can also be used to
+ force an initial value or to expose an absolute value when the application does not compute it's state
+ as a change from a previous value. Typically, a <code>connectionManager</code> component will use
+ increment/decrement to expose active connections, and a <code>fileSystemMonitor</code> will use
+ set to expose free space on disks.
+ </li>
+ </ul>
+ </p>
+ <p>
+ In both cases, the statValues compute statistical information from what the application exposes, like
+ min / max / mean and standardDeviation, that in many case is more informative than the current value.
+ </p>
+ <p>
+ The statValues are identified in a monitor by a role. There is predefined roles for performances and
+ concurrency monitoring, and any other relevant counter/gauge can be registered to a monitor. The default
+ <code>org.apache.commons.monitoring.impl.CreateValuesOnDemandMonitor</code> monitor implementation will
+ create the required Gauge/Counters implementation when a statValue is requested by the application.
+ <pre>
+ Monitor monitor = repository.getMonitor( "SoapEndpoint.process", "soap" );
+
+ // Process a SOAP message
+
+ // retrieve the custom Counter for the "byte" role
+ monitor.getCounter( "bytes" ).add( SOAPMessage.getSize() );
+ </pre>
+ </p>
+ </subsection>
+ <subsection name="StopWatches">
+ <p>Performance monitoring is first-class use case of Commons Monitoring. The
+ <code>org.apache.commons.monitoring.StopWatch</code> class provides the necessary tooling
+ to compute and monitor code or service invocation performances. A StopWatch is created
+ by the repository for a monitor. The stopwatch is initialy "started", and will compute
+ elapsed time until it is stopped by the application. The application MUST ALLWAYS stop
+ the StopWatches it has created ! To ensure this, always use a finally block :
+ <pre>
+ StopWatch stopWatch = repository.start( myMonitor );
+ try
+ {
+ // Do something that takes time and requires monitoring
+ }
+ finally
+ {
+ stopWatch.stop();
+ }
+ </pre>
+ </p>
+ <p>
+ You can nest stopWatches, in many case by monitoring some high-level process (for example web
+ request rendering time) and nested low-level service (remote service invocation, JDBC request...).
+ The StopWatch provides two methods for executed code performance :
+ <ul>
+ <li><code>getElapsedTime()</code> returns the time (in ns) elapsed between the stopWatch creation
+ and the moment it was stopped, including any other sub-process</li>
+ <li><code>getRunningTime()</code> returns same time MINUS time elapsed in StopWatches that
+ monitor sub-processes.</li>
+ </ul>
+ The monitor maintains statistics about those informations as the PERFORMANCE and RESPONSE_TIME
+ counters. First one only computes performance of the target code, not sub-processes.
+ </p>
+ <p>
+ The default StopWatch implementation (<code>org.apache.commons.monitoring.impl.DefaultStopWatch.java</code>)
+ can optionally maintain the List of StopWatches involved in the current thread processing via the
+ <code>ExecutionStack</code>. To enable this feature, invoke <code>DefaultStopWatch.setTraceExecution()</code>
+ at application startup.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Helpers">
+ <p>
+ The <b>Monitoring</b> class is a convenience utility class to make application instrumentation
+ as simple as possible. To monitor application performance, simply do :
+ <pre>
+ public void myMethodToGetMonitored()
+ {
+ StopWatch stopWatch = Monitoring.start( "MyClass.myMethod" );
+ try
+ {
+ // Do something that takes time and requires monitoring
+ }
+ finally
+ {
+ stopWatch.stop();
+ }
+ }
+ </pre>
+ The StopWatch class will compute the time elapsed during code execution and report it to the
+ monitor "MyClass.myMethod".
+ </p>
+ <p>
+ Other helper classes are provided for simplier use with commons frameworks. The
+ <code>org.apache.commons.monitoring.aop</code> package contains for example classes for use with
+ AOP frameworks to automagically instrument application components.
+ </p>
+ </section>
+
+ </body>
+
+</document>
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/instrumentation.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml (added)
+++ commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml Tue Feb 26 01:31:23 2008
@@ -0,0 +1,98 @@
+<?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>Monitoring listeners</title>
+ </properties>
+
+ <body>
+ <section name="Listeners">
+ <p>
+ In many case, the application itself can take advantage of the monitoring infrastructure either
+ to adapt it's behavior or to compute finest state to expose.
+ </p>
+ <p>
+ For example, the application can switch between two implementations of a component depending
+ on the business process load. A monitor that computes this load can be used by the application to
+ detect the overload and switch to a lightweight implementation. To implement this, the application
+ may use the monitor and programmatically (in a <code>if then else</code> block) select the
+ implementation to use. A more elegant way is to attach a Listener to the Gauge that monitors the load.
+ </p>
+ <p>
+ Repository, Monitors and StatValues support listeners. The <code>StatValue.Listener</code> interface
+ allows custom code to get notified when a value is updated. This is a nice way to detect some
+ value to increase abnormally and to adapt application behavior. The main advantage is that such
+ listener can be reused and don't require code intrusive changes in the monitored components.
+ </p>
+ <p>
+ <code>Monitor.Listener</code> allows the application to get evolved when a new StatValue is registered
+ to the monitor. The application can register new statValues (or <em>automagically</em> creates new ones
+ when requested) at any moment, and this listener can be used to get notified and pre-configure the
+ statValue before it gets used.
+ </p>
+ <p>
+ <code>Repository.Listener</code> can be used by the application to get notified any time a new monitor
+ instance is created, for example to register a Monitor.Listener !
+ </p>
+ </section>
+ <section name="ExecutionStack">
+ <p>
+ A listener can be used to detect that a business process exceed a maximum execution time. Just counting
+ such overload events is informative but don't give finest info about the context and how to improve
+ application scalability.
+ </p>
+ <p>
+ The StopWatches used to monitor execution can be registered in the <code>ExecutionStack</code> utility
+ class that maintain the set of active stopWatches for the current thread. It is recommended
+ to let the stopWatches register themselves by calling <code>DefaultStopWatch.setTraceExecution( true )</code>
+ at application startup, as all registered StopWatches MUST be removed before the thread stops or
+ proceed another task/request.
+ </p>
+ <p>
+ When the Listener on the business process detects some overload, it can look at the ExecutionStack
+ for the most time-consuming sub-process and log contextual information of what exactly happened.
+ This is really useful to detect bottlenecks and concurrency issues, as the application can
+ auto-diagnostic itself JUST when the bottlenecks occurred, with execution context available.
+ </p>
+ </section>
+ <section name="Secondary monitors">
+ <p>
+ Listeners are low-level hooks to observe the monitored state and the state exposed by the application.
+ A higher level is provided via the <code>org.apache.commons.monitoring.listeners.SecondaryRepository</code>.
+ Secondary repositories are used to observe the monitored state for a period of time, where Listeners
+ are used to observe individual monitoring events.
+ </p>
+ <p>
+ When a SecondaryRepository is created, it registers all the required listeners to maintain a set
+ or secondary monitors / counters / gauges in sync with the "primary" repository.
+ A secondary gauge will share the initial state of the primary gauge. A secondary counter will start
+ with initial value set to 0. The secondary repository can so be used to monitor the application during
+ a period as if monitoring had just been reseted. It can then be detached from the primary repository,
+ and will then not get notified anymore on application monitoring events.
+ </p>
+ <p>
+ Secondary repositories are the first-class component for building a time-based monitoring console. See
+ reporting section for more information on there usage for this use case.
+ </p>
+ </section>
+
+ </body>
+
+</document>
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/listeners.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Added: commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml (added)
+++ commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml Tue Feb 26 01:31:23 2008
@@ -0,0 +1,34 @@
+<?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>Repporting</title>
+ </properties>
+
+ <body>
+ <section name="Repporting">
+ <p>
+ TODO ...
+ </p>
+ </section>
+
+ </body>
+
+</document>
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/site/xdoc/reporting.xml
------------------------------------------------------------------------------
svn:mime-type = text/xml
Modified: commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/ExecutionStackTest.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/ExecutionStackTest.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/ExecutionStackTest.java (original)
+++ commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/ExecutionStackTest.java Tue Feb 26 01:31:23 2008
@@ -17,6 +17,8 @@
package org.apache.commons.monitoring;
+import org.apache.commons.monitoring.impl.DefaultStopWatch;
+
import junit.framework.TestCase;
/**
@@ -29,11 +31,11 @@
public void testExcution()
throws Exception
{
- StopWatch s1 = new StopWatch( null );
+ DefaultStopWatch s1 = new DefaultStopWatch( null );
ExecutionStack.push( s1 );
- StopWatch s2 = new StopWatch( null );
+ DefaultStopWatch s2 = new DefaultStopWatch( null );
ExecutionStack.push( s2 );
- StopWatch s3 = new StopWatch( null );
+ DefaultStopWatch s3 = new DefaultStopWatch( null );
ExecutionStack.push( s3 );
ExecutionStack.pause();
Modified: commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/StopWatchTest.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/StopWatchTest.java?rev=631142&r1=631141&r2=631142&view=diff
==============================================================================
--- commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/StopWatchTest.java (original)
+++ commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/StopWatchTest.java Tue Feb 26 01:31:23 2008
@@ -17,6 +17,8 @@
package org.apache.commons.monitoring;
+import org.apache.commons.monitoring.impl.DefaultStopWatch;
+
import junit.framework.TestCase;
/**
@@ -96,8 +98,9 @@
assertTrue( stopWatch.isStoped() );
}
+
private class MockTimeWatch
- extends StopWatch
+ extends DefaultStopWatch
{
public MockTimeWatch( Monitor monitor )
{
Added: commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java
URL: http://svn.apache.org/viewvc/commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java?rev=631142&view=auto
==============================================================================
--- commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java (added)
+++ commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java Tue Feb 26 01:31:23 2008
@@ -0,0 +1,73 @@
+/*
+ * 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.
+ */
+
+package org.apache.commons.monitoring.impl;
+
+import java.util.Collection;
+import java.util.Set;
+
+import org.apache.commons.monitoring.Monitor;
+import org.apache.commons.monitoring.Repository;
+
+import junit.framework.TestCase;
+
+/**
+ * @author <a href="mailto:nicolas@apache.org">Nicolas De Loof</a>
+ */
+public class DefaultRepositoryTest
+ extends TestCase
+{
+
+ public void testCategories()
+ throws Exception
+ {
+ Repository repository = new DefaultRepository();
+ Monitor foo = repository.getMonitor( "foo", "test" );
+ repository.getMonitor( "bar", "junit" );
+ repository.getMonitor( "just-a-name" );
+
+ Set<String> categories = repository.getCategories();
+ assertTrue( categories.contains( "test" ) );
+ assertTrue( categories.contains( "junit" ) );
+ assertTrue( categories.contains( null ) );
+ assertEquals( 3, categories.size() );
+
+ Collection<Monitor> monitors = repository.getMonitorsFromCategory( "test" );
+ assertEquals( 1, monitors.size() );
+ assertSame( foo, monitors.iterator().next() );
+ }
+
+ public void testSubsystem()
+ throws Exception
+ {
+ Repository repository = new DefaultRepository();
+ Monitor foo = repository.getMonitor( "foo", "test", "test" );
+ repository.getMonitor( "bar", "junit", "fake" );
+ repository.getMonitor( "just-a-name" );
+
+ Set<String> subsystems = repository.getSubSystems();
+ assertTrue( subsystems.contains( "test" ) );
+ assertTrue( subsystems.contains( "fake" ) );
+ assertTrue( subsystems.contains( null ) );
+ assertEquals( 3, subsystems.size() );
+
+ Collection<Monitor> monitors = repository.getMonitorsFromSubSystem( "test" );
+ assertEquals( 1, monitors.size() );
+ assertSame( foo, monitors.iterator().next() );
+ }
+
+}
Propchange: commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java
------------------------------------------------------------------------------
svn:keywords = Date Author Id Revision HeadURL
Propchange: commons/sandbox/monitoring/trunk/src/test/java/org/apache/commons/monitoring/impl/DefaultRepositoryTest.java
------------------------------------------------------------------------------
svn:mime-type = text/plain