Micrometer | 基础 - [Spring Boot Actuator]

目录

• §6 Metrics
  • 6.1 Getting started
  • 6.2 Supported monitoring systems
  • 6.3 Supported Metrics
  • 6.3.1 Spring MVC Metrics
  • 6.3.2 Spring WebFlux Metrics
  • 6.3.3 Jersey Server Metrics
    • 6.3.4 HTTP Client Metrics
  • 6.3.5 Cache Metrics
  • 6.3.6 DataSource Metrics
  • 6.4 Registering custom metrics
  • 6.5 Customizing individual metrics
    • 6.5.1 Common tags
  • 6.5.2 Per-meter properties
  • 6.6 Metrics endpoint

对应官方文档
https://docs.spring.io/spring-boot/docs/2.3.12.RELEASE/reference/html/production-ready-features.html

§6 Metrics

Spring Boot Actuator 提供自动配置 Micrometer 的依赖管理
Micrometer 是一个应用级 Metrics 门面，它可以支持众多监控系统

6.1 Getting started

Spring Boot 会自动配置一个复合型 MeterRegistry，并将 classpath 中能找到的每一个支持的实现注册到这个 MeterRegistry 里面

什么叫 支持的实现？
即 micrometer-registry-{system}，system 是支持的监控系统名，比如 micrometer-registry-prometheus
能找到对应的包，就是支持的 MeterRegistry 的实现
只要运行时 classpath 里包含 micrometer-registry-{system} 依赖，就可以使 springboot 自动配置对应 system 的 Metirc

大部分 micrometer-registry-{system} 具有通用的特性。
举个例子，即使 classpath 里已经包含了 micrometer-registry-{system} 的依赖，依然可以通过下面的配置来禁用它

management.metrics.export.{system}.enabled=false

springboot 还会把自动装配的 registry 添加到全局静态的复核注册中心上，这东西在 Metrics 类中，如下

public class Metrics {public static final CompositeMeterRegistry globalRegistry = new CompositeMeterRegistry();
}

但可以通过下面的配置不让它注册

management.metrics.use-global-registry=false

在任意 Meter 实现被注册之前，你可以通过向 springboot 容器声明任意数量的 MeterRegistryCustomizer bean，来进一步配置 registry
比如设置 commonTags

@Bean
MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {return registry -> registry.config().commonTags("region", "us-east-1");
}

也可以通过 MeterRegistryCustomizer 的泛型的实参，将定制化应用于指定的 registry 实现上

@Bean
MeterRegistryCustomizer<GraphiteMeterRegistry> graphiteMetricsNamingConvention() {return registry -> registry.config().namingConvention(MY_CUSTOM_CONVENTION);
}

6.2 Supported monitoring systems

略

6.3 Supported Metrics

springboot 注册以下核心指标：

• JVM
  • 各种内存（指标里也会有内存池的说法）和缓冲池
  • GC 相关的统计
  • 线程
  • 加载/未加载的类的数量
• CPU
• 文件描述符
• Kafka consumer/producer/streams
• 日志：Log4j2/Logback
• 各种上电时间
• Tomcat，需要 server.tomcat.mbeanregistry.enabled=true
• Micrometer Integration，5.0.3 及以后才支持

6.3.1 Spring MVC Metrics

通过下面的配置，启用 Spring MVC 的自动装配，这会统计所有 MVC 执行的请求

management.metrics.web.server.request.autotime.enabled=true

或者，也可以通过 @Timed 注解

@RestController
@Timed //整个 controller 都开启
public class MyController {@GetMapping("/api/people")// 对某个方法(准确的是叫 endpoint)开启// 如果类上配了 @Timed，这里就不必要，但可以用了进一步配置单独的方法@Timed(extraTags = { "region", "us-east-1" }) // 用于配置长任务的 (LongTaskTimer)，长任务需要一个独立的指标名，并且可以与短任务堆叠@Timed(value = "all.people", longTask = true) public List<Person> listPeople() { ... }
}

默认情况下，metrics 名为 http.server.requests，可以通过下面配置自定义

management.metrics.web.server.request.metric-name=http.server.requests

此 metrics 具有如下 tag

Tag	Description
exception	执行时抛出的异常的简单类名
method	GET/POST
outcome	请求结果，即响应码。1xx-5xx 依次表示：信息/成功/重定向/客户端错误/服务端错误
status	响应码
uri	endpoint 的路径，如 @RequestMapping(value = "/monitor") 的 value

6.3.2 Spring WebFlux Metrics

略

6.3.3 Jersey Server Metrics

略

6.3.4 HTTP Client Metrics

Spring Boot Actuator 支持 RestTemplate 和 WebClient 的参数

• RestTemplate 通过 RestTemplateBuilder 创建
• WebClient 通过 WebClient.Builder 创建，这是 WebFlux 用的

builder 是自动装配的，可以直接通过它创建实例，例如

@Bean
public RestTemplate restTemplate(RestTemplateBuilder builder) {return builder.build();
}

builder 也可以通过 MetricsRestTemplateCustomizer/MetricsWebClientCustomizer 手动自定义

默认情况下，metrics 名为 http.client.requests，可以通过下面配置自定义

management.metrics.web.client.request.metric-name=http.client.requests

此 metrics 具有如下 tag

Tag	Description
clientName	URI 的主机部分
method	GET/POST
outcome	请求结果，即响应码。1xx-5xx 依次表示：信息/成功/重定向/客户端错误/服务端错误
status	响应码
uri	endpoint 的路径，如 @RequestMapping(value = "/monitor") 的 value

@PathVariable 带来的问题
以如下代码为例

@RequestMapping(value = "/p/{count}")
public String p(@PathVariable String count) {return count;
}

按 count = 1~10 依次调用此接口，其监控结果不是对 /p/{count} 端点的 10 次访问，而是对 /p/1 ~ /p/10，共 10 个端点的各一次访问
经验证（定制 RestTemplateExchangeTagsProvider），此问题目前看来无解
请求发起端除非人为在请求上进行标记，否则无法从 uri 中匹配出来对应的模板，不能识别模板也就不能完成聚合

6.3.5 Cache Metrics

略

6.3.6 DataSource Metrics

所有可用的 DataSource 对象都可以通过自动装配启用其监控，随后得到以 jdbc.connections 为前缀的指标
这些指标反映连接池的 最大、最小、当前活跃、当前空闲连接数
指标带有 DataSource 名 tag，其值基于 bean 名确认

默认情况下，springboot 为所有支持的数据源提供了元数据，对于没有提供开箱即用的支持的数据源，可以添加额外的 DataSourcePoolMetadataProvider
可以参考 DataSourcePoolMetadataProvidersConfiguration 作为例子

Hikari 连接池的 metrics 通过 hikaricp 前缀暴露，每个 metric 都带着 pool tag，这个 tag 的值是连接池的名字，可以通过下面的配置指定数据源名

spring.datasource.name=HikariPool-1

6.4 Registering custom metrics

注册自定义 metrics，需要在 Component 里注入 MeterRegistry，如下演示

class Dictionary {private final List<String> words = new CopyOnWriteArrayList<>();//在这里注入Dictionary(MeterRegistry registry) {registry.gaugeCollectionSize("dictionary.size", Tags.empty(), this.words);}
}

如果 metrics 依赖其他 bean，可以通过 MeterBinder 实现，如下所示

@Bean
MeterBinder queueSize(Queue queue) {return (registry) -> Gauge.builder("queueSize", queue::size).register(registry);
}

MeterBinder 可以保证正确的设置 Metrics 的依赖关系，可以保证在获取 Metrics 的值时，依赖的 bean 可用
如果需要在组建或应用中，反复检查同一组指标，那使用 MeterBinder 就是非常有效的
默认情况下，所有 MeterBinder 定义的 Metrics 都会自动装配到 spring 管理的 MeterRegistry 中

6.5 Customizing individual metrics

通过 io.micrometer.core.instrument.config.MeterFilter 接口，可以定制化 Meter 实例
比如，如果想重命名所有 com.example 开头的 meter id 的 mytag.region 标签为 mytag.area，参考如下代码

@Beanpublic MeterFilter renameRegionTagMeterFilter() {return MeterFilter.renameTag("com.example", "mytag.region", "mytag.area");
}

默认情况下，所有 MeterFilter bean 都会自动的绑定到 spring 管理的 MeterRegistry 中
确保 metrics 通过 spring 管理的 MeterRegistry，而不是任何 Metrics 的静态方法注册，后者的全局注册不是被 spring 纳管的

6.5.1 Common tags

通用标签常用于在操作环境上向下挖掘，如 host, instance, region, stack 等
通用标签的配置方式如下，配置后会作用于所有的测量，这个例子会给所有的测量分别追加两个值

management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prod

默认情况下 通用标签的顺序 是无法保证的，因此建议在使用 Graphite 的场景中自定义一个自定义 MeterFilter

6.5.2 Per-meter properties

除了 MeterFilter bean，还可以在每个测量的基础上，通过属性套用一个有限的自定义集合
通测自定义可以作用于以指定名字起始的每个测量 ID，如下例，可以禁用所有 ID 以 example.remote 起始的测量

management.metrics.enable.example.remote=false

下列参数允许通测属性

|management.metrics.enable|是否开启测量|
|management.metrics.distribution.percentiles-histogram|是否发布直方图，直方图适用于计算可聚合的（跨维度）百分位近似值|
|management.metrics.distribution.minimum-expected-value|为减少直方图竖桶的数量，而限定期望值的范围|
|这两个参数用于定义期望值范围的最大、最小值|management.metrics.distribution.maximum-expected-value|
|management.metrics.distribution.percentiles|开启应用的百分位计算|
|management.metrics.distribution.slo|开启累计直方图，其中的桶由服务级别目标定义|

怎么理解东西？

看到这里，知道这东西学名应该叫什么的，受累告诉我一声

per- 的前缀在词源上表示 "一直、贯通、完全"，因此 per-meter properties 结合当前语义暂时翻译为 "通测属性"（但是不重要）
可以这么理解，有一些参数，叫作 a.b.c，但是必须写作 a.b.c.<metrics> 才能生效，如下图所示，不包含红框中的 metrics 会报错
这种形式的属性叫做 per-meter properties

对应到代码上，这类参数的实际类型是一个 map

6.6 Metrics endpoint

springboot 提供了一个 /metrics 端点，它可以检查从应用上收集的所有 metrics
默认情况下，/metrics 端点是关闭的，必须手动暴露它

/actuator/metrics 的明细
/actuator/metrics 展示所有可用测量的名字，使用这些名字可以深入查看指定的测量指标信息，如下
/actuator/metrics/jvm.memory.max
访问 /actuator/metrics，有下图

以 /actuator/metrics/jvm.buffer.count 的形式可以查看具体参数的详情
追加在后面的名字应该用代码风格（jvm.buffer.count）而不是转换为接入监控系统时的格式（jvm_buffer_count）
说白了 /actuator/metrics 这里展示出了什么指标，就能看什么指标的详情，这里指标叫啥名，就原封不动的使用这个名，不要变格式

/actuator/metrics 的 tag 筛选
可以在 URL 后追加任意数量的 tag=KEY:VALUE 形式的查询参数（用 & 分割多个），以（在维度上深入）查看某个指标的详情
带有 tag 筛选的查询所返回的结果，是匹配 metrics 名称以及所有指定的 tag 的 metric 的统计之和（原文是 any tag，实测应该按所有 tag 理解）
因此，/actuator/metrics/jvm.memory.max?tag=area:nonheap 是所有的非堆的统计，包括代码缓冲区、压缩类空间和元空间
如果只需要元空间的数据统计，应该使用 /actuator/metrics/jvm.memory.max?tag=area:nonheap&tag=id:Metaspace