com.commsen.stopwatch
Class Stopwatch

java.lang.Object
  com.commsen.stopwatch.Stopwatch

public class Stopwatch
extends java.lang.Object

Stopwatch allows you to measure performance of any given piece of code. It's basic usage is as follows:

 .....
 long swId = Stopwatch.start("group", "label");
 // some code to be measured
 Stopwatch.stop(swId);
 ...
 

since version 0.4 there is also Meter object

 .....
 Meter meter = Stopwatch.startMeter("group", "label");
 // some code to be measured
 meter.stop();
 ...
 

To skip already started mensuration (for example if an Exception is thrown) something similar to following code may be used:

 .....
 long swId = Stopwatch.start("group", "label");
 try {
    // some code to be measured
 } catch (Exception) { 
    Stopwatch.skip(swId);
 } finally {
    Stopwatch.stop(swId);
 }
 ...
 

or alternatively (since version 0.4) use Meter object

 .....
 Meter meter = Stopwatch.startMeter("group", "label");
 try {
    // some code to be measured
 } catch (Exception) { 
    meter.cancel();
 } finally {
    meter.stop();
 }
 ...
 

By default Stopwatch is not active! It means all calls to start(String, String), skip(long) and stop(long) methods are simply ignored. To activate Stopwatch do one of the following:

• explicitly call Stopwatch.setActive(true)
• pass -Dcom.commsen.stopwatch.activeOnStart=true JVM parameter
• create "stopwatch.properties" file on classpath and set activeOnStart=true

Stopwatch can also be activated/deactivated at runtime via JMX, RMI, etc.

Author:

Milen Dyankov

Field Summary

static java.lang.String	DEFAULT_ENGINE
static java.lang.String	DEFAULT_ENGINE_PROPERTIES
static int	DEFAULT_MODE
static java.lang.String	DEFAULT_STORAGE
static java.lang.String	DEFAULT_STORAGE_PROPERTIES
static java.lang.String	PROPERTY_ACTIVE
static java.lang.String	PROPERTY_DEBUG
static java.lang.String	PROPERTY_ENGINE
static java.lang.String	PROPERTY_ENGINE_PROPERTIES
static java.lang.String	PROPERTY_JMX_MANAGED
static java.lang.String	PROPERTY_MBEAN_SERVER_NAME
static java.lang.String	PROPERTY_MODE
static java.lang.String	PROPERTY_STORAGE
static java.lang.String	PROPERTY_STORAGE_PROPERTIES
static java.lang.String	SYSTEM_PROPERTIES_PREFIX

Constructor Summary

Stopwatch()

Method Summary

static Report[]	getAllByGroupReports()
static Report[]	getAllByGroupReports(ReportComparator comparator)
static Report[]	getAllByLabelReports()
static Report[]	getAllByLabelReports(ReportComparator comparator)
static Report[]	getAllReports() Generates an array of reports which contains exactly 1 element for each combination of group and label If there is no enough data to produce reports, this method returns null
static Report[]	getAllReports(ReportComparator comparator) Generates an array of reports which contains exactly 1 element for each combination of group and label If there is no enough data to produce reports, this method returns null
static java.lang.String	getEngineClass()
static long[]	getGroupLoad(java.lang.String group, int periodField, int numberOfPeriods) Returns information of how many instances of any measured code in group group ware running for the last numberOfPeriods periods.
static Report[]	getGroupReports(java.lang.String group) Generates an array of reports which contains exactly 1 element for each group If there is no enough data to produce the report, this method returns null
static Report[]	getGroupReports(java.lang.String group, ReportComparator comparator) Generates an array of reports which contains exactly 1 element for each group If there is no enough data to produce the report, this method returns null
static long[]	getLabelLoad(java.lang.String label, int periodField, int numberOfPeriods) Returns information of how many instances of any measured code labeled label ware running for the last numberOfPeriods periods.
static Report[]	getLabelReports(java.lang.String label) Generates an array of reports which contains exactly 1 element for each label If there is no enough data to produce the report, this method returns null
static Report[]	getLabelReports(java.lang.String label, ReportComparator comparator) Generates an array of reports which contains exactly 1 element for each label If there is no enough data to produce the report, this method returns null
static long[]	getLoad(int periodField, int numberOfPeriods) Returns information of how many instances of any measured code ware running for the last numberOfPeriods periods.
static long[]	getLoad(java.lang.String group, java.lang.String label, int periodField, int numberOfPeriods) Returns information of how many instances of any measured code in group group labeled label ware running for the last numberOfPeriods periods.
static java.lang.String	getPersistenceMode()
static java.lang.String	getProperty(java.lang.String key, java.lang.String defaultValue) Tries to get the value of property key
static Report	getSingleReport(java.lang.String group, java.lang.String label) Generates a single report for provided group and label If there is no enough data to produce the report, this method returns null
static java.lang.String	getStorageClass()
static boolean	isActive() Called to check if Stopwatch is active.
static boolean	isDebugEnabled() Called to check if Stopwatch should produce debug information.
static boolean	isInitialised()
static void	reset()
static void	setActive(boolean active) This method changes stopwatch's status Should be used to activate/deactivate Stopwatch at runtime.
static void	setDebugEnabled(boolean debugEnabled) Used to disable/enable Stopwatch's debug information.
static void	skip(long id) Skip measurement identified by id.
static long	start(java.lang.String group, java.lang.String label) Starts new measurement.
static Meter	startMeter(java.lang.String group, java.lang.String label) Starts new measurement and provides a Meter which can be later on stopped (Meter.stop()) or canceled (Meter.cancel()).
static void	stop(long id) Stop measurement identified by id.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SYSTEM_PROPERTIES_PREFIX

public static final java.lang.String SYSTEM_PROPERTIES_PREFIX

See Also:

Constant Field Values

PROPERTY_ACTIVE

public static final java.lang.String PROPERTY_ACTIVE

See Also:

Constant Field Values

PROPERTY_DEBUG

public static final java.lang.String PROPERTY_DEBUG

See Also:

Constant Field Values

PROPERTY_ENGINE

public static final java.lang.String PROPERTY_ENGINE

See Also:

Constant Field Values

PROPERTY_ENGINE_PROPERTIES

public static final java.lang.String PROPERTY_ENGINE_PROPERTIES

See Also:

Constant Field Values

PROPERTY_STORAGE

public static final java.lang.String PROPERTY_STORAGE

See Also:

Constant Field Values

PROPERTY_STORAGE_PROPERTIES

public static final java.lang.String PROPERTY_STORAGE_PROPERTIES

See Also:

Constant Field Values

PROPERTY_MODE

public static final java.lang.String PROPERTY_MODE

See Also:

Constant Field Values

PROPERTY_JMX_MANAGED

public static final java.lang.String PROPERTY_JMX_MANAGED

See Also:

Constant Field Values

PROPERTY_MBEAN_SERVER_NAME

public static final java.lang.String PROPERTY_MBEAN_SERVER_NAME

See Also:

Constant Field Values

DEFAULT_ENGINE

public static final java.lang.String DEFAULT_ENGINE

DEFAULT_ENGINE_PROPERTIES

public static final java.lang.String DEFAULT_ENGINE_PROPERTIES

See Also:

Constant Field Values

DEFAULT_STORAGE

public static final java.lang.String DEFAULT_STORAGE

DEFAULT_STORAGE_PROPERTIES

public static final java.lang.String DEFAULT_STORAGE_PROPERTIES

See Also:

Constant Field Values

DEFAULT_MODE

public static final int DEFAULT_MODE

See Also:

Constant Field Values

Constructor Detail

Stopwatch

public Stopwatch()

Method Detail

start

public static long start(java.lang.String group,
                         java.lang.String label)

Starts new measurement. This method will do nothing and simply return a negative long if Stopwatch is not active.

Parameters:

group - the name of the group this measurement should be placed in

label - how this measurement should be labeled

Returns:

Unique ID representing current measurement.

startMeter

public static Meter startMeter(java.lang.String group,
                               java.lang.String label)

Starts new measurement and provides a Meter which can be later on stopped (Meter.stop()) or canceled (Meter.cancel()).

Parameters:

group - the name of the group this measurement should be placed in

label - how this measurement should be labeled

Returns:

a Meter which can be later on stopped (Meter.stop()) or canceled (Meter.cancel())

Since:

0.4

stop

public static void stop(long id)

Stop measurement identified by id. This method will do nothing if Stopwatch is not active or measurement has been skipped already.

Parameters:

id - which measurement to stop

skip

public static void skip(long id)

Skip measurement identified by id. Method should be called if for some reason current measurement should be skipped. Default stopwatch engine will delete any information related to this id but other engines may behave differently (for example to provide a "skipped measurements" report). This method will do nothing if Stopwatch is not active or measurement has been stopped already.

Parameters:

id - which measurement to stop

getAllReports

public static Report[] getAllReports()

Generates an array of reports which contains exactly 1 element for each combination of group and label If there is no enough data to produce reports, this method returns null

Returns:

array of reports of null.

getAllReports

public static Report[] getAllReports(ReportComparator comparator)

Generates an array of reports which contains exactly 1 element for each combination of group and label If there is no enough data to produce reports, this method returns null

Returns:

array of reports of null.

getAllByGroupReports

public static Report[] getAllByGroupReports()

Returns:

getAllByGroupReports

public static Report[] getAllByGroupReports(ReportComparator comparator)

Returns:

getAllByLabelReports

public static Report[] getAllByLabelReports()

Returns:

getAllByLabelReports

public static Report[] getAllByLabelReports(ReportComparator comparator)

Returns:

getGroupReports

public static Report[] getGroupReports(java.lang.String group)

Generates an array of reports which contains exactly 1 element for each group If there is no enough data to produce the report, this method returns null

Parameters:

group - the group for which report should be generated

Returns:

array of reports of null.

getGroupReports

public static Report[] getGroupReports(java.lang.String group,
                                       ReportComparator comparator)

Generates an array of reports which contains exactly 1 element for each group If there is no enough data to produce the report, this method returns null

Parameters:

group - the group for which report should be generated

Returns:

array of reports of null.

getLabelReports

public static Report[] getLabelReports(java.lang.String label)

Generates an array of reports which contains exactly 1 element for each label If there is no enough data to produce the report, this method returns null

Parameters:

label - the label for which report should be generated

Returns:

array of reports or null.

getLabelReports

public static Report[] getLabelReports(java.lang.String label,
                                       ReportComparator comparator)

Generates an array of reports which contains exactly 1 element for each label If there is no enough data to produce the report, this method returns null

Parameters:

label - the label for which report should be generated

Returns:

array of reports or null.

getSingleReport

public static Report getSingleReport(java.lang.String group,
                                     java.lang.String label)

Generates a single report for provided group and label If there is no enough data to produce the report, this method returns null

Parameters:

group - the group for which report should be generated

label - the label for which report should be generated

Returns:

single report for provided group and label of null.

getLoad

public static long[] getLoad(int periodField,
                             int numberOfPeriods)

Returns information of how many instances of any measured code ware running for the last numberOfPeriods periods. Period length is defined by periodField which can be one of Calendar.FIELD_NAME

For example to see how many peaces of measured code were running per minute for the last 30 minutes, one could use:

                long[] load = Stopwatch.getLoad(Calendar.MINUTE, 30);
 

In this case load[0] will contain the number of code instances running 30 minutes ago and load[29] number of code instances running in the last minute.

Parameters:

periodField - can be one of Calendar.FIELD_NAME

numberOfPeriods - number of periods

Returns:

array of length numberOfPeriods where every element represents the load for given pariod.

getGroupLoad

public static long[] getGroupLoad(java.lang.String group,
                                  int periodField,
                                  int numberOfPeriods)

Returns information of how many instances of any measured code in group group ware running for the last numberOfPeriods periods. Period length is defined by periodField which can be one of Calendar.FIELD_NAME

For example to see how many peaces of measured code in group g1 were running per day for the last 10 days, one could use:

                long[] load = Stopwatch.getLoad(Calendar.DAY_OF_MONTH, 10);
 

In this case load[0] will contain the number of code instances running 10 days ago and load[9] number of code instances running today.

Parameters:

group - the group for which report should be generated

periodField - can be one of Calendar.FIELD_NAME

numberOfPeriods - number of periods

Returns:

array of length numberOfPeriods where every element represents the load for given period.

getLabelLoad

public static long[] getLabelLoad(java.lang.String label,
                                  int periodField,
                                  int numberOfPeriods)

Returns information of how many instances of any measured code labeled label ware running for the last numberOfPeriods periods. Period length is defined by periodField which can be one of Calendar.FIELD_NAME

For example to see how many peaces of measured code labeled l1 were running per second for the last 15 seconds, one could use:

                long[] load = Stopwatch.getLoad(Calendar.SECOND, 15);
 

In this case load[0] will contain the number of code instances running 15 seconds ago and load[14] number of code instances running in the last second.

Parameters:

label - the label for which report should be generated

periodField - can be one of Calendar.FIELD_NAME

numberOfPeriods - number of periods

Returns:

array of length numberOfPeriods where every element represents the load for given period.

getLoad

public static long[] getLoad(java.lang.String group,
                             java.lang.String label,
                             int periodField,
                             int numberOfPeriods)

Returns information of how many instances of any measured code in group group labeled label ware running for the last numberOfPeriods periods. Period length is defined by periodField which can be one of Calendar.FIELD_NAME

For example to see how many peaces of measured code in group g1 labeled l1 were running per second for the last 3 weeks, one could use:

                long[] load = Stopwatch.getLoad(Calendar.WEEK_OF_YEAR, 3);
 

In this case load[0] will contain the number of code instances running 3 weeks ago and load[2] number of code instances running in the last week.

Parameters:

group - the group for which report should be generated

label - the label for which report should be generated

periodField - can be one of Calendar.FIELD_NAME

numberOfPeriods - number of periods

Returns:

array of length numberOfPeriods where every element represents the load for given period.

reset

public static void reset()

isActive

public static boolean isActive()

Called to check if Stopwatch is active. When this method returns false all calls to start(String, String) and stop(long) are ignored.

Returns:

Returns the Stopwatch's status.

setActive

public static void setActive(boolean active)

This method changes stopwatch's status Should be used to activate/deactivate Stopwatch at runtime.

Parameters:

active - the Stopwatch's status.

isDebugEnabled

public static boolean isDebugEnabled()

Called to check if Stopwatch should produce debug information.

Returns:

Returns the true or false

See Also:

setDebugEnabled(boolean)

setDebugEnabled

public static void setDebugEnabled(boolean debugEnabled)

Used to disable/enable Stopwatch's debug information. The reason for this method to exist is to be able to minimize the performance impact Stopwatch may have on the measured application. Generating debug info consumes additional CPU units, which may become a problem if Stopwatch is heavily used. Setting this to false (is is false by default) will cause no debug info being generated by Stopwatch even when log4j's level is set to DEBUG.

Parameters:

debugEnabled - should debug information be generated

getProperty

public static java.lang.String getProperty(java.lang.String key,
                                           java.lang.String defaultValue)

Tries to get the value of property key

Parameters:

key -

defaultValue -

Returns:

the value of property key of defaultValue if property not found.

getEngineClass

public static java.lang.String getEngineClass()

getStorageClass

public static java.lang.String getStorageClass()

getPersistenceMode

public static java.lang.String getPersistenceMode()

isInitialised

public static boolean isInitialised()

Returns:

the initialised