【2016-08-08】

In addition to JMX and HTTP, Metrics also has reporters for the following outputs:

• STDOUT, using ConsoleReporter from metrics-core
• CSV files, using CsvReporter from metrics-core
• SLF4J loggers, using Slf4jReporter from metrics-core
• Ganglia, using GangliaReporter from metrics-ganglia
• Graphite, using GraphiteReporter from metrics-graphite

Metric Registries

      The starting point for Metrics is the MetricRegistry class, which is a collection of all the metrics for your application (or a subset of your application).

        Generally you only need one MetricRegistry instance per application, although you may choose to use more if you want to organize your metrics in particular reporting groups.

        Global named registries can also be shared through the static SharedMetricRegistries class. This allows the same registry to be used in different sections of code without explicitly passing a MetricRegistry instance around.

       Like all Metrics classes, SharedMetricRegistries is fully thread-safe.

Metric Names

        Each metric is associated with a MetricRegistry, and has a unique name within that registry. This is a simple dotted name, likecom.example.Queue.size. This flexibility allows you to encode a wide variety of context directly into a metric’s name. If you have two instances of com.example.Queue, you can give them more specific: com.example.Queue.requests.size vs. com.example.Queue.responses.size, for example.

MetricRegistry has a set of static helper methods for easily creating names:

MetricRegistry.name(Queue.class, "requests", "size")
MetricRegistry.name(Queue.class, "responses", "size")

These methods will also elide any null values, allowing for easy optional scopes.

Gauges

        A gauge is the simplest metric type. It just returns a value. If, for example, your application has a value which is maintained by a third-party library, you can easily expose it by registering a Gauge instance which returns that value:

【首先，它返回一个值，这个值是实时的，并且不限定只能是数值类型；其次，他能方便的获取到第三方库的数据】

registry.register(name(SessionStore.class, "cache-evictions"), new Gauge<Integer>() {
    @Override
    public Integer getValue() {
        return cache.getEvictionsCount();
    }
});

JMX Gauges

        Given that many third-party library often expose metrics only via JMX, Metrics provides the JmxAttributeGauge class, which takes the obje

registry.register(name(SessionStore.class, "cache-evictions"),
                 new JmxAttributeGauge("net.sf.ehcache:type=Cache,scope=sessions,name=eviction-count", "Value"));

Ratio Gauges

        A ratio gauge is a simple way to create a gauge which is the ratio between two numbers:

public class CacheHitRatio extends RatioGauge {
    private final Meter hits;
    private final Timer calls;
    public CacheHitRatio(Meter hits, Timer calls) {
        this.hits = hits;
        this.calls = calls;
    }
    @Override
    public Ratio getRatio() {
        return Ratio.of(hits.getOneMinuteRate(),
                        calls.getOneMinuteRate());
    }
}

      This gauge returns the ratio of cache hits to misses using a meter and a timer.

Cached Gauges

      A cached gauge allows for a more efficient reporting of values which are expensive to calculate:

registry.register(name(Cache.class, cache.getName(), "size"),
                  new CachedGauge<Long>(10, TimeUnit.MINUTES) {
                      @Override
                      protected Long loadValue() {
                          // assume this does something which takes a long time
                          return cache.getSize();
                      }
                  });

Derivative Gauges

        A derivative gauge allows you to derive values from other gauges’ values:

public class CacheSizeGauge extends DerivativeGauge<CacheStats, Long> {
    public CacheSizeGauge(Gauge<CacheStats> statsGauge) {
        super(statsGauge);
    }
    @Override
    protected Long transform(CacheStats stats) {
        return stats.getSize();
    }
}

Counters

        A counter is a simple incrementing and decrementing 64-bit integer:

final Counter evictions = registry.counter(name(SessionStore.class, "cache-evictions"));
evictions.inc();
evictions.inc(3);
evictions.dec();
evictions.dec(2);

      All Counter metrics start out at 0.

Histograms

      A Histogram measures the distribution of values in a stream of data: e.g., the number of results returned by a search:   

final Histogram resultCounts = registry.histogram(name(ProductDAO.class, "result-counts");
resultCounts.update(results.size());

        直方图统计，不仅可以统计简单的像最大值，最小值，平均值以及标准差，还可以统计分位数，中位数以及百分数。

        传统上，中位数（或其他任何位数）的计算方法是采取整个数据集，对其进行排序，并采取值在中间（或1 ％，从年底，第99百分位数） 。这适用于小的数据集，或分批处理系统中，但不适用于高并发，低延迟服务。

        而Histograms能满足需求，是因为它采用了简单的采样数据的解决方案。By maintaining a small, manageable reservoir which is statistically representative of the data stream as a whole, we can quickly and easily calculate quantiles which are valid approximations of the actual quantiles. This technique is called reservoir sampling.

Meters

final Meter getRequests = registry.meter(name(WebProxy.class, "get-requests", "requests"));
getRequests.mark();
getRequests.mark(requests.size());

        Meters有几种不同的方法测量时间发生的比率。mean rate是事件发生的平均比率。

        eg：请求的总数量/程序run的秒数。

Timers

final Timer timer = registry.timer(name(WebProxy.class, "get-requests"));
final Timer.Context context = timer.time();
try {
    // handle request
} finally {
    context.stop();
}