Micrometer 快速入门

micrometer为最流行的监控系统提供了一个简单的仪表客户端外观，允许仪表化jvm应用，而无需关心是哪个供应商提供的指标。它的作用和slf4j类似，只不过它关注的不是logging（日志），而是application metrics（应用指标）。简而言之，它就是应用监控界的slf4j。

micrometer（译：千分尺）

不妨看看slf4j官网上对于slf4j的说明：simple logging facade for java (slf4j)

现在再看micrometer的说明：micrometer provides a simple facade over the instrumentation clients for the most popular monitoring systems.

 

metrics（译：指标，度量）

 

micrometer提供了与供应商无关的接口，包括 timers（计时器）， gauges（量规）， counters（计数器）， distribution summaries（分布式摘要）， long task timers（长任务定时器）。它具有维度数据模型，当与维度监视系统结合使用时，可以高效地访问特定的命名度量，并能够跨维度深入研究。

支持的监控系统：appoptics ， azure monitor ， netflix atlas ， cloudwatch ， datadog ， dynatrace ， elastic ， ganglia ， graphite ， humio ， influx/telegraf ， jmx ， kairosdb ， new relic ， prometheus ， signalfx ， google stackdriver ， statsd ， wavefront

 

1.  安装

micrometer记录的应用程序指标用于观察、告警和对环境当前/最近的操作状态做出反应。

为了使用micrometer，首先要添加你所选择的监视系统的依赖。以prometheus为例：

1 <dependency>
2 	<groupid>io.micrometer</groupid>
3   	<artifactid>micrometer-registry-prometheus</artifactid>
4   	<version>${micrometer.version}</version>
5 </dependency>

 

2.  概念

2.1.  registry

meter是收集关于你的应用的一系列指标的接口。meter是由meterregistry创建的。每个支持的监控系统都必须实现meterregistry。 

micrometer中包含一个simplemeterregistry，它在内存中维护每个meter的最新值，并且不将数据导出到任何地方。如果你还没有一个首选的监测系统，你可以先用simplemeterregistry： 

1 meterregistry registry = new simplemeterregistry(); 

注意：如果你用spring的话，simplemeterregistry是自动注入的 

micrometer还提供一个compositemeterregistry用于将多个registries结合在一起使用，允许同时向多个监视系统发布指标。 

1 compositemeterregistry composite = new compositemeterregistry();
2 
3 counter compositecounter = composite.counter("counter");
4 compositecounter.increment();
5 
6 simplemeterregistry simple = new simplemeterregistry();
7 composite.add(simple);
8 
9 compositecounter.increment();

 

2.2.  meters

micrometer提供一系列原生的meter，包括timer , counter , gauge , distributionsummary , longtasktimer , functioncounter , functiontimer , timegauge。不同的meter类型导致有不同的时间序列指标值。例如，单个指标值用gauge表示，计时事件的次数和总时间用timer表示。

每一项指标都有一个唯一标识的名字和维度。“维度”和“标签”是一个意思，micrometer中有一个tag接口，仅仅因为它更简短。一般来说，应该尽可能地使用名称作为轴心。

（ps：指标的名字很好理解，维度怎么理解呢？如果把name想象成横坐标的话，那么dimension就是纵坐标。tag是一个key/value对，代表指标的一个维度值） 

 

2.3.  naming meters（指标命名）

micrometer使用了一种命名约定，用.分隔小写单词字符。不同的监控系统有不同的命名约定。每个micrometer的实现都要负责将micrometer这种以.分隔的小写字符命名转换成对应监控系统推荐的命名。你可以提供一个自己的namingconvention来覆盖默认的命名转换：

1 registry.config().namingconvention(mycustomnamingconvention); 

 有了命名约定以后，下面这个timer在不同的监控系统中看起来就是这样的：

1 registry.timer("http.server.requests"); 

在prometheus中，它是http_server_requests_duration_seconds

在atlas中，它对应的是httpserverrequests

在influxdb中，对应的是http_server_requests

（ps：每项指标都有一个名字，不同的监控系统的命名规则（风格）都不太一样，因此可能同一个指标在不同的监控系统中有不同的名字。简单地来说，比如内存使用率这个指标可能在prometheus中用memoryusage表示，在influxdb中用mem_usage表示，因此每个监控系统都要提供一个命名转换器，当看到mem.usage的时候influxdb应该知道说的是内存使用率，对应的指标名称是mem_usage。这就好比，中文“你好”翻译成英文是“hello”，翻译成日文是“こんにちは” ） 

2.3.1.  tag naming

假设，我们想要统计http请求数和数据库调用次数，那么可以这样写：

1 registry.counter("database.calls", "db", "users");       // 数据库调用次数
2 registry.counter("http.requests", "uri", "/api/users");  // http请求数

2.3.2.  common tags

common tags可以被定义在registry级别，并且会被添加到每个监控系统的报告中

预定义的tags有host , instance , region , stack等 

1 registry.config().commontags("stack", "prod", "region", "us-east-1");
2 registry.config().commontags(arrays.aslist(tag.of("stack", "prod"), tag.of("region", "us-east-1"))); // 二者等价

2.3.4.  tag values

tag values must be non-null 

 

2.4.  meter filters

每个registry都可以配置指标过滤器，它有3个方法：

deny (or accept) meters from being registered

transform meter ids

configure distribution statistics for some meter types.

实现meterfilter就可以加到registry中

1 registry.config()
2     .meterfilter(meterfilter.ignoretags("too.much.information"))
3     .meterfilter(meterfilter.denynamestartswith("jvm")); 

过滤器按顺序应用，所有的过滤器形成一个过滤器链（chain） 

2.4.1.  deny/accept meters

接受或拒绝指标

1 new meterfilter() {
2     @override
3     public meterfilterreply accept(meter.id id) {
4        if(id.getname().contains("test")) {
5           return meterfilterreply.deny;
6        }
7        return meterfilterreply.neutral;
8     }
9 }

meterfilter还提供了许多方便的静态方法用于接受或拒绝指标 

2.4.2.  transforming metrics 

一个转换过滤器可能是这样的：

1 new meterfilter() {
2     @override
3     public meter.id map(meter.id id) {
4        if(id.getname().startswith("test")) {
5           return id.withname("extra." + id.getname()).withtag("extra.tag", "value");
6        }
7        return id;
8     }
9 }

 

2.5.  counters（计数器）

counter接口允许以固定的数值递增，该数值必须为正数。 

 1 meterregistry registry = new simplemeterregistry();
 2 
 3 //  写法一
 4 counter counter = registry.counter("counter");
 5 
 6 //  写法二
 7 counter counter = counter
 8     .builder("counter")
 9     .baseunit("beans") // optional
10     .description("a description of what this counter does") // optional
11     .tags("region", "test") // optional
12     .register(registry);

2.5.1.  function-tracking counters

跟踪单调递增函数的计数器

1 cache cache = ...; // suppose we have a guava cache with stats recording on
2 registry.more().counter("evictions", tags, cache, c -> c.stats().evictioncount()); // evictioncount()是一个单调递增函数，用于记录缓存被剔除的次数

 

2.6.  gauges

gauge是获取当前值的句柄。典型的例子是，获取集合、map、或运行中的线程数等。

meterregistry接口包含了用于构建gauges的方法，用于观察数字值、函数、集合和map。 

1 list<string> list = registry.gauge("listgauge", collections.emptylist(), new arraylist<>(), list::size); //监视非数值对象
2 list<string> list2 = registry.gaugecollectionsize("listsize2", tags.empty(), new arraylist<>()); //监视集合大小
3 map<string, integer> map = registry.gaugemapsize("mapgauge", tags.empty(), new hashmap<>()); 

还可以手动加减gauge

1 atomicinteger n = registry.gauge("numbergauge", new atomicinteger(0));
2 n.set(1);
3 n.set(2);

 

2.7.  timers（计时器） 

timer用于测量短时间延迟和此类事件的频率。所有timer实现至少将总时间和事件次数报告为单独的时间序列。

例如，可以考虑用一个图表来显示一个典型的web服务器的请求延迟情况。服务器可以快速响应许多请求，因此定时器每秒将更新很多次。

 1 // 方式一
 2 public interface timer extends meter {
 3     ...
 4     void record(long amount, timeunit unit);
 5     void record(duration duration);
 6     double totaltime(timeunit unit);
 7 }
 8 
 9 // 方式二
10 timer timer = timer
11     .builder("my.timer")
12     .description("a description of what this timer does") // optional
13     .tags("region", "test") // optional
14     .register(registry); 

查看源代码，一目了然，不一一赘述

 

 

2.8.  long task timers 

长任务计时器用于跟踪所有正在运行的长时间运行任务的总持续时间和此类任务的数量。 

timer记录的是次数，long task timer记录的是任务时长和任务数

 1 // 方式一
 2 @timed(value = "aws.scrape", longtask = true)
 3 @scheduled(fixeddelay = 360000)
 4 void scraperesources() {
 5     // find instances, volumes, auto-scaling groups, etc...
 6 }
 7 
 8 // 方式二
 9 longtasktimer scrapetimer = registry.more().longtasktimer("scrape");
10 void scraperesources() {
11     scrapetimer.record(() => {
12         // find instances, volumes, auto-scaling groups, etc...
13     });
14 }

 

2.9.  distribution summaries（分布汇总）

distribution summary用于跟踪分布式的事件。它在结构上类似于计时器，但是记录的值不代表时间单位。例如，记录http服务器上的请求的响应大小。

1 distributionsummary summary = registry.summary("response.size");

 

2.10.  histograms and percentiles（直方图和百分比） 

timers 和 distribution summaries 支持收集数据来观察它们的百分比。查看百分比有两种主要方法：

percentile histograms（百分比直方图）：  micrometer将值累积到底层直方图，并将一组预先确定的buckets发送到监控系统。监控系统的查询语言负责从这个直方图中计算百分比。目前，只有prometheus , atlas , wavefront支持基于直方图的百分位数近似值，并且通过histogram_quantile , :percentile , hs()依次表示。

client-side percentiles（客户端百分比）：micrometer为每个meter id（一组name和tag）计算百分位数近似值，并将百分位数值发送到监控系统。

下面是用直方图构建timer的一个例子：

1 timer.builder("my.timer")
2    .publishpercentiles(0.5, 0.95) // median and 95th percentile
3    .publishpercentilehistogram()
4    .sla(duration.ofmillis(100))
5    .minimumexpectedvalue(duration.ofmillis(1))
6    .maximumexpectedvalue(duration.ofseconds(10))

 

3.  micrometer prometheus 

prometheus是一个内存中的维度时间序列数据库，具有简单的内置ui、定制查询语言和数学操作。prometheus的设计是基于pull模型进行操作，根据服务发现定期从应用程序实例中抓取指标。

 

3.1.  安装

1 <dependency>
2     <groupid>io.micrometer</groupid>
3     <artifactid>micrometer-registry-prometheus</artifactid>
4     <version>${micrometer.version}</version>
5 </dependency>

 

3.2.  配置

prometheus希望通过抓取或轮询单个应用程序实例来获得指标。除了创建prometheus registry之外，还需要向prometheus的scraper公开一个http端点。在spring环境中，一个prometheus actuator endpoint是在spring boot actuator存在的情况下自动配置的。

下面的示例使用jdk的com.sun.net.httpserver.httpserver来公布scrape端点： 

 1 prometheusmeterregistry prometheusregistry = new prometheusmeterregistry(prometheusconfig.default);
 2 
 3 try {
 4     httpserver server = httpserver.create(new inetsocketaddress(8080), 0);
 5     server.createcontext("/prometheus", httpexchange -> {
 6         string response = prometheusregistry.scrape();
 7         httpexchange.sendresponseheaders(200, response.getbytes().length);
 8         try (outputstream os = httpexchange.getresponsebody()) {
 9             os.write(response.getbytes());
10         }
11     });
12 
13     new thread(server::start).start();
14 } catch (ioexception e) {
15     throw new runtimeexception(e);
16 }

 

3.3.  图表

grafana dashboard

 

4.  spring boot 2.0

spring boot actuator提供依赖管理并自动配置micrometer

spring boot 自动配置一个组合的meterregistry，并添加一个registry到这个组合meterregistry中。

你可以注册任意数量的meterregistrycustomizer来进一步配置registry

1 @bean
2 meterregistrycustomizer<meterregistry> metricscommontags() {
3     return registry -> registry.config().commontags("region", "us-east-1");
4 }

你可以在组件中注入meterregistry，并注册指标：

 1 @component
 2 public class samplebean {
 3 
 4     private final counter counter;
 5 
 6     public samplebean(meterregistry registry) {
 7         this.counter = registry.counter("received.messages");
 8     }
 9 
10     public void handlemessage(string message) {
11         this.counter.increment();
12         // handle message implementation
13     }
14 
15 }

spring boot为prometheus提供/actuator/prometheus端点

下面是一个简单的例子，scrape_config添加到prometheus.yml中：

1 scrape_configs:
2   - job_name: 'spring'
3     metrics_path: '/actuator/prometheus'
4     static_configs:
5       - targets: ['host:port']

 

5.  jvm、cache、okhttpclient

micrometer提供了几个用于监视jvm、cache等的binder。例如：

 1 new classloadermetrics().bindto(registry);
 2 new jvmmemorymetrics().bindto(registry);
 3 new jvmgcmetrics().bindto(registry);
 4 new processormetrics().bindto(registry);
 5 new jvmthreadmetrics().bindto(registry);
 6 
 7 //  通过添加okhttpmetricseventlistener来收集okhttpclient指标
 8 okhttpclient client = new okhttpclient.builder()
 9     .eventlistener(okhttpmetricseventlistener.builder(registry, "okhttp.requests")
10         .tags(tags.of("foo", "bar"))
11         .build())
12     .build();
13 //  为了配置uri mapper，可以用urimapper()
14 okhttpclient client = new okhttpclient.builder()
15     .eventlistener(okhttpmetricseventlistener.builder(registry, "okhttp.requests")
16         .urimapper(req -> req.url().encodedpath())
17         .tags(tags.of("foo", "bar"))
18         .build())
19     .build(); 

还有很多内置的binder，看图：

 

最后，切记文档是用来查的，此处只是一个引子，有个大概印象，等需要用的时候再细查文档即可。

 

6.  文档