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 wach differs:

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

Each of these watches extend from {@link org.jini.rio.watch.ThresholdWatch}, which contains {@link org.jini.rio.core.ThresholdValues}, which in turn can have {@link org.jini.rio.core.SLA}s attached to them providing specific {@link org.jini.rio.qos.SLAPolicyHandler}s approaches.
Watches record {@link org.jini.rio.watch.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 {@link org.jini.rio.watch.WatchDataSource}. The WatchDataSource can be transient or persistent, and provides a reposiory 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.