Rio Project 4.0 API Documentation

Package org.rioproject.watch

Provides mechanisms to collect and analyze programmer defined metrics defined in a distributed application.

See:
Description

Interface Summary

Archivable	Used to archive Calculable entries added to a $WatchDataSource.
CalculableViewable	Interface defining semantics for viewing a Calculable record
CounterWatchMBean	Provides a standard MBean to use when administering a CounterWatch using JMX
PeriodicWatchMBean	Provides a standard MBean to use when administering a PeriodicWatch using JMX
RemoteWatchDataReplicator	A remote WatchDataReplicator.
StopWatchMBean	Provides a standard MBean to use when administering a StopWatch using JMX
ThresholdListener	Listener for notification that a threshold has been crossed.
ThresholdWatchMBean	Provides a standard MBean to use when administering a Watch using JMX
Watchable	This interface is used to fetch WatchDataSource instances that have been created and registered
WatchDataReplicator	Used to replicate Calculable entries added to a $WatchDataSource.
WatchDataSource	The WatchDataSource interface defines the semantics for a Watch to store Calculable records
WatchMBean	Provides a standard MBean to use when administering a Watch using JMX
WatchRegistry	Defines the semantics for a registry of Watch instances and their corresponding WatchDataSource instances, providing capabilities to search over all registered Watch instances.
WatchService	A service that supports the creation of remote WatchDataSource instances

Class Summary

Accumulator	The Accumulator represents a collection of Calculable objects and performs statistical analysis across the collection of Calculable objects, providing mean, median and standard deviation
AccumulatorViewer	Accumulator Viewer
BoundedThresholdManager	The BoundedThresholdManager provides support for threshold handling as follows: A ThresholdNotify.notify method is invoked when the high threshold is breached, and again invoked when the Calculable drops below the high threshold.
Calculable	A Calculable is the atomic attribute that is being 'watched'
CalculableDisplayAttributes	Default attributes to display when providing rendering support for a Calculable
CalculableViewable.PlottedCalculable	Data structure that holds as properties the the Calculable and the Point it is plotted at
CounterCalculableView	A view for a Counter Calculable
CounterWatch	A CounterWatch provides a mechanism to count a monotonically increasing non-negative value of an arbitrary occurance of something over time
DefaultCalculableView	Default attributes for viewing a collection of Calculables
FontDescriptor	Contains information about a Font used by the AccumulatorViewer
GaugeWatch	A GaugeWatch provides a mechanism to record values that can go up and down, and can be positive or negative.
PeriodicWatch	A PeriodicWatch provides a mechanism to obtain information at preset intervals of time.
QueuedReplicator	Provides a queued approach to replicate a Watch record.
ResponseTimeCalculableView	A view for a response time Calculable
SamplingWatch	An implementation of a PeriodicWatch that samples a bean's method
Statistics	Class Statistics implements basic statistical formulae.
StopWatch	A Watch for capturing elapsed time
ThreadDeadlockMonitor	Monitor thread deadlocks for a Java Virtual Machine.
ThresholdCalculableView	A ThresholdCalculableView is used to render threshold watches
ThresholdEvent	The ThresholdEvent extends RemoteServiceEvent allowing for remote notification of a Threshold being crossed
ThresholdManager	The ThresholdManager is the keeper of ThresholdValues and determines when Calculable items being recorded have crossed any thresholds.
ThresholdValues	ThresholdValues provides attributes for thresholds which can be applied to a Watch
ThresholdWatch	A Watch that provides threshold processing semantics
Watch	The Watch provides a mechanism to collect information and associate it to a WatchDataSource
WatchDataReplicatorProxy	Proxy for a WatchDataReplicator to be used in conjunction with a RemoteWatchDataReplicator.
WatchDataSourceImpl	The WatchDataSourceImpl provides support for the WatchDataSource interface.
WatchDataSourceRegistry	An implementation of a WatchRegistry
WatchDescriptor	The WatchDescriptor defines attributes of a declarable Watch, allowing a Watch to be declared as part of an OperationalString.
WatchInjector	The WatchInjector provides support for declarative Watch management, by taking a WatchDescriptor and creating SamplingWatch instances which are then registered for an instantiated service.
WatchServiceImpl	Created by IntelliJ IDEA.

Enum Summary

WatchDescriptor.Type

Package org.rioproject.watch Description

Provides mechanisms to collect and analyze programmer defined metrics defined in a distributed application. This framework may be used to instrument services developed under the Rio Architecture and to monitor performance and other measurable aspects of distributed operational strings of execution using this architecture.

The approach outlined in this document provides the basis for recording a measurement of a metric. Recording can be done either locally within a JVM or remotely across different JVM’s. Depending on the type of metric being observed (watched), the type of watch differs:

• A CounterWatch provides a mechanism to count a monotonically increasing non-negative value of an arbitrary occurance of something over time
• A GaugeWatch provides a mechanism to record values that can go up and down, and can be positive or negative.
• A StopWatch is a Watch for capturing elapsed time

Each of these watches extend from ThresholdWatch, which contains ThresholdValues, which in turn can have SLAs attached to them providing specific SLAPolicyHandlers approaches.

Watches record Calculable objects which contain the value of the metric being observed and the time when the metric was captured. These object sre stored in a WatchDataSource. The WatchDataSource can be transient or persistent, and provides a repository for given watch instance Calculables.

While the Watch framework is generic in that it can collect any kind of metric, a common use will be to measure application response times. It is useful to analyze this type of measurement to understand the Watchable Framework.

Within an application, a bounded unit of work can be measured for execution time. Because, the Service Bean and Service Container model is inherently distributed, this bounded unit of work may be local to one Java Virtual Machine or span multiple Java Virtual Machines. (If end points are distributed some mechanism for clock synchronization is required. Clock synchronization is beyond the scope of this document.)

Local Watches

The simplest case is to measure response time within a local Java Virtual Machine. The main steps in measuring these response time metrics are:

1. Create the StopWatch which:
• Creates a local instance of a WatchDataSource
• Associates the WatchDataSource to the StopWatch
2. Register the WatchDataSource with the WatchDataSourceRegistry. This allows the WatchDataSource to be discovered by remote clients
3. Start the timing
4. Stop the timing which:
• Calculates the elapsed time
• Creates a Calculable object
• Adds the Calculable object to the WatchDataSource
5. Repeat Steps #3 and #4 as necessary
6. Examine the results

The “StopWatch” class is essentially a utility class used for capturing this elapsed execution time. A Calculable record is created and then stored in the WatchDataSource. The getValue method of the Calculable interface returns a double value which represents the milliseconds of elapsed time for this measurement.

Remote Watches
The next case is to measure response time within a local Java Virtual Machine, but post the results to a remote WatchDataSource. This kind of pattern is useful when the desired outcome is a common collection of metrics from various services or from numerous instances of the same service. The main steps in measuring these response time metrics are:

1. Find the remote WatchDataSource
2. Associate the WatchDataSource with the StopWatch
3. Start the timing
4. Stop the timing which:
• Calculates the elapsed time
• Creates a Calculable object
• Adds the Calculable object to the WatchDataSource
5. Repeat Steps #3 and #4 as necessary
6. Examine the results

The primary difference here is that the WatchDataSource is first located using the Jini Lookup Service. Once located, the constructor for the StopWatch is invoked passing the reference to the remote WatchDataSource. Once the StopWatch has been created in this way, the rest of the processing steps are the same as the local case.