# Gauge
Gauge(仪表)是获取当前度量记录值的句柄，也就是它表示一个可以任意上下浮动的单数值度量Meter。Gauge通常用于变动的测量值，测量值用ToDoubleFunction参数的返回值设置，如当前的内存使用情况，同时也可以测量上下移动的”计数”，比如队列中的消息数量。
官网文档中提到Gauge的典型使用场景是用于测量集合或映射的大小或运行状态中的线程数。Gauge一般用于监测有自然上界的事件或者任务，而Counter一般使用于无自然上界的事件或者任务的监测，所以像Http请求总量计数应该使用Counter而非Gauge。
MeterRegistry中提供了一些便于构建用于观察数值、函数、集合和映射的Gauge相关的方法：
Listlist= registry.gauge("listGauge", Collections.emptyList(),newArrayList<>(),List::size);List list2 = registry.gaugeCollectionSize("listSize2", Tags.empty(),newArrayList<>());Map map = registry.gaugeMapSize("mapGauge", Tags.empty(),newHashMap<>());
上面的三个方法通过MeterRegistry构建Gauge并且返回了集合或者映射实例，使用这些集合或者映射实例就能在其size变化过程中记录这个变更值。更重要的优点是，我们不需要感知Gauge接口的存在，只需要像平时一样使用集合或者映射实例就可以了。
此外，Gauge还支持java.lang.Number的子类，java.util.concurrent.atomic包中的AtomicInteger和AtomicLong，还有Guava提供的AtomicDouble：
AtomicInteger n = registry.gauge("numberGauge",newAtomicInteger(0));n.set(1);n.set(2);
除了使用MeterRegistry创建Gauge之外，还可以使用建造器流式创建：
//一般我们不需要操作Gauge实例Gauge gauge = Gauge.builder("gauge", myObj, myObj::gaugeValue).description("a description of what this gauge does")// 可选.tags("region","test")// 可选.register(registry);
使用场景：
根据个人经验和实践，总结如下：
有自然(物理)上界的浮动值的监测，例如物理内存、集合、映射、数值等。
有逻辑上界的浮动值的监测，例如积压的消息、(线程池中)积压的任务等，其实本质也是集合或者映射的监测。
举个相对实际的例子，假设我们需要对登录后的用户发送一条短信或者推送，做法是消息先投放到一个阻塞队列，再由一个线程消费消息进行其他操作：
publicclassGaugeMain{privatestaticfinalMeterRegistry MR =newSimpleMeterRegistry();privatestaticfinalBlockingQueue QUEUE =newArrayBlockingQueue<>(500);privatestaticBlockingQueue REAL_QUEUE;static{REAL_QUEUE = MR.gauge("messageGauge", QUEUE, Collection::size); }publicstaticvoidmain(String[] args)throwsException{ consume();Message message =newMessage();message.setUserId(1L);message.setContent("content"); REAL_QUEUE.put(message); }privatestaticvoidconsume()throwsException{newThread(() -> {while(true) {try{ Message message = REAL_QUEUE.take();//handle message System.out.println(message);}catch(InterruptedException e) {//no-op } } }).start(); }}
上面的例子代码写得比较糟糕，只为了演示相关使用方式，切勿用于生产环境。
# TimeGauge
TimeGauge是Gauge的特化类型，相比Gauge，它的构建器中多了一个TimeUnit类型的参数，用于指定ToDoubleFunction入参的基础时间单位。这里简单举个使用例子：
publicclassTimeGaugeMain{privatestaticfinalSimpleMeterRegistryR= newSimpleMeterRegistry();publicstaticvoid main(String[] args)throwsException{AtomicIntegercount= newAtomicInteger();TimeGauge.Builder timeGauge =TimeGauge.builder("timeGauge",count,TimeUnit.SECONDS,AtomicInteger::get);timeGauge.register(R);count.addAndGet(10086);print();count.set(1);print(); }privatestaticvoidprint()throwsException{Search.in(R).meters().forEach(each -> {StringBuilderbuilder = newStringBuilder();builder.append("name:") .append(each.getId().getName()).append(",tags:") .append(each.getId().getTags()).append(",type:").append(each.getId().getType()).append(",value:").append(each.measure());System.out.println(builder.toString()); }); } }//输出name:timeGauge,tags:[],type:GAUGE,value:[Measurement{statistic='VALUE', value=10086.0}]name:timeGauge,tags:[],type:GAUGE,value:[Measurement{statistic='VALUE', value=1.0}]
# DistributionSummary
Summary(摘要)主要用于跟踪事件的分布，在Micrometer中，对应的类是DistributionSummary(分发摘要)。它的使用方式和Timer十分相似，但是它的记录值并不依赖于时间单位。
常见的使用场景：使用DistributionSummary测量命中服务器的请求的有效负载大小。使用MeterRegistry创建DistributionSummary实例如下：
DistributionSummarysummary = registry.summary("response.size");
通过建造器流式创建如下：
DistributionSummary summary = DistributionSummary.builder("response.size").description("a description of what this summary does")// 可选.baseUnit("bytes")// 可选.tags("region","test")// 可选.scale(100)// 可选.register(registry);
DistributionSummary中有很多构建参数跟缩放和直方图的表示相关，见下一节。
