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
。除非您定义自己的,否则将提供自动配置的GraphiteConfig
和Clock
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
。除非您定义自己的,否则将提供自动配置的JmxConfig
和Clock
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-requests
为true
时,将对所有请求进行检测。或者,当设置为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 带有以下信息标记:
Tag | Description |
---|---|
exception | 处理请求时引发的任何异常的简单类名。 |
method | 请求的方法(例如GET 或POST ) |
outcome | 请求的结果基于响应的状态码。 1xx 是INFORMATIONAL ,2xx 是SUCCESS ,3xx 是REDIRECTION ,4xx CLIENT_ERROR ,5xx 是SERVER_ERROR |
status | 响应的 HTTP 状态代码(例如200 或500 ) |
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 相关的度量标准标记有以下信息:
Tag | Description |
---|---|
exception | 处理请求时引发的任何异常的简单类名。 |
method | 请求的方法(例如GET 或POST ) |
outcome | 请求的结果基于响应的状态码。 1xx 是INFORMATIONAL ,2xx 是SUCCESS ,3xx 是REDIRECTION ,4xx CLIENT_ERROR ,5xx 是SERVER_ERROR |
status | 响应的 HTTP 状态代码(例如200 或500 ) |
uri | 变量替换之前的请求 URI 模板(如果可能)(例如/api/person/{id} ) |
要自定义标签,请提供实现WebFluxTagsProvider
的@Bean
。
57.3.3 Jersey 服务器 Metrics
通过自动配置,可以检测由 Jersey JAX-RS 实现处理的请求。当management.metrics.web.server.auto-time-requests
为true
时,将对所有请求进行检测。或者,当设置为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 带有以下信息:
Tag | Description |
---|---|
exception | 处理请求时引发的任何异常的简单类名。 |
method | 请求的方法(例如GET 或POST ) |
outcome | 请求的结果基于响应的状态码。 1xx 是INFORMATIONAL ,2xx 是SUCCESS ,3xx 是REDIRECTION ,4xx CLIENT_ERROR ,5xx 是SERVER_ERROR |
status | 响应的 HTTP 状态代码(例如200 或500 ) |
uri | 变量替换之前的请求 URI 模板(如果可能)(例如/api/person/{id} ) |
要自定义标签,请提供实现JerseyTagsProvider
的@Bean
。
57.3.4 HTTP Client 端 Metrics
Spring Boot Actuator ManagementRestTemplate
和WebClient
的工具。为此,您必须注入自动配置的构建器并使用它来创建实例:
-
RestTemplateBuilder
RestTemplate
-
WebClient.Builder
WebClient
也可以手动应用负责此工具的定制程序,即MetricsRestTemplateCustomizer
和MetricsWebClientCustomizer
。
默认情况下,使用名称http.client.requests
生成度量。可以通过设置management.metrics.web.client.requests-metric-name
属性来自定义名称。
默认情况下,由检测的 Client 端生成的度量标准标记有以下信息:
-
method
,即请求的方法(例如GET
或POST
)。 -
uri
,变量替换之前的请求 URI 模板(如果可能的话,例如/api/person/{id}
)。 -
status
,即响应的 HTTP 状态代码(例如200
或500
)。 -
clientName
,即 URI 的主机部分。
要自定义标签,并根据您选择的 Client 端,可以提供实现RestTemplateExchangeTagsProvider
或WebClientExchangeTagsProvider
的@Bean
。 RestTemplateExchangeTags
和WebClientExchangeTags
中有便捷的静态函数。
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
上面的示例将region
和stack
标签添加到所有仪表,其值分别为us-east-1
和prod
。
Note
如果使用 Graphite,则常用标签的 Sequences 很重要。由于使用这种方法不能保证通用标签的 Sequences,因此建议 Graphite 用户定义自定义MeterFilter
。
57.5.2 每米属性
除了MeterFilter
bean 外,还可以使用属性在每米基础上应用有限的一组自定义设置。每表定制适用于以给定名称开头的所有所有表 ID。例如,以下将禁用所有 ID 以example.remote
开头的仪表
management.metrics.enable.example.remote=false
以下属性允许按米自定义:
表 57.1. 每米自定义
Property | Description |
---|---|
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-histogram
,percentiles
和sla
后面的概念的更多详细信息,请参阅千分尺文档的“直方图和百分位数”部分。
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
。