org.apache.commons.monitoring
Interface Monitor

All Known Subinterfaces:

Monitor.Observable

All Known Implementing Classes:

AbstractMonitor, CompositeValuesMonitor, CreateValuesOnDemandMonitor, EmpyMonitor, ObservableMonitor, SecondaryMonitor

public interface Monitor

A Monitor is an abstraction of some application resource that is instrumented with a set of indicators (Gauges or Counters).

A Monitor is identified by its Key, that MUST be unique in the application. To ensure this, the Key class defines the monitor identifier as a combination of name, subsystem and category.

The name is the human-readable representation of the "resource" beeing monitored. A typical use is the fully qualified class name + method signature, or the HTTP request path.

The category is a grouping attribute to reflect the application layering. Typically for JEE application, you will set category to the N-tier layer beeing monitored ("servlet", "service", "persistence").

The subsystem is a logical grouping, by use-cases. "account", and "user" can be used as subsystem for the application account and user management dedicated components.

You are free to use more complex Key types, by simple subclassing the Key class and providing the adequate equals()/hasCode() methods.

The Counters / Gauges used to store monitored application state are retrieved based on a "role" String. The monitor can handle as many values as needed, until any of them has a dedicated role. This allows to easily extend the monitor by registering custom values.

Author:

Nicolas De Loof

Nested Class Summary

static class	Monitor.Key Identifier class for Monitors
static interface	Monitor.Listener Listener interface to get notified on montor events
static interface	Monitor.Observable Monitor that accepts Listeners and notify them on monitor events

Field Summary

static Role<Gauge>	CONCURRENCY default role for multi-thread concurrency
static Role<Counter>	FAILURES default Role for the invocation failure counter
static Role<Counter>	PERFORMANCES default role key for code performances

Method Summary

Counter	getCounter(Role<Counter> role) Retrieve or create a Counter in the monitor
Counter	getCounter(java.lang.String role) Retrieve a Counter
Gauge	getGauge(Role<Gauge> role) Retrieve or create a Gauge in the monitor
Gauge	getGauge(java.lang.String role) Retrieve a Gauge in the monitor
Monitor.Key	getKey()
java.util.Collection<Role>	getRoles()
<T extends StatValue> T	getValue(Role<T> role) Retrieve a StatValue in the monitor
StatValue	getValue(java.lang.String role) Retrieve a StatValue.
java.util.Collection<StatValue>	getValues()
void	reset() Reset all StatValues (don't remove them)

Field Detail

PERFORMANCES

static final Role<Counter> PERFORMANCES

default role key for code performances

CONCURRENCY

static final Role<Gauge> CONCURRENCY

default role for multi-thread concurrency

FAILURES

static final Role<Counter> FAILURES

default Role for the invocation failure counter

Method Detail

getKey

Monitor.Key getKey()

Returns:

the monitor key

getCounter

Counter getCounter(java.lang.String role)

Retrieve a Counter

Parameters:

role - a unique identifier for a Counter in the monitor

unit - the data unit to count

Returns:

the Counter

getCounter

Counter getCounter(Role<Counter> role)

Retrieve or create a Counter in the monitor

Parameters:

role - the Counter role in the monitor

Returns:

the Counter

getGauge

Gauge getGauge(java.lang.String role)

Retrieve a Gauge in the monitor

Parameters:

role - a unique identifier for a Gauge in the monitor

Returns:

the Gauge

getGauge

Gauge getGauge(Role<Gauge> role)

Retrieve or create a Gauge in the monitor

Parameters:

role - the gauge role in the monitor

Returns:

the Gauge

getValue

StatValue getValue(java.lang.String role)

Retrieve a StatValue.

Parameters:

role - a unique identifier for a StatValue in the monitor

Returns:

the StatValue

getValue

<T extends StatValue> T getValue(Role<T> role)

Retrieve a StatValue in the monitor

Parameters:

role - the StatValue role in the monitor

Returns:

the StatValue

getRoles

java.util.Collection<Role> getRoles()

Returns:

an unmodifiable collection of registered statValues roles

getValues

java.util.Collection<StatValue> getValues()

Returns:

an unmodifiable collection of registered statValues

reset

void reset()

Reset all StatValues (don't remove them)