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 {@link 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 {@link javax.inject.Provider} to retrieve statistics. Statistics change over time and this willinject the latest statistics. In the case of singleton resources usage of {@code Provider} is the only way howto inject statistics that are up to date.
Retrieving statistics by {@code MonitoringStatisticsListener} is convenient in cases when there is a needto 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 {@code MonitoringStatistics} to be immutable. Implementation of monitoring statisticsmight be mutable, which means that an instance of {@code MonitoringStatistics}might change its internal state over time. In order to get immutable snapshot of statistics the method {@link #snapshot()} must be called to get a snapshot of the statistics that guaranteesthat data to be immutable and consistent. Nested statistics interfaces contain also {@code snapshot} method whichcan be used in the same way. Note that a snapshot of {@code MonitoringStatistics} performs a deep snapshot of nested statistics object too, so thereis no need to call the {@code 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)