org.glassfish.jersey.server.monitoring
Interface MonitoringStatistics

public interface MonitoringStatistics

Monitoring statistics return statistic information about application run like number of requests received, duration of request processing, number of successfully processed requests, statistical information about execution of methods and resources, information about matching but also static information about application configuration like application name, registered resource classes and such.

Monitoring statistics is the main interface from which all statistic information can be retrieved. Statistics can be retried in two ways: these can be injected or received from registered callback interface MonitoringStatisticsListener. The following is the example of statistic injection:

   @Path("resource")
   public static class StatisticsTest {
       @Inject
       Provider<MonitoringStatistics> statistics;

       @GET
       public String getAppName() throws InterruptedException {
           final MonitoringStatistics monitoringStatistics = statistics.get();
           final String name = monitoringStatistics.getApplicationStatistics()
                               .getResourceConfig().getApplicationName();

           return name;
       }
   }
 

Note usage of Provider to retrieve statistics. Statistics change over time and this will inject the latest statistics. In the case of singleton resources usage of Provider is the only way how to inject statistics that are up to date.

Retrieving statistics by MonitoringStatisticsListener is convenient in cases when there is a need to take an action only when new statistics are calculated which occurs in not defined irregular intervals (once per second for example).

The contract does not mandate MonitoringStatistics to be immutable. Implementation of monitoring statistics might be mutable, which means that an instance of MonitoringStatistics might change its internal state over time. In order to get immutable snapshot of statistics the method snapshot() must be called to get a snapshot of the statistics that guarantees that data to be immutable and consistent. Nested statistics interfaces contain also snapshot method which can be used in the same way. Note that a snapshot of MonitoringStatistics performs a deep snapshot of nested statistics object too, so there is no need to call the snapshot method again on nested statistics components.

The implementation of this interface may be mutable and change it's state by an external event, however it is guaranteed to be thread-safe.

Author:

Miroslav Fuksa (miroslav.fuksa at oracle.com)

Method Summary

ApplicationStatistics	getApplicationStatistics() Get global statistics about application and configuration of application.
ExceptionMapperStatistics	getExceptionMapperStatistics() Get statistics about registered exception mappers.
ExecutionStatistics	getRequestStatistics() Get the global application statistics of request execution.
Map<Class<?>,ResourceStatistics>	getResourceClassStatistics() Get the statistics for each resource Class that is deployed in the application.
ResponseStatistics	getResponseStatistics() Get global application response statistics.
Map<String,ResourceStatistics>	getUriStatistics() Get the statistics for each URI that is exposed in the application.
MonitoringStatistics	snapshot() Get the immutable consistent snapshot of the monitoring statistics.

Method Detail

getUriStatistics

Map<String,ResourceStatistics> getUriStatistics()

Get the statistics for each URI that is exposed in the application. Keys of returned map are String URIs (for example "/bookstore/users/admin") and values are resource statistics that contain information about execution of resource methods available on the URI. The map contain URIs that are available in application without URIs available in sub resource locators and URIs that are available trough sub resource locators and were already matched by any request.

Returns:

Map with URI keys and resource statistics values.

getResourceClassStatistics

Map<Class<?>,ResourceStatistics> getResourceClassStatistics()

Get the statistics for each resource Class that is deployed in the application. Keys of returned map are classes of resources and values are resource statistics that contain information about execution of resource methods available in the resource class. Note that one resource class can serve request matched to different URIs. By default the map will contain resource classes which are registered in the resource model plus resource classes of sub resources returned from sub resource locators.

Returns:

Map with resource class keys and resource statistics values.

getRequestStatistics

ExecutionStatistics getRequestStatistics()

Get the global application statistics of request execution. The statistics are not bound any specific resource or resource method and contains information about all requests that application handles.

Returns:

Application request execution statistics.

getResponseStatistics

ResponseStatistics getResponseStatistics()

Get global application response statistics. The statistics are not bound any specific resource or resource method and contains information about all responses that application creates.

Returns:

Application response statistics.

getApplicationStatistics

ApplicationStatistics getApplicationStatistics()

Get global statistics about application and configuration of application.

Returns:

Global application statistics and configuration.

getExceptionMapperStatistics

ExceptionMapperStatistics getExceptionMapperStatistics()

Get statistics about registered exception mappers.

Returns:

Exception mapper statistics.

snapshot

MonitoringStatistics snapshot()

Get the immutable consistent snapshot of the monitoring statistics. Working with snapshots might have negative performance impact as snapshot must be created but ensures consistency of data over time. However, the usage of snapshot is encouraged to avoid working with inconsistent data. Not all statistics must be updated in the same time on mutable version of statistics.

Returns:

Snapshot of monitoring statistics.