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.
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!
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.
The recommended approach is to create stopwatch.properties 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 stopwatch.properties . It's value must be fully qualified class name. There are three engines provided with Stopwatch:
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()
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.
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 stopwatch.properties . 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:
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 stopwatch.properties . 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 stopwatch.properties . 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 stopwatch.properties .