commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nico...@apache.org
Subject 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...
Date Tue, 26 Feb 2008 09:31:36 GMT
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



Mime
View raw message