de.is24.util.monitoring
Class InApplicationMonitor

java.lang.Object
  de.is24.util.monitoring.InApplicationMonitor

public final class InApplicationMonitor
extends Object

This is the central class of appmon4j.
appmon4j is a lightweight, easy to use in application monitoring system allowing measurements of "real traffic" performance values in high throughput java applications.

This class is an "old school" singleton, which is accessed by using the static getInstance() method.

Author:

OSchmitz

Field Summary

private CorePlugin	corePlugin
private static InApplicationMonitor	INSTANCE
private static Pattern	KEY_ESCAPE_PATTERN
private static org.apache.log4j.Logger	LOGGER
private boolean	monitorActive
private CopyOnWriteArrayList<MonitorPlugin>	plugins

Constructor Summary

private

InApplicationMonitor()

Method Summary

void	activate()
void	addHighRateTimerMeasurement(String name, long timing) Add a timer measurement for a often occuring event with given name.
void	addHistorizable(Historizable historizable) add a Historizable instance to the list identified by historizable.getName()
void	addReportableObserver(ReportableObserver reportableObserver) Deprecated. use corePlugin directly, will be removed from InApplicationMonitor
void	addSingleEventTimerMeasurement(String name, long timing) Add a timer measurement for a rarely occuring event with given name.
void	addTimerMeasurement(String name, long timing) Add a timer measurement for the given name.
void	addTimerMeasurement(String name, long begin, long end) Add a timer measurement for the given name.
void	deactivate()
private String	escape(String name) helper function that escapes a reportable's name so that it is JMX-compatible
CorePlugin	getCorePlugin()
static InApplicationMonitor	getInstance() Delivers the Singleton instance of InApplicationMonitor.
int	getMaxHistoryEntriesToKeep() Deprecated. use corePlugin directly, will be removed from InApplicationMonitor
List<String>	getRegisteredPluginKeys()
void	incrementCounter(String name) Increment the named Counter by one.
void	incrementCounter(String name, int increment) Increase the specified counter by a variable amount.
void	incrementHighRateCounter(String name) Increment the named Counter by one.
void	initializeCounter(String name) If you want to ensure existance of a counter, for example you want to prevent spelling errors in an operational monitoring configuration, you may initialize a counter using this method.
void	initializeTimerMeasurement(String name) If you want to ensure existence of a timer, for example you want to prevent spelling errors in an operational monitoring configuration, you may initialize a timer using this method.
boolean	isMonitorActive() If true, monitoring is active.
void	registerPlugin(MonitorPlugin plugin) Register a plugin to able to hook into monitoring with your own monitor.
void	registerStateValue(StateValueProvider stateValueProvider) Add a state value provider to this appmon4j instance.
void	registerVersion(String name, String version) This method was intended to register module names with their current version identifier.
void	removeAllPlugins()
void	removeReportableObserver(ReportableObserver reportableObserver) Deprecated. use corePlugin directly, will be removed from InApplicationMonitor
void	reportInto(ReportVisitor reportVisitor) Deprecated. use corePlugin directly, will be removed from InApplicationMonitor
void	setMaxHistoryEntriesToKeep(int aMaxHistoryEntriesToKeep) Deprecated. use corePlugin directly, will be removed from InApplicationMonitor

Methods inherited from class java.lang.Object

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

Field Detail

LOGGER

private static final org.apache.log4j.Logger LOGGER

KEY_ESCAPE_PATTERN

private static final Pattern KEY_ESCAPE_PATTERN

INSTANCE

private static final InApplicationMonitor INSTANCE

monitorActive

private volatile boolean monitorActive

corePlugin

private CorePlugin corePlugin

plugins

private final CopyOnWriteArrayList<MonitorPlugin> plugins

Constructor Detail

InApplicationMonitor

private InApplicationMonitor()

Method Detail

getInstance

public static InApplicationMonitor getInstance()

Delivers the Singleton instance of InApplicationMonitor.

Returns:

InApplicationMonitor Singleton

escape

private String escape(String name)

helper function that escapes a reportable's name so that it is JMX-compatible

Parameters:

name - the original name of the reportable

Returns:

the espaced name TODO OSchmi I think escaping should happen on the read side (where the problem is), not everytime on writing. Or we should have a defined contract on allowed chars in keys and enfocr it on the entry side. Due to performance and responsibility reasons.

activate

public void activate()

See Also:

isMonitorActive()

deactivate

public void deactivate()

See Also:

isMonitorActive()

isMonitorActive

public boolean isMonitorActive()

If true, monitoring is active. If false incrementCounter and addTimer calls will return without doing anything (thus not synchronizing on any resource). Initialize calls will be processed however. registerStateValue, registerVersion and add Historizable will be processed, too.

Returns:

true if the monitor is currently active, false if not

getMaxHistoryEntriesToKeep

@Deprecated
public int getMaxHistoryEntriesToKeep()

Deprecated. use corePlugin directly, will be removed from InApplicationMonitor

Returns:

Number of entries to keep for each Historizable list.

setMaxHistoryEntriesToKeep

@Deprecated
public void setMaxHistoryEntriesToKeep(int aMaxHistoryEntriesToKeep)

Deprecated. use corePlugin directly, will be removed from InApplicationMonitor

Set the Number of entries to keep for each Historizable list. Default is 5.

Parameters:

aMaxHistoryEntriesToKeep - Number of entries to keep

addReportableObserver

public void addReportableObserver(ReportableObserver reportableObserver)

Deprecated. use corePlugin directly, will be removed from InApplicationMonitor

adds a new ReportableObserver that wants to be notified about new Reportables that are registered on the InApplicationMonitor

Parameters:

reportableObserver - the class that wants to be notified

removeReportableObserver

public void removeReportableObserver(ReportableObserver reportableObserver)

Deprecated. use corePlugin directly, will be removed from InApplicationMonitor

Allow disconnection of observers, mainly for testing

Parameters:

reportableObserver -

reportInto

public void reportInto(ReportVisitor reportVisitor)

Deprecated. use corePlugin directly, will be removed from InApplicationMonitor

Implements the InApplicationMonitor side of the Visitor pattern. Iterates through all registered Reportable instances and calls the corresponding method on the ReportVisitor implementation.

Parameters:

reportVisitor - The ReportVisitor instance that shall be visited by all regieteres Reportable instances.

incrementCounter

public void incrementCounter(String name)

Increment the named Counter by one.

Parameters:

name - name of the Counter to increment

incrementHighRateCounter

public void incrementHighRateCounter(String name)

Increment the named Counter by one. Using this method instead of incrementCounter is a hint to some plugins that this is an event that may happen very often. Plugins may use sampling to to limit load or network traffic.

Parameters:

name - name of the Counter to increment

incrementCounter

public void incrementCounter(String name,
                             int increment)

Increase the specified counter by a variable amount.

Parameters:

name - the name of the Counter to increase

increment - the added to add

initializeCounter

public void initializeCounter(String name)

If you want to ensure existance of a counter, for example you want to prevent spelling errors in an operational monitoring configuration, you may initialize a counter using this method. The plugins will decide how to handle this initialization.

Parameters:

name - the name of the counter to be initialized

addTimerMeasurement

public void addTimerMeasurement(String name,
                                long timing)

Add a timer measurement for the given name. Timers allow adding timer measurements, implicitly incrementing the count Timers count and measure timed events. The application decides which unit to use for timing. Miliseconds are suggested and some ReportVisitor implementations may imply this.

Parameters:

name - name of the Timer

timing - number of elapsed time units for a single measurement

addSingleEventTimerMeasurement

public void addSingleEventTimerMeasurement(String name,
                                           long timing)

Add a timer measurement for a rarely occuring event with given name. This allows Plugins to to react on the estimated rate of the event. Namely the statsd plugin will not sent these, as the requires storage is in no relation to the value of the data. Timers allow adding timer measurements, implicitly incrementing the count Timers count and measure timed events. The application decides which unit to use for timing. Miliseconds are suggested and some ReportVisitor implementations may imply this.

Parameters:

name - name of the Timer

timing - number of elapsed time units for a single measurement

addHighRateTimerMeasurement

public void addHighRateTimerMeasurement(String name,
                                        long timing)

Add a timer measurement for a often occuring event with given name. This allows Plugins to to react on the estimated rate of the event. Namely the statsd plugin will use sampling on these, to reduce network traffic. Timers allow adding timer measurements, implicitly incrementing the count Timers count and measure timed events. The application decides which unit to use for timing. Miliseconds are suggested and some ReportVisitor implementations may imply this.

Parameters:

name - name of the Timer

timing - number of elapsed time units for a single measurement

addTimerMeasurement

public void addTimerMeasurement(String name,
                                long begin,
                                long end)

Add a timer measurement for the given name. Timers allow adding timer measurements, implicitly incrementing the count Timers count and measure timed events. The application decides which unit to use for timing. Miliseconds are suggested and some ReportVisitor implementations may imply this.

Parameters:

name - name of the Timer

begin - number of elapsed time units at the beginning of the single measurement

end - number of elapsed time units at the end of the single measurement

initializeTimerMeasurement

public void initializeTimerMeasurement(String name)

If you want to ensure existence of a timer, for example you want to prevent spelling errors in an operational monitoring configuration, you may initialize a timer using this method. The plugins will decide how to handle this initialization.

Parameters:

name - the name of the timer to be initialized

registerStateValue

public void registerStateValue(StateValueProvider stateValueProvider)

Add a state value provider to this appmon4j instance. StateValueProvider instances allow access to a numeric value (long), that is already available in the application.

Parameters:

stateValueProvider - the StateValueProvider instance to add

registerVersion

public void registerVersion(String name,
                            String version)

This method was intended to register module names with their current version identifier. This could / should actually be generalized into an non numeric state value

Parameters:

name - name of the versionized "thing" (class, module etc.)

version - identifier of the version

addHistorizable

public void addHistorizable(Historizable historizable)

add a Historizable instance to the list identified by historizable.getName()

Parameters:

historizable - the historizable to add

registerPlugin

public void registerPlugin(MonitorPlugin plugin)

Register a plugin to able to hook into monitoring with your own monitor.

Parameters:

plugin - the plugin to adapt a new monitor.

getRegisteredPluginKeys

public List<String> getRegisteredPluginKeys()

removeAllPlugins

public void removeAllPlugins()

getCorePlugin

public CorePlugin getCorePlugin()