Stopwatch configuration

Enable/Disable Stopwatch

Stopwatch is by default disabled. This means that all Stopwatch API calls are skipped and no measurements take place. The reason for that is to be able to disable Stopwatch and reduce possible overload in production environment.

Before using Stopwatch it needs to be enabled. This can be done in a number of ways.

  • Call Stopwatch.setActive(true)

    Stopwatch can be enabled at any time by calling Stopwatch.setActive(true) . While useful is some cases this is definitively NOT the recommended approach. Use this with care and remember to disable it once you are done!

  • Pass -Dcom.commsen.stopwatch.activeOnStart=true JVM parameter

    This is much better approach to activate Stopwatch. It may be particularly useful for enabling/disabling Stopwatch in unit tests or while running in non-production environment.

  • Set activeOnStart=true in

    The recommended approach is to create file on CLASSPATH and set activeOnStart=true . This basically does the same thing as the one above. The only difference is that this there is no need to play with JVM's parameters which may be a problem if it is not under your control.


Stopwatch was meant to be kind of general measurement tool into which different engines can be plugged. Engines may differ in what or how they measure. Stopwatch can be told what engine to use by setting engine property in . It's value must be fully qualified class name. There are three engines provided with Stopwatch:

  • com.commsen.stopwatch.engines.DefaultStopwatchEngine

    This is the default engine. It simply measures how long it takes to execute given code block. Reports generated by this engine provide following methods: getMinTime() , getMaxTime() , getAverageTime() , getAverageTime()

  • com.commsen.stopwatch.engines.MemoryStopwatchEngine

    MemoryStopwatchEngine extends DefaultStopwatchEngine and attempts to measure memory usage. Reports generated by this engine in addition to default ones provide methods: getMinMemory() , getMaxMemory() , getAverageMemory()

    IMPORTANT NOTE : the engine simply remembers the amount of memory used by JVM at the time of starting the measurement and compares it to the amount of memory used by JVM at the time of completing the measurement. This of course may have nothing to do with truth if some other threads are running and consuming memory or for example GC is started while measuring. The results may vary from "almost correct" in the case of single threaded application to "pure fiction" in case of heavily loaded, multi-threaded application.

  • com.commsen.stopwatch.engines.LoadStopwatchEngine

    LoadStopwatchEngine is now deprecated and will be removed in future releases. Since version 0.3 there are new getLoad () methods provided.


For storing collected data Stopwatch uses a storage. As far as Stopwatch is concern a storage is simply an object that is able to persist data collected by the engine. Stopwatch can be told what storage to use by setting storage property in . It's value must be fully qualified class name. IMPORTANT NOTE : The storage must be compatible with currently selected engine. By default Stopwatch allows you to chose from:

  • com.commsen.stopwatch.storages.DefaultHSQLInMemoryStorage - This is the default storage for DefaultStopwatchEngine . Provides interface for storing basic information collected by DefaultStopwatchEngine . It uses in-memory HSQL database!
  • com.commsen.stopwatch.storages.DefaultHSQLStorage - The same as above but uses HSQL server instead. Connection properties should be provided in
  • com.commsen.stopwatch.storages.MemoryHSQLInMemoryStorage - This is the default storage for MemoryStopwatchEngine . It extends DefaultHSQLInMemoryStorage and is capable of storing memory usage related data. It uses in-memory HSQL database!
  • com.commsen.stopwatch.storages.MemoryHSQLStorage - The same as above but uses HSQL server instead. Connection properties should be provided in

Persistence modes

Measuring given code block requires some data to be collected at the beginning and some at the end of that block. When it comes to persisting the data the question is "when and how it can be persisted?". Can it be stored right after collection or Stopwatch should wait until measuring process is done? Should it be done in the same thread the measured block is running or a new one needs to be created?

Stopwatch can be told what persistence strategy to use by setting persistenceMode property in . You can choose from three persistence modes :


    Storage manager will insert record into database when start(group, label) method is called and update it when stop(id) method is called. NOTE: in this case the time taken to insert the record into database is added to measurements.


    same as NORMAL but storage manager runs in separate thread, thus resulting in more correct measurements. NOTE : in this case getReport(...) methods may return incomplete data (or even NULL ) since storage manager may have not managed to store all the data.


    Storage manager keeps in memory data gathered on start(group, label) and stores all together when stop(id) is called. This is the DEFAULT value .


Stopwatch is easy to control remotely over JMX. Managed bean provide appropriate methods for enabling/disabling Stopwatch as well as generating reports. By default JMX is disabled. To enable it set jmxManaged=true in . By default a new MBean server will be created and registered. If there is already running MBean server that Stopwatch should connect to, it can by told to do so by setting MBeanServer=My JMX server in .