Quick introduction

The Monitoring class is a convenience utility class to make application instrumentation as simple as possible. To monitor application performance, simply do :

        public void myMethodToGetMonitored()
        {
            StopWatch stopWatch = Monitoring.start( "MyClass.myMethod" );
            try
            {
                // Do something that takes time and requires monitoring
            }
            finally
            {
                stopWatch.stop();
            }
        }
        

The StopWatch class will compute the time elapsed during code execution and report it to the monitor "MyClass.myMethod".

Instrumentation

A Monitor defines a control point in the application. It can be associated to a resource, a code fragment or anything relevant for the application. The monitor is unique and retrieved from a Repository . It is identified by a name, a category (technical description of the application component) and a subsystem (functional description). In the previous code sample, only a name was set as category and subsystem are optional. We recommend to use them to create monitors as this is a convenient and powerfull way to group and sort monitors and associated statistics.

The monitor maintains a set of StatValues, that can be either Counters or Gauges .

• A Counter will get incremented any time the application does its work and expose the result to the monitoring backbone : byte received, lines processed...
• A Gauge allows the application to expose how a resource is used : active connections...

Each StatValue is identified by a ROLE in the monitor. Default roles are defined for PERFORMANCES and CONCURRENCY (threads running same code), and you can register Counters/Gauges for custom roles to monitor anything that is relevant for your application (bytes processed, message payload, account balance ...) :

            Monitor monitor = repository.getMonitor( "SoapEndpoint.process", "soap" );

            // Process a SOAP message
            monitor.getCounter( "bytes" ).add( SOAPMessage.getSize() );
        

Commons Monitoring provides Helpers to instrument application, for example to monitor web application Request or JDBC operations, so that in many case you don't have to know commons-monitoring API to get basic instrumentation on your application.

Repporting

You can retrieve statistical datas from your monitors and StatValues to build reports. You can programatically acces the repository and iterate on monitors to build a custom output, or rely on Commons Monitoring provided Renderers that support common output formats (XML, TXT, JSON).

When used in a webapp, Commons Monitoring provides a simple web UI. TODO...