57. Metrics

Spring Boot Actuator 为Micrometer提供依赖关系 Management 和自动配置,Micrometer是一种应用程序 Metrics 外观,支持众多监视系统,包括:

Tip

要了解有关 Micrometer 功能的更多信息,请参阅其reference documentation,尤其是concepts section

57.1 使用 Starter

Spring Boot 自动配置组合MeterRegistry,并为其在 Classpath 上找到的每个受支持的实现向组合添加注册表。在运行时 Classpath 中具有micrometer-registry-{system}的依赖关系足以让 Spring Boot 配置注册表。

大多数注册表具有共同的 Feature。例如,即使 Micrometer 注册表实现位于 Classpath 中,您也可以禁用特定的注册表。例如,要禁用 Datadog:

management.metrics.export.datadog.enabled=false

Spring Boot 还会将任何自动配置的注册表添加到Metrics类的全局静态复合注册表中,除非您明确告知不要:

management.metrics.use-global-registry=false

您可以注册任意数量的MeterRegistryCustomizer bean 来进一步配置注册表,例如在向注册表注册任何计量器之前应用通用标签:

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

您可以通过更具体地了解通用类型,将自定义应用于特定的注册表实现:

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

完成该设置后,您可以在组件中注入MeterRegistry并注册 Metrics:

@Component
public class SampleBean {

	private final Counter counter;

	public SampleBean(MeterRegistry registry) {
		this.counter = registry.counter("received.messages");
	}

	public void handleMessage(String message) {
		this.counter.increment();
		// handle message implementation
	}

}

Spring Boot 也是配置内置仪器(即MeterBinder实现),您可以通过配置或专用 Comments 标记进行控制。

57.2 支持的监视系统

57.2.1 AppOptics

默认情况下,AppOptics 注册表会定期将 Metrics 推送到api.appoptics.com/v1/measurements。要将 Metrics 导出到 SaaS AppOptics,必须提供您的 API 令牌:

management.metrics.export.appoptics.api-token=YOUR_TOKEN

57.2.2 Atlas

默认情况下,度量标准导出到在本地计算机上运行的Atlas。可以使用以下方式提供要使用的Atlas server的位置:

management.metrics.export.atlas.uri=http://atlas.example.com:7101/api/v1/publish

57.2.3 Datadog

Datadog 注册表会定期将 Metrics 推送到datadoghq。要将 Metrics 导出到Datadog,必须提供您的 API 密钥:

management.metrics.export.datadog.api-key=YOUR_KEY

您还可以更改将度量标准发送到 Datadog 的时间间隔:

management.metrics.export.datadog.step=30s

57.2.4 Dynatrace

Dynatrace 注册表会定期将 Metrics 推送到配置的 URI。要将 Metrics 导出到Dynatrace,必须提供您的 API 令牌,设备 ID 和 URI:

management.metrics.export.dynatrace.api-token=YOUR_TOKEN
management.metrics.export.dynatrace.device-id=YOUR_DEVICE_ID
management.metrics.export.dynatrace.uri=YOUR_URI

您还可以更改将度量标准发送到 Dynatrace 的时间间隔:

management.metrics.export.dynatrace.step=30s

57.2.5 Elastic

默认情况下,度量标准导出到在本地计算机上运行的Elastic。可以使用以下属性提供要使用的 Elastic 服务器的位置:

management.metrics.export.elastic.host=http://elastic.example.com:8086

57.2.6 Ganglia

默认情况下,度量标准导出到在本地计算机上运行的Ganglia。可以使用以下方式提供要使用的Ganglia server主机和端口:

management.metrics.export.ganglia.host=ganglia.example.com
management.metrics.export.ganglia.port=9649

57.2.7 Graphite

默认情况下,度量标准导出到在本地计算机上运行的Graphite。可以使用以下方式提供要使用的Graphite server主机和端口:

management.metrics.export.graphite.host=graphite.example.com
management.metrics.export.graphite.port=9004

千分尺提供默认值HierarchicalNameMapper,该默认值HierarchicalNameMapper决定尺寸表 ID Map 到平面层次结构名称的方式。

Tip

要控制此行为,请定义您的GraphiteMeterRegistry并提供您自己的HierarchicalNameMapper。除非您定义自己的,否则将提供自动配置的GraphiteConfigClock bean:

@Bean
public GraphiteMeterRegistry graphiteMeterRegistry(GraphiteConfig config, Clock clock) {
	return new GraphiteMeterRegistry(config, clock, MY_HIERARCHICAL_MAPPER);
}

57.2.8 Humio

默认情况下,Humio 注册表会定期将 Metrics 推送到cloud.humio.com。要将 Metrics 导出到 SaaS Humio,必须提供您的 API 令牌:

management.metrics.export.humio.api-token=YOUR_TOKEN

您还应该配置一个或多个标记以标识将度量标准推送到的数据源:

management.metrics.export.humio.tags.alpha=a
management.metrics.export.humio.tags.bravo=b

57.2.9 Influx

默认情况下,度量标准导出到在本地计算机上运行的Influx。可以使用以下方式提供要使用的Influx server的位置:

management.metrics.export.influx.uri=http://influx.example.com:8086

57.2.10 JMX

千分尺提供到JMX的层次结构 Map,主要是作为一种便宜且可移植的方式在本地查看 Metrics。默认情况下,Metrics 会导出到metrics JMX 域。可以使用以下方式提供要使用的域:

management.metrics.export.jmx.domain=com.example.app.metrics

千分尺提供默认值HierarchicalNameMapper,该默认值HierarchicalNameMapper决定尺寸表 ID Map 到平面层次结构名称的方式。

Tip

要控制此行为,请定义您的JmxMeterRegistry并提供您自己的HierarchicalNameMapper。除非您定义自己的,否则将提供自动配置的JmxConfigClock bean:

@Bean
public JmxMeterRegistry jmxMeterRegistry(JmxConfig config, Clock clock) {
	return new JmxMeterRegistry(config, clock, MY_HIERARCHICAL_MAPPER);
}

57.2.11 KairosDB

默认情况下,度量标准导出到在本地计算机上运行的KairosDB。可以使用以下方式提供要使用的KairosDB server的位置:

management.metrics.export.kairos.uri=http://kairosdb.example.com:8080/api/v1/datapoints

57.2.12 New Relic

新的 Relic 注册表会定期将 Metrics 推送到New Relic。要将 Metrics 导出到New Relic,必须提供您的 API 密钥和帐户 ID:

management.metrics.export.newrelic.api-key=YOUR_KEY
management.metrics.export.newrelic.account-id=YOUR_ACCOUNT_ID

您还可以更改将度量标准发送到 New Relic 的时间间隔:

management.metrics.export.newrelic.step=30s

57.2.13 Prometheus

Prometheus希望抓取或轮询单个应用程序实例以获取 Metrics。 Spring Boot 在/actuator/prometheus处提供了一个 Actuator 端点,以渲染具有适当格式的Prometheus scrape

Tip

该端点默认情况下不可用,必须公开,有关更多详细信息,请参见exposing endpoints

这是将scrape_config添加到prometheus.yml的示例:

scrape_configs:
  - job_name: 'spring'
	metrics_path: '/actuator/prometheus'
	static_configs:
	  - targets: ['HOST:PORT']

57.2.14 SignalFx

SignalFx 注册表会定期将 Metrics 推送到SignalFx。要将 Metrics 导出到SignalFx,必须提供您的访问令牌:

management.metrics.export.signalfx.access-token=YOUR_ACCESS_TOKEN

您还可以更改将度量标准发送到 SignalFx 的时间间隔:

management.metrics.export.signalfx.step=30s

57.2.15 Simple

千分尺附带一个简单的内存后端,如果未配置其他注册表,该后端将自动用作后备。这使您可以查看metrics endpoint中收集了哪些 Metrics。

使用任何其他可用后端时,内存后端都会自行禁用。您还可以显式禁用它:

management.metrics.export.simple.enabled=false

57.2.16 StatsD

StatsD 注册表急切地通过 UDP 将度量标准推送到 StatsD 代理。默认情况下,Metrics 会导出到本地计算机上运行的StatsD代理。可以使用以下方式提供要使用的 StatsD 代理主机和端口:

management.metrics.export.statsd.host=statsd.example.com
management.metrics.export.statsd.port=9125

您还可以更改要使用的 StatsD 线路协议(默认为 Datadog):

management.metrics.export.statsd.flavor=etsy

57.2.17 Wavefront

Wavefront 注册表会定期将 Metrics 推送到Wavefront。如果您直接将 Metrics 导出到Wavefront,则必须提供您的 API 令牌:

management.metrics.export.wavefront.api-token=YOUR_API_TOKEN

或者,您可以使用在您的环境中设置的 Wavefront 辅助工具或内部代理,将 Metrics 数据转发到 Wavefront API 主机:

management.metrics.export.wavefront.uri=proxy://localhost:2878

Tip

如果将 Metrics 发布到 Wavefront 代理(如the documentation中所述),则主机必须为proxy://HOST:PORT格式。

您还可以更改将度量标准发送到 Wavefront 的时间间隔:

management.metrics.export.wavefront.step=30s

57.3 支持的 Metrics

如果适用,Spring Boot 将注册以下核心 Metrics:

  • JVM Metrics,报告以下方面的利用率:

  • 各种内存和缓冲池

    • 与垃圾收集有关的统计数据

    • Threads utilization

    • 加载/卸载的类数

  • CPU metrics

  • 文件 DescriptorsMetrics

  • KafkaConsumerMetrics

  • Log4j2 Metrics:记录每个级别记录到 Log4j2 的事件数

  • Logback Metrics:记录每个级别记录到 Logback 的事件数

  • 正常运行时间 Metrics:报告正常运行时间的量度和代表应用程序绝对启动时间的固定量度

  • Tomcat metrics

  • Spring Integration metrics

57.3.1 Spring MVC Metrics

通过自动配置,可以检测由 Spring MVC 处理的请求。当management.metrics.web.server.auto-time-requeststrue时,将对所有请求进行检测。或者,当设置为false时,可以通过将@Timed添加到请求处理方法来启用检测:

@RestController
@Timed (1)
public class MyController {

	@GetMapping("/api/people")
	@Timed(extraTags = { "region", "us-east-1" }) (2)
	@Timed(value = "all.people", longTask = true) (3)
	public List<Person> listPeople() { ... }

}
  • (1) 控制器类,用于对控制器中的每个请求处理程序启用计时。
  • (2) 一种启用单个端点的方法。如果您将它放在类中,则不必这样做,但是可以用于进一步为此特定端点自定义计时器。
  • (3) 具有longTask = true的方法为该方法启用长任务计时器。长任务计时器需要一个单独的度量标准名称,并且可以与短任务计时器堆叠在一起。

默认情况下,使用名称http.server.requests生成度量。可以通过设置management.metrics.web.server.requests-metric-name属性来自定义名称。

默认情况下,与 Spring MVC 相关的 Metrics 带有以下信息标记:

TagDescription
exception处理请求时引发的任何异常的简单类名。
method请求的方法(例如GETPOST)
outcome请求的结果基于响应的状态码。 1xx 是INFORMATIONAL,2xx 是SUCCESS,3xx 是REDIRECTION,4xx CLIENT_ERROR,5xx 是SERVER_ERROR
status响应的 HTTP 状态代码(例如200500)
uri变量替换之前的请求 URI 模板(如果可能)(例如/api/person/{id})

要自定义标签,请提供实现WebMvcTagsProvider@Bean

57.3.2 Spring WebFlux Metrics

通过自动配置,可以检测 WebFlux 控制器和功能处理程序处理的所有请求。

默认情况下,使用名称http.server.requests生成度量。您可以通过设置management.metrics.web.server.requests-metric-name属性来自定义名称。

默认情况下,与 WebFlux 相关的度量标准标记有以下信息:

TagDescription
exception处理请求时引发的任何异常的简单类名。
method请求的方法(例如GETPOST)
outcome请求的结果基于响应的状态码。 1xx 是INFORMATIONAL,2xx 是SUCCESS,3xx 是REDIRECTION,4xx CLIENT_ERROR,5xx 是SERVER_ERROR
status响应的 HTTP 状态代码(例如200500)
uri变量替换之前的请求 URI 模板(如果可能)(例如/api/person/{id})

要自定义标签,请提供实现WebFluxTagsProvider@Bean

57.3.3 Jersey 服务器 Metrics

通过自动配置,可以检测由 Jersey JAX-RS 实现处理的请求。当management.metrics.web.server.auto-time-requeststrue时,将对所有请求进行检测。或者,当设置为false时,可以通过将@Timed添加到请求处理方法来启用检测:

@Component
@Path("/api/people")
@Timed (1)
public class Endpoint {
	@GET
	@Timed(extraTags = { "region", "us-east-1" }) (2)
	@Timed(value = "all.people", longTask = true) (3)
	public List<Person> listPeople() { ... }
}
  • (1) 在资源类上,以对资源中的每个请求处理程序启用计时。
  • (2) 关于启用单个端点的方法。如果您将它放在类中,则不必这样做,但是可以用于进一步为此特定端点自定义计时器。
  • (3) 在具有longTask = true的方法上为该方法启用长任务计时器。长任务计时器需要一个单独的度量标准名称,并且可以与短任务计时器堆叠在一起。

默认情况下,使用名称http.server.requests生成度量。可以通过设置management.metrics.web.server.requests-metric-name属性来自定义名称。

默认情况下,Jersey 服务器 Metrics 带有以下信息:

TagDescription
exception处理请求时引发的任何异常的简单类名。
method请求的方法(例如GETPOST)
outcome请求的结果基于响应的状态码。 1xx 是INFORMATIONAL,2xx 是SUCCESS,3xx 是REDIRECTION,4xx CLIENT_ERROR,5xx 是SERVER_ERROR
status响应的 HTTP 状态代码(例如200500)
uri变量替换之前的请求 URI 模板(如果可能)(例如/api/person/{id})

要自定义标签,请提供实现JerseyTagsProvider@Bean

57.3.4 HTTP Client 端 Metrics

Spring Boot Actuator ManagementRestTemplateWebClient的工具。为此,您必须注入自动配置的构建器并使用它来创建实例:

  • RestTemplateBuilder RestTemplate

  • WebClient.Builder WebClient

也可以手动应用负责此工具的定制程序,即MetricsRestTemplateCustomizerMetricsWebClientCustomizer

默认情况下,使用名称http.client.requests生成度量。可以通过设置management.metrics.web.client.requests-metric-name属性来自定义名称。

默认情况下,由检测的 Client 端生成的度量标准标记有以下信息:

  • method,即请求的方法(例如GETPOST)。

  • uri,变量替换之前的请求 URI 模板(如果可能的话,例如/api/person/{id})。

  • status,即响应的 HTTP 状态代码(例如200500)。

  • clientName,即 URI 的主机部分。

要自定义标签,并根据您选择的 Client 端,可以提供实现RestTemplateExchangeTagsProviderWebClientExchangeTagsProvider@BeanRestTemplateExchangeTagsWebClientExchangeTags中有便捷的静态函数。

57.3.5 缓存 Metrics

通过自动配置,可以在启动时使用前缀cache的度量来检测所有可用的Cache。高速缓存检测针对一组基本 Metrics 进行了标准化。还提供其他特定于缓存的 Metrics。

支持以下缓存库:

  • Caffeine

  • EhCache 2

  • Hazelcast

  • 任何兼容的 JCache(JSR-107)实现

用高速缓存的名称和从 Bean 名称派生的CacheManager的名称来标记度量标准。

Note

只有启动时可用的缓存才绑定到注册表。对于在启动阶段后即时或以编程方式创建的缓存,需要显式注册。提供CacheMetricsRegistrar bean 可以简化该过程。

57.3.6 数据源 Metrics

通过自动配置,可以使用名为jdbc的度量标准检测所有可用的DataSource对象。数据源检测产生的量规表示池中当前 Active,最大允许和最小允许的连接。这些仪表中的每个都有一个以jdbc为前缀的名称。

度量标准还标有根据 Bean 名称计算出的DataSource的名称。

Tip

默认情况下,Spring Boot 为所有支持的数据源提供元数据。如果不支持立即使用您喜欢的数据源,则可以添加其他DataSourcePoolMetadataProvider bean。有关示例,请参见DataSourcePoolMetadataProvidersConfiguration

此外,特定于 Hikari 的 Metrics 以hikaricp前缀公开。每个度量标准都由池的名称标记(可以使用spring.datasource.name进行控制)。

57.3.7 HibernateMetrics

通过自动配置,可以检测所有可用名为hibernate的 Metrics 启用了统计信息的 Hibernate EntityManagerFactory实例。

度量标准还标有从 Bean 名称派生的EntityManagerFactory的名称。

要启用统计信息,必须将标准 JPA 属性hibernate.generate_statistics设置为true。您可以在自动配置的EntityManagerFactory上启用它,如以下示例所示:

spring.jpa.properties.hibernate.generate_statistics=true

57.3.8 RabbitMQ Metrics

自动配置将启用所有名为rabbitmq的度量的可用 RabbitMQ 连接工厂的检测。

57.4 注册自定义 Metrics

要注册自定义 Metrics,请在组件中注入MeterRegistry,如以下示例所示:

class Dictionary {

	private final List<String> words = new CopyOnWriteArrayList<>();

	Dictionary(MeterRegistry registry) {
		registry.gaugeCollectionSize("dictionary.size", Tags.empty(), this.words);
	}

	// …

}

如果发现您在组件或应用程序中反复测试了一套 Metrics,则可以将此套件封装在MeterBinder实现中。默认情况下,所有MeterBinder bean 的度量将自动绑定到 Spring Management 的MeterRegistry

57.5 自定义单个 Metrics

如果您需要对特定的Meter实例应用自定义设置,则可以使用io.micrometer.core.instrument.config.MeterFilter界面。默认情况下,所有MeterFilter bean 将自动应用于千分尺MeterRegistry.Config

例如,如果要将所有以com.example开头的仪表 ID 的mytag.region标签重命名为mytag.area,则可以执行以下操作:

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

57.5.1 常用标签

通用标签通常用于在操作环境(如主机,实例,区域,堆栈等)上进行维度深入分析。通用标签适用于所有仪表,可以按以下示例所示进行配置:

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

上面的示例将regionstack标签添加到所有仪表,其值分别为us-east-1prod

Note

如果使用 Graphite,则常用标签的 Sequences 很重要。由于使用这种方法不能保证通用标签的 Sequences,因此建议 Graphite 用户定义自定义MeterFilter

57.5.2 每米属性

除了MeterFilter bean 外,还可以使用属性在每米基础上应用有限的一组自定义设置。每表定制适用于以给定名称开头的所有所有表 ID。例如,以下将禁用所有 ID 以example.remote开头的仪表

management.metrics.enable.example.remote=false

以下属性允许按米自定义:

表 57.1. 每米自定义

PropertyDescription
management.metrics.enable是否拒绝仪表发出任何 Metrics。
management.metrics.distribution.percentiles-histogram是否发布适合计算可凝集(跨维度)百分位数逼近的直方图。
management.metrics.distribution.minimum-expected-value , management.metrics.distribution.maximum-expected-value通过限制期望值的范围来发布较少的直方图桶。
management.metrics.distribution.percentiles发布在应用程序中计算的百分位值
management.metrics.distribution.sla发布包含您的 SLA 定义的存储区的累积直方图。

有关percentiles-histogrampercentilessla后面的概念的更多详细信息,请参阅千分尺文档的“直方图和百分位数”部分

57.6 Metrics 终结点

Spring Boot 提供了一个metrics端点,可用于诊断检查应用程序收集的 Metrics。该端点默认情况下不可用,必须公开,有关更多详细信息,请参见exposing endpoints

导航到/actuator/metrics将显示可用仪表名称的列表。您可以通过提供特定名称作为 selectors 来深入查看有关特定仪表的信息,例如/actuator/metrics/jvm.memory.max

Tip

您在此处使用的名称应与代码中使用的名称相匹配,而不是已针对其出厂的监视系统进行了命名约定标准化后的名称。换句话说,如果jvm.memory.max由于其蛇形命名约定而在 Prometheus 中显示为jvm_memory_max,则在metrics端点中检查电表时,仍应使用jvm.memory.max作为 selectors。

您还可以在网址末尾添加任意数量的tag=KEY:VALUE查询参数,以在维度上更深入地了解电表,例如/actuator/metrics/jvm.memory.max?tag=area:nonheap

Tip

报告的测量值是与仪表名称和已应用的所有标签相匹配的所有仪表的统计信息的。因此,在上面的示例中,返回的“值”统计量是堆的“代码缓存”,“压缩类空间”和“元空间”区域的最大内存占用量的总和。如果您只想查看“ Metaspace”的最大大小,则可以添加一个额外的tag=id:Metaspace,即/actuator/metrics/jvm.memory.max?tag=area:nonheap&tag=id:Metaspace