org.avaje.metric

Interface TimedMetric

All Superinterfaces:

Metric

public interface TimedMetric
extends Metric

Collects and provides statics for a timed event.

Typically collects execution statistics for a method. TimedMetric has the ability to keep separate statistics for success and error execution. It is generally useful to know which methods are invoking errors and differences in execution time of errors versus successful execution.

Example: Using addEventSince(boolean, long).

 
  
  // Declare the metric (typically as a static field)
  
  static final TimedMetric timedUserLogin = MetricManager.getTimedMetric(MyService.class, "performLogin");
  ...
  
  public void performLogin() {
    
    long startNanos = System.nanoTime();
    
    try {
      ...
    
    
    } finally {
      // Add the event to the success statistics
      timedUserLogin.addEventSince(true, startNanos);
    }
  }
  
 
 

Instead of programmatically adding TimedMetric code these can be added using enhancement. Classes that are annotated with @Timed on the class or method can have the appropriate code added via enhancement. Also note that the enhancement in addition can be applied to classes annotated with @Singleton, JAX-RS annotations like @Path and Spring stereotype annotations like @Component, @Service etc.

The enhancement will add instructions such that for method execution that throw exceptions the timing is put into the error statistics. This can provide quick insight into where errors are occurring, how frequently and execution time of errors.

Example: @Timed annotation.

 
  ...
  @Timed
  public void performLogin() {
    ...
  }
  
 
 

Example: Alternative using TimedMetric. This will have a slight extra cost compared with addEventSince(boolean, long) as TimedEvent is instantiated and must be later garbage collected - using #addEventSince(boolean, long) avoid that extra object creation.

 
  TimedMetric metric = MetricManager.getTimedMetric(MyService.class, "sayHello");
  ...
  
  TimedEvent timedEvent = metric.startEvent();
  try {
    ...
  
  } finally {
    // Add the event to the success statistics
    timedEvent.endWithSuccess();
  }
  
 
 

Method Summary

Methods

Modifier and Type	Method and Description
void	addEventDuration(boolean success, long durationNanos) Add an event duration in nanoseconds noting if it was a success or failure result.
void	addEventSince(boolean success, long startNanos) Add an event based on a startNanos (determined by System.nanoTime()).
ValueStatistics	getCollectedErrorStatistics() Return the error statistics.
ValueStatistics	getCollectedSuccessStatistics() Return the success statistics.
ValueStatistics	getErrorStatistics(boolean reset) Return the error success statistics choosing is the underlying statistics should be reset.
ValueStatistics	getSuccessStatistics(boolean reset) Return the current success statistics choosing is the underlying statistics should be reset.
void	operationEnd(int opCode, long startNanos) Add an event duration with opCode indicating success or failure.
TimedEvent	startEvent() Start an event.

Methods inherited from interface org.avaje.metric.Metric

clearStatistics, collectStatistics, getName, visit

Method Detail

getCollectedSuccessStatistics

ValueStatistics getCollectedSuccessStatistics()

Return the success statistics.

getCollectedErrorStatistics

ValueStatistics getCollectedErrorStatistics()

Return the error statistics.

getSuccessStatistics

ValueStatistics getSuccessStatistics(boolean reset)

Return the current success statistics choosing is the underlying statistics should be reset.

getErrorStatistics

ValueStatistics getErrorStatistics(boolean reset)

Return the error success statistics choosing is the underlying statistics should be reset.

startEvent

TimedEvent startEvent()

Start an event.

At the completion of the event one of TimedEvent.endWithSuccess(), TimedEvent.endWithError() or TimedEvent.end(boolean) is called to record the event duration and success or otherwise.

This is an alternative to using addEventSince(boolean, long) or addEventDuration(boolean, long). Note that this startEvent() method has slightly higher overhead as it instantiates a TimedEvent object which must be later GC'ed. In this sense generally addEventSince() is the preferred method to use.

addEventSince

void addEventSince(boolean success,
                 long startNanos)

Add an event based on a startNanos (determined by System.nanoTime()).

Success and failure statistics are kept separately.

This is an alternative to using startEvent(). Note that using startEvent() has slightly higher overhead as it instantiates a TimedEvent object which must be later GC'ed. In this sense generally addEventSince() is the preferred method to use.

addEventDuration

void addEventDuration(boolean success,
                    long durationNanos)

Add an event duration in nanoseconds noting if it was a success or failure result.

Success and failure statistics are kept separately.

This is an alternative to using addEventSince(boolean, long) where you pass in the duration rather than the start nanoseconds.

operationEnd

void operationEnd(int opCode,
                long startNanos)

Add an event duration with opCode indicating success or failure. This is intended for use by enhanced code and not general use.

Although this looks redundant and a little ugly having this method means that for enhancement the added byte code is minimised. In the case where metric collection is turned off overhead is limited to a System.nanoTime() call and a noop method call.