core/api/src/docs/metrics.txt

//////////////////////
 * Copyright (c) 2007-2012, Niclas Hedhman. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 * either express or implied.
 * See the License for the specific language governing permissions
 * and limitations under the License.
//////////////////////

[[core-api-metrics, Metrics API]]
= Metrics API =
The Zest™ platform defines an advanced Metrics SPI to capture runtime metrics of Zest's internals as well be used by
application code (via this API) to provide production metrics for operations personnel, ensuring healthy state of
the applications.


== MetricsProvider ==
There are quite a lot of different Metrics components available, which are instantiated via factories. There is one
factory for each component type, to allow for additional components to be created in the future without breaking
compatibility in the existing implementations.

The MetricsProvider is a standard Zest™ Service and simply acquired via the @Service annotation on a field or
constructor argument.

[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=common
--------------

== Gauge ==
A Gauge is the simplest form of Metric. It is a value that the application sets, which is polled upon request. The
application need to provide the implementation of the _value()_ method. Gauges are genericized for type-safe value
handling.

A Gauge can represent anything, for instance, thread pool levels, queue sizes and other resource allocations. It is
useful to have separate gauges for percentage (%) and absolute numbers of the same resource. Operations are mainly
interested in being alerted when threshold are reach as a percentage, as it is otherwise too many numbers to keep
track of.

To create a Gauge, you do something like;

[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=gauge
--------------

== Counter ==

[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=counter
--------------

== Histogram ==
[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=histogram
--------------

== Meter ==

[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=meter
--------------

== Timer ==
Timers capture both the length of some execution as well as rate of calls. They can be used to time method calls, or
critical sections, or even HTTP requests duration and similar.

[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=timer
--------------

== HealthCheck ==

[snippet,java]
--------------
source=core/api/src/test/java/org/qi4j/api/metrics/DocumentationSupport.java
tag=healthcheck
--------------