com.jamonapi

Interface MonitorFactoryInterface

All Superinterfaces:

Serializable

All Known Implementing Classes:

FactoryDisabled, FactoryEnabled

public interface MonitorFactoryInterface
extends Serializable

Interface used to create Monitors. It is implemented by both FactoryEnabled and FactoryDisabled which allows for enabling/disabling monitors at run time. A Factory is a design concept that is described in the Gang of 4's design patterns.

Note the factory will create a monitor if it doesn't exist and use an existing one if it does.

Field Summary

Fields

Modifier and Type	Field and Description
static String	VERSION

Method Summary

Modifier and Type	Method and Description
Monitor	add(MonKey key, double value) Used when you want to create your own key for the monitor.
Monitor	add(String label, String units, double value) Return a monitor with the given label and units.
Monitor	addException(Monitor mon, Throwable throwable) Add 2 exception monitors.
Monitor	addException(Throwable throwable) Track an exception except there is no other associated monitor to put the details in.
void	addListeners(List<JamonPropertiesLoader.JamonListenerProperty> listeners) Add listeners.
MonitorFactoryInterface	copy()
void	disableTotalKeySizeTracking()
void	enableActivityTracking(boolean enable) This determines if activity tracking in ranges is enabled.
void	enableGlobalActive(boolean enable)
void	enableTotalKeySizeTracking() This will keep track of the total size of of the keys used to store the monitors which can be useful in keeping track of memory used by JAMon.
boolean	exists(MonKey key) Return true if the monitor associated with the passed in key exists
boolean	exists(String label, String units) Return true if the monitor associated with the passed in label and units exists
MonitorComposite	getComposite(String units) Return the composite monitor associated with the passed unit.
Map	getMap() Get the backing map that holds the the Monitors.
int	getMaxNumMonitors() Return the max number of configured of monitors.
int	getMaxSqlSize() Return the size that sql statements can be before truncating them.
Monitor	getMonitor() Returns a non-TimeMonitor that won't update the jamon factory.
Monitor	getMonitor(MonKey key) Get the monitor associated with the passed in key.
Monitor	getMonitor(String label, String units) Get the monitor with the passed in label, and units.
int	getNumRows() Get the number of monitors in this factory
String[]	getRangeHeader() Return the header associated with range names
Object[][]	getRangeNames() Return an array of range names.
MonitorComposite	getRootMonitor() Get the root composite monitor that contains all monitors in this factory
Monitor	getTimeMonitor(MonKey key) Get the time monitor associated with the passed in key.
Monitor	getTimeMonitor(String label) Get the time monitor associated with the passed in label.
long	getTotalKeySize()
String	getVersion() Get JAMon's version.
boolean	isActivityTrackingEnabled()
boolean	isGlobalActiveEnabled()
boolean	isTotalKeySizeTrackingEnabled()
Iterator	iterator()
void	remove(MonKey key) Remove the monitor associated with the passed in key
void	remove(String label, String units) Remove the monitor associated with the passed in label and units
void	reset() Reset jamon stats for this factory.
void	setMap(Map map) Set the map that holds the monitors.
void	setMaxNumMonitors(int maxMonitors) Set the max number of monitors that can be tracked.
void	setMaxSqlSize(int size) Set the maximum size for a sql statement.
void	setRangeDefault(String key, RangeHolder rangeHolder) Associate a Range mapping to any monitor that has a unit/key name that matches what is passed to key
Monitor	start() Returns a TimeMonitor that won't update the jamon factory.
Monitor	start(MonKey key) Start using the passed in key.
Monitor	start(String label) Return a time monitor (the units are implied and are ms.
Monitor	startNano(MonKey key) Provide your own key to a nanosecond timer
Monitor	startNano(String label) Create a timing monitor that uses nanosecond granularity (1,000,000 ns.=1 ms.)
Monitor	startPrimary(MonKey key) Start a monitor with the specified key and mark it as primary
Monitor	startPrimary(String label) Start a time monitor and mark it as primary

Field Detail

VERSION

static final String VERSION

See Also:

Constant Field Values

Method Detail

add

Monitor add(String label,
            String units,
            double value)

Return a monitor with the given label and units. Note label has an effect on what range is used. If no range is associated with units then it will use the null range (i.e. no range)

Sample Call: factory.add("com.fdsapi.MyException", "error", 1);

add

Monitor add(MonKey key,
            double value)

Used when you want to create your own key for the monitor. This works similarly to a group by clause where the key is any columns used after the group by clause.

start

Monitor start(String label)

Return a time monitor (the units are implied and are ms. Note activity stats are incremented

start

Monitor start(MonKey key)

Start using the passed in key. Note activity stats are incremented

start

Monitor start()

Returns a TimeMonitor that won't update the jamon factory.

startNano

Monitor startNano(String label)

Create a timing monitor that uses nanosecond granularity (1,000,000 ns.=1 ms.)

startNano

Monitor startNano(MonKey key)

Provide your own key to a nanosecond timer

getMonitor

Monitor getMonitor()

Returns a non-TimeMonitor that won't update the jamon factory.

startPrimary

Monitor startPrimary(String label)

Start a time monitor and mark it as primary

startPrimary

Monitor startPrimary(MonKey key)

Start a monitor with the specified key and mark it as primary

getMonitor

Monitor getMonitor(MonKey key)

Get the monitor associated with the passed in key. It will be created if it doesn't exist

getMonitor

Monitor getMonitor(String label,
                   String units)

Get the monitor with the passed in label, and units. It will be created if it doesn't exist

getTimeMonitor

Monitor getTimeMonitor(String label)

Get the time monitor associated with the passed in label. It will be created if it doesn't exist. The units are in ms.

getTimeMonitor

Monitor getTimeMonitor(MonKey key)

Get the time monitor associated with the passed in key. It will be created if it doesn't exist. The units are in ms.

addException

Monitor addException(Monitor mon,
                     Throwable throwable)

Add 2 exception monitors. One for the specific exception and the other a catchall monitor for all exceptions. It will also put the stacktrace in the details for both of these monitors as well as for the monitor being passed in which would typically be the code associated with throwing the exception. Passing in a null for mon is acceptable.

Parameters:

mon - optional monitor where we want to store the stack trace.

throwable - exception that we want to create a monitor for

Returns:

Returns only the monitor associated with the specific exception even though 2 monitors are created.

addException

Monitor addException(Throwable throwable)

Track an exception except there is no other associated monitor to put the details in. Equivalent to addException(null, throwable);

Parameters:

throwable - exception to create a monitor for.

Returns:

Returns only the monitor associated with the specific exception even though 2 monitors are created.

remove

void remove(String label,
            String units)

Remove the monitor associated with the passed in label and units

remove

void remove(MonKey key)

Remove the monitor associated with the passed in key

exists

boolean exists(String label,
               String units)

Return true if the monitor associated with the passed in label and units exists

exists

boolean exists(MonKey key)

Return true if the monitor associated with the passed in key exists

setRangeDefault

void setRangeDefault(String key,
                     RangeHolder rangeHolder)

Associate a Range mapping to any monitor that has a unit/key name that matches what is passed to key

getRangeHeader

String[] getRangeHeader()

Return the header associated with range names

getRangeNames

Object[][] getRangeNames()

Return an array of range names. This is dynamic based on what was passed to setRangeDefault

getNumRows

int getNumRows()

Get the number of monitors in this factory

getRootMonitor

MonitorComposite getRootMonitor()

Get the root composite monitor that contains all monitors in this factory

getComposite

MonitorComposite getComposite(String units)

Return the composite monitor associated with the passed unit. Note this method changed from jamon 1.0. Previously it took a regular expression that was matched on the label column and now it looks for any monitors that have the given range/unit key

getVersion

String getVersion()

Get JAMon's version. Example: 2.0

setMap

void setMap(Map map)

Set the map that holds the monitors. This could be used to aid jamon performance by passing in a high performance Thread safe map such as open source projects and jdk 1.5 have

getMap

Map getMap()

Get the backing map that holds the the Monitors. Keys=MonKeys, values=Monitor

reset

void reset()

Reset jamon stats for this factory. Like recreating the factory

isGlobalActiveEnabled

boolean isGlobalActiveEnabled()

enableGlobalActive

void enableGlobalActive(boolean enable)

enableActivityTracking

void enableActivityTracking(boolean enable)

This determines if activity tracking in ranges is enabled. Activity tracking allows you to see how performance tracks to the number of activities (monitors) that are running. For example it can let you see how your web site scales by seeing how performance correlates when 10 simultaneous pages are being invoked, or 20, 30, 40, 50 etc. Disabling or enabling will affect current monitors as well as any others that are subsequently created. One problem at this point is that any in flight monitors can be disabled/enabled while they are in flight leading to results that may be off. For this reason it is best to enable/disable before any monitors have been created or when you know none are running. A future enhancement may be to delay this capability until no monitors are running. Note disabling global active turns off a subset of this capability.

Parameters:

enable -

isActivityTrackingEnabled

boolean isActivityTrackingEnabled()

iterator

Iterator iterator()

setMaxNumMonitors

void setMaxNumMonitors(int maxMonitors)

Set the max number of monitors that can be tracked. The default is unlimited. When this value is set the number of jamon monitors is capped at this number and does not grow unbounded. Once this threshold has been reached any additional are not stored in the Map and no warning is given. If the threshold is set, but the monitors currently exceed this number the current monitors remain, however no new ones will be added.

Parameters:

maxMonitors - If positive then this is the max number of monitors that can be stored. 0 or negative means monitors can grow unbounded.

getMaxNumMonitors

int getMaxNumMonitors()

Return the max number of configured of monitors.

enableTotalKeySizeTracking

void enableTotalKeySizeTracking()

This will keep track of the total size of of the keys used to store the monitors which can be useful in keeping track of memory used by JAMon. To have accureate measurements enableTotalKeySizeTracking() must be called before any monitors are stored.

disableTotalKeySizeTracking

void disableTotalKeySizeTracking()

isTotalKeySizeTrackingEnabled

boolean isTotalKeySizeTrackingEnabled()

getTotalKeySize

long getTotalKeySize()

setMaxSqlSize

void setMaxSqlSize(int size)

Set the maximum size for a sql statement. Sql bigger than this will be truncated before a JAMon label is created via the JAMon JDBC proxy driver. This is useful to limit the size in memory that jamon occupies due to really long sql statements. For backwards compatibility The default is to not limit the statement size.

Parameters:

size -

getMaxSqlSize

int getMaxSqlSize()

Return the size that sql statements can be before truncating them. This will limit the size of JAMon labels for sql statements

Returns:

the max size that the sql is allowed to be before being truncated.

addListeners

void addListeners(List<JamonPropertiesLoader.JamonListenerProperty> listeners)

Add listeners. These can be read from a properties file (@see JamonPropertiesLoader). It should be done as part of application startup. One use is to ensure that exceptions details are tracked at application startup. The @see JamonServletContextListener automatically reads the values from the properties file if there are any of them.

Since:

2.79

copy

MonitorFactoryInterface copy()

Returns:

a deep copy of this object

Since:

2.79