Spring Boot 生产就绪中文文档-下

本文为官方文档直译版本。原文链接
由于篇幅较长，遂分两篇。上半部分中文文档

度量标准

Spring Boot Actuator 为 Micrometer 提供了依赖关系管理和自动配置功能，Micrometer 是一个应用程序度量门面，支持众多监控系统，包括

• AppOptics
• Atlas
• Datadog
• Dynatrace
• Elastic
• Ganglia
• Graphite
• Humio
• Influx
• JMX
• KairosDB
• New Relic
• OpenTelemetry
• Prometheus
• SignalFx
• Simple (in-memory)
• Stackdriver
• StatsD
• Wavefront

要了解 Micrometer 功能的更多信息，请参阅参考文档，特别是概念部分。

入门

Spring Boot 会自动配置一个复合 MeterRegistry，并为它在类路径上找到的每个支持的实现添加一个注册表。运行时类路径中对 micrometer-registry-{system} 的依赖足以让 Spring Boot 配置注册表。
大多数注册表都有共同的功能。例如，即使 Micrometer 注册表实现位于类路径上，您也可以禁用某个注册表。下面的示例禁用了 Datadog：

management:
  datadog:
    metrics:
      export:
        enabled: false

您也可以禁用所有注册表，除非注册表特定属性另有说明，如下例所示：

management:
  defaults:
    metrics:
      export:
        enabled: false

Spring Boot 还会将任何自动配置的注册表添加到 Metrics 类的全局静态复合注册表中，除非您明确告诉它不要这样做：

management:
  metrics:
    use-global-registry: false

您可以注册任意数量的 MeterRegistryCustomizer Bean 来进一步配置注册表，例如在向注册表注册任何仪表之前应用通用标记：

import io.micrometer.core.instrument.MeterRegistry;

import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyMeterRegistryConfiguration {
    
    

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

}

您可以通过更具体的通用类型，对特定的注册表实施进行自定义：

import io.micrometer.core.instrument.Meter;
import io.micrometer.core.instrument.config.NamingConvention;
import io.micrometer.graphite.GraphiteMeterRegistry;

import org.springframework.boot.actuate.autoconfigure.metrics.MeterRegistryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyMeterRegistryConfiguration {
    
    

    @Bean
    public MeterRegistryCustomizer<GraphiteMeterRegistry> graphiteMetricsNamingConvention() {
    
    
        return (registry) -> registry.config().namingConvention(this::name);
    }

    private String name(String name, Meter.Type type, String baseUnit) {
    
    
        return ...
    }

}

Spring Boot 还配置了内置仪器，你可以通过配置或专用注释标记来控制这些仪器。

受支持的监控系统

本节简要介绍每个支持的监控系统。

AppOptics

默认情况下，AppOptics 注册会定期将指标推送到 api.appoptics.com/v1/measurements。要将指标导出到 SaaS AppOptics，必须提供您的 API 标记：

management:
  appoptics:
    metrics:
      export:
        api-token: "YOUR_TOKEN"

Atlas

默认情况下，度量指标会导出到本地计算机上运行的 Atlas。您可以提供 Atlas 服务器的位置：

management:
  atlas:
    metrics:
      export:
        uri: "https://atlas.example.com:7101/api/v1/publish"

Datadog

Datadog 注册表会定期向 datadoghq 推送指标。要将指标导出到 Datadog，您必须提供 API 密钥：

management:
  datadog:
    metrics:
      export:
        api-key: "YOUR_KEY"

如果额外提供应用密钥（可选），则还会导出仪表描述、类型和基本单位等元数据：

management:
  datadog:
    metrics:
      export:
        api-key: "YOUR_API_KEY"
        application-key: "YOUR_APPLICATION_KEY"

默认情况下，度量指标发送到 Datadog 美国站点 (api.datadoghq.com)。如果您的 Datadog 项目托管在其他站点上，或者您需要通过代理发送度量指标，请相应配置 URI：

management:
  datadog:
    metrics:
      export:
        uri: "https://api.datadoghq.eu"

您还可以更改向 Datadog 发送指标的时间间隔：

management:
  datadog:
    metrics:
      export:
        step: "30s"

Dynatrace

Dynatrace 提供两个指标摄取 API，这两个 API 都是为 Micrometer 实现的。您可在此处找到有关 Micrometer 指标摄取的 Dynatrace 文档。v1 名称空间中的配置属性仅在导出至 Timeseries v1 API 时适用。v2 名称空间中的配置属性仅适用于导出至 Metrics v2 API。请注意，此集成一次只能导出到 API 的 v1 或 v2 版本，优先选择 v2。如果在 v1 名称空间中设置了 device-id（v1 需要，但 v2 中不使用），则会向 v1 端点导出度量值。否则，将假定使用 v2 版本。

v2 API

您可以通过两种方式使用 v2 API。

自动配置

Dynatrace 自动配置适用于由 OneAgent 或 Dynatrace Operator for Kubernetes 监控的主机。
Local OneAgent： 如果主机上运行 OneAgent，指标会自动导出到本地 OneAgent 摄取端点。摄取端点会将指标转发到 Dynatrace 后台。
Dynatrace Kubernetes Operator： 在安装了 Dynatrace 操作员的 Kubernetes 中运行时，注册表会自动从操作员处获取端点 URI 和 API 标记。
这是默认行为，除了依赖于 io.micrometer:micrometer-registry-dynatrace 之外，无需其他特殊设置。

手动配置

如果没有自动配置功能，则需要 Metrics v2 API 的端点和 API 令牌。API 令牌必须设置有 “摄取度量”（metrics.ingest）权限。我们建议将令牌的范围限制在这一个权限内。必须确保端点 URI 包含路径（例如，/api/v2/metrics/ingest）：
Metrics API v2 ingest 端点的 URL 根据部署选项的不同而不同：

• SaaS: https://{your-environment-id}.live.dynatrace.com/api/v2/metrics/ingest
• Managed deployments: https://{your-domain}/e/{your-environment-id}/api/v2/metrics/ingest

下面的示例使用example环境 ID 配置指标导出：

management:
  dynatrace:
    metrics:
      export:
        uri: "https://example.live.dynatrace.com/api/v2/metrics/ingest"
        api-token: "YOUR_TOKEN"

使用 Dynatrace v2 API 时，可使用以下可选功能（更多详细信息请参阅 Dynatrace 文档）：

• 度量键前缀： 设置所有导出度量键的前缀。
• 使用 Dynatrace 元数据丰富度量： 如果 OneAgent 或 Dynatrace 操作员正在运行，则使用附加元数据（例如，有关主机、进程或 pod 的元数据）丰富度量。
• 默认维度： 指定添加到所有导出指标的键值对。如果使用 Micrometer 指定了具有相同键值的标签，它们会覆盖默认维度。
• 使用 Dynatrace 摘要工具： 在某些情况下，Micrometer Dynatrace 注册表创建的度量被拒绝。在 Micrometer 1.9.x 中，通过引入特定于 Dynatrace 的摘要工具解决了这一问题。只有在从 Micrometer 1.8.x 迁移到 1.9.x 时遇到问题时才可使用。
• 导出仪表元数据： 从 Micrometer 1.12.0 开始，Dynatrace 输出程序还将输出仪表元数据，如默认单位和描述。使用 export-meter-metadata 切换按钮可关闭此功能。

可以不指定 URI 和 API 标记，如下例所示。在这种情况下，将使用自动配置的端点：

management:
  dynatrace:
    metrics:
      export:
        # Specify uri and api-token here if not using the local OneAgent endpoint.
        v2:
          metric-key-prefix: "your.key.prefix"
          enrich-with-dynatrace-metadata: true
          default-dimensions:
            key1: "value1"
            key2: "value2"
          use-dynatrace-summary-instruments: true # (default: true)
          export-meter-metadata: true             # (default: true)

v1 API (旧版)

Dynatrace v1 API 指标注册中心通过使用 Timeseries v1 API 定期向配置的 URI 推送指标。为了与现有设置向后兼容，当设置了 device-id（v1 需要，但 v2 中不使用）时，指标会导出到 Timeseries v1 端点。要向 Dynatrace 导出指标，必须提供 API 标记、设备 ID 和 URI：

management:
  dynatrace:
    metrics:
      export:
        uri: "https://{your-environment-id}.live.dynatrace.com"
        api-token: "YOUR_TOKEN"
        v1:
          device-id: "YOUR_DEVICE_ID"

对于 v1 应用程序接口，您必须指定不含路径的基础环境 URI，因为 v1 端点路径会自动添加。

与版本无关的设置

除了 API 端点和令牌，您还可以更改向 Dynatrace 发送指标的时间间隔。默认导出间隔为 60 秒。下面的示例将导出间隔设置为 30 秒：

management:
  dynatrace:
    metrics:
      export:
        step: "30s"

有关如何为 Micrometer 设置 Dynatrace 输出程序的详细信息，请参阅 Micrometer 文档和 Dynatrace 文档。

Elastic

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

management:
  elastic:
    metrics:
      export:
        host: "https://elastic.example.com:8086"

Ganglia

默认情况下，度量指标会导出到本地计算机上运行的 Ganglia。您可以提供 Ganglia 服务器主机和端口，如下例所示：

management:
  ganglia:
    metrics:
      export:
        host: "ganglia.example.com"
        port: 9649

Graphite

默认情况下，度量指标会导出到本地计算机上运行的 Graphite。您可以提供 Graphite 服务器主机和端口，如下例所示：

management:
  graphite:
    metrics:
      export:
         host: "graphite.example.com"
         port: 9004

Micrometer 提供一个默认的 HierarchicalNameMapper，用于管理如何将仪表 ID 映射到平面层次名称。

要控制这种行为，请定义您的 GraphiteMeterRegistry 并提供您自己的 HierarchicalNameMapper。除非您定义自己的 GraphiteConfig 和 Clock Bean，否则我们会提供自动配置的 GraphiteConfig 和 Clock Bean：

import io.micrometer.core.instrument.Clock;
import io.micrometer.core.instrument.Meter;
import io.micrometer.core.instrument.config.NamingConvention;
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
import io.micrometer.graphite.GraphiteConfig;
import io.micrometer.graphite.GraphiteMeterRegistry;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyGraphiteConfiguration {
    
    

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

    private String toHierarchicalName(Meter.Id id, NamingConvention convention) {
    
    
        return ...
    }

}

Humio

默认情况下，Humio 注册表会定期将指标推送到 cloud.humio.com。要将指标导出到 SaaS Humio，必须提供 API 令牌：

management:
  humio:
    metrics:
      export:
        api-token: "YOUR_TOKEN"

您还应该配置一个或多个标记，以标识要推送指标的数据源：

management:
  humio:
    metrics:
      export:
        tags:
          alpha: "a"
          bravo: "b"

Influx

默认情况下，度量指标会以默认配置导出到本地计算机上运行的 Influx v1 实例。要将指标导出到 InfluxDB v2，请配置用于写入指标的 org、bucket 和身份验证令牌。您可以使用以下方式提供要使用的 Influx 服务器位置：

management:
  influx:
    metrics:
      export:
        uri: "https://influx.example.com:8086"

JMX

Micrometer 为 JMX 提供了一个分层映射，主要是作为在本地查看度量的一种廉价且便携的方式。默认情况下，度量指标会导出到 metrics JMX 域。您可以通过使用

management:
  jmx:
    metrics:
      export:
        domain: "com.example.app.metrics"

Micrometer 提供一个默认的 HierarchicalNameMapper，用于管理如何将仪表 ID 映射到平面层次名称。

要控制这种行为，请定义您的 JmxMeterRegistry 并提供您自己的 HierarchicalNameMapper。除非您自己定义，否则系统会提供自动配置的 JmxConfig 和 Clock Bean：

import io.micrometer.core.instrument.Clock;
import io.micrometer.core.instrument.Meter;
import io.micrometer.core.instrument.config.NamingConvention;
import io.micrometer.core.instrument.util.HierarchicalNameMapper;
import io.micrometer.jmx.JmxConfig;
import io.micrometer.jmx.JmxMeterRegistry;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyJmxConfiguration {
    
    

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

    private String toHierarchicalName(Meter.Id id, NamingConvention convention) {
    
    
        return ...
    }

}

KairosDB

默认情况下，度量指标会导出到本地计算机上运行的 KairosDB。您可以使用以下命令提供要使用的 KairosDB 服务器位置：

management:
  kairos:
    metrics:
      export:
        uri: "https://kairosdb.example.com:8080/api/v1/datapoints"

New Relic

New Relic 注册表会定期向 New Relic 推送指标。要将指标导出到 New Relic，您必须提供 API 密钥和账户 ID：

management:
  newrelic:
    metrics:
      export:
        api-key: "YOUR_KEY"
        account-id: "YOUR_ACCOUNT_ID"

您还可以更改向 New Relic 发送指标的时间间隔：

management:
  newrelic:
    metrics:
      export:
        step: "30s"

默认情况下，度量指标通过 REST 调用发布，但如果类路径上有 Java Agent API，也可以使用它：

management:
  newrelic:
    metrics:
      export:
        client-provider-type: "insights-agent"

最后，您可以通过定义自己的 NewRelicClientProvider Bean 来实现完全控制。

OpenTelemetry

默认情况下，度量指标会导出到本地计算机上运行的 OpenTelemetry。您可以使用以下方式提供要使用的 OpenTelemetry 指标端点的位置：

management:
  otlp:
    metrics:
      export:
        url: "https://otlp.example.com:4318/v1/metrics"

Prometheus

Prometheus 希望刮取或轮询单个应用程序实例的指标。Spring Boot 在 /actuator/prometheus 中提供了一个执行器端点，用于以适当的格式呈现 Prometheus scrape。

默认情况下，端点不可用，必须公开。更多详情，请参阅 “暴露端点”。

以下示例将 scrape_config 添加到 prometheus.yml 中：

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

还支持 Prometheus Exemplars。要启用此功能，必须有一个 SpanContextSupplier Bean。如果使用 Micrometer Tracing，则会自动为您配置，但您也可以根据需要创建自己的Bean。请查看 Prometheus 文档，因为该功能需要在 Prometheus 端明确启用，而且只有 OpenMetrics 格式才支持该功能。
对于可能存在时间不够长、无法进行刮擦的短暂作业或批处理作业，可以使用 Prometheus Pushgateway 支持将指标暴露给 Prometheus。要启用 Prometheus Pushgateway 支持，请在项目中添加以下依赖项：

<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient_pushgateway</artifactId>
</dependency>

当类路径上存在 Prometheus Pushgateway 依赖关系且 management.prometheus.metrics.export.pushgateway.enabled 属性设置为 true 时，将自动配置 PrometheusPushGatewayManager Bean。它会管理将度量指标推送到 Prometheus Pushgateway 的过程。
您可以使用 management.prometheus.metrics.export.pushgateway 下的属性来调整 PrometheusPushGatewayManager。对于高级配置，您还可以提供自己的 PrometheusPushGatewayManager Bean。

SignalFx

SignalFx 注册表会定期向 SignalFx 推送指标。要将指标导出到 SignalFx，必须提供访问令牌：

management:
  signalfx:
    metrics:
      export:
        access-token: "YOUR_ACCESS_TOKEN"

还可以更改向 SignalFx 发送指标的时间间隔：

management:
  signalfx:
    metrics:
      export:
        step: "30s"

Simple

Micrometer 随附一个简单的内存后端，如果没有配置其他注册表，该后端会自动用作备用。这样你就能看到度量端点收集了哪些度量。
一旦你使用了其他可用的后端，内存后端就会自动禁用。您也可以显式禁用它：

management:
  simple:
    metrics:
      export:
        enabled: false

Stackdriver

Stackdriver 注册表会定期向 Stackdriver 推送指标。要将指标导出到 SaaS Stackdriver，必须提供 Google Cloud 项目 ID：

management:
  stackdriver:
    metrics:
      export:
        project-id: "my-project"

您还可以更改向 Stackdriver 发送指标的时间间隔：

management:
  stackdriver:
    metrics:
      export:
        step: "30s"

StatsD

StatsD 注册表会急切地通过 UDP 向 StatsD 代理推送指标。默认情况下，指标会导出到本地机器上运行的 StatsD 代理。你可以使用以下命令提供要使用的 StatsD 代理主机、端口和协议：

management:
  statsd:
    metrics:
      export:
        host: "statsd.example.com"
        port: 9125
        protocol: "udp"

您还可以更改要使用的 StatsD 线路协议（默认为 Datadog）：

management:
  statsd:
    metrics:
      export:
        flavor: "etsy"

Wavefront

Wavefront 注册表会定期向 Wavefront 推送指标。如果直接向 Wavefront 导出度量，则必须提供 API 令牌：

management:
  wavefront:
    api-token: "YOUR_API_TOKEN"

或者，您也可以在环境中使用 Wavefront sidecar 或内部代理将指标数据转发到 Wavefront API 主机：

management:
  wavefront:
    uri: "proxy://localhost:2878"

如果将指标发布到 Wavefront 代理（如 Wavefront 文档所述），主机必须是 proxy://HOST:PORT 格式。

您还可以更改向 Wavefront 发送指标的时间间隔：

management:
  wavefront:
    metrics:
      export:
        step: "30s"

支持的度量标准和度量器

Spring Boot 可为各种技术提供自动度量注册。在大多数情况下，默认值提供了合理的度量，可以发布到任何支持的监控系统。

JVM 度量标准

自动配置通过使用核心 Micrometer 类来启用 JVM 度量。JVM 指标以 jvm. meter 名称发布。
提供以下 JVM 指标：

• 各种内存和缓冲池详情
• 与垃圾回收有关的统计
• 线程利用率
• 加载和卸载的类的数量
• JVM 版本信息
• JIT 编译时间

系统度量标准

自动配置通过使用核心 Micrometer 类实现系统度量。系统指标以 system.、process.和 disk.meter 名称发布。
提供以下系统指标：

• CPU 指标
• 文件描述符指标
• 正常运行时间指标（既包括应用程序的运行时间，也包括绝对启动时间的固定指标）
• 可用磁盘空间

应用启动度量标准

自动配置暴露了应用程序启动时间度量标准：

• application.started.time：启动应用程序所需的时间。
• application.ready.time：应用程序准备好为请求提供服务所用的时间。

度量指标用应用程序类的全称标记。

Logger 度量标准

自动配置可启用 Logback 和 Log4J2 的事件度量。详情发布在 log4j2.events. 或 logback.events.meter 名称下。

任务执行和调度度量标准

只要底层 ThreadPoolExecutor 可用，自动配置就能对所有可用的 ThreadPoolTaskExecutor 和 ThreadPoolTaskScheduler Bean 进行检测。度量指标由执行器名称标记，而执行器名称则来自于 Bean 名称。

JMS 度量标准

自动配置可对所有可用的 JmsTemplate Bean 和 @JmsListener 注释方法进行检测。这将分别产生 “jms.message.publish” 和 "jms.message.process"指标。有关生成的观测值的更多信息，请参阅 Spring Framework 参考文档。

Spring MVC 度量标准

自动配置可对 Spring MVC 控制器和功能处理程序处理的所有请求进行监测。默认情况下，生成的指标名称为 http.server.requests。您可以通过设置 management.observations.http.server.requests.name 属性来自定义名称。
有关生成的观测值的更多信息，请参阅 Spring Framework 参考文档。
要添加默认标记，请提供一个从 org.springframework.http.server.observation 包中扩展 DefaultServerRequestObservationConvention 的 @Bean。要替换默认标记，请提供一个实现 ServerRequestObservationConvention 的 @Bean。

在某些情况下，网络控制器处理的异常不会被记录为请求度量标记。应用程序可以选择将已处理的异常设置为请求属性，从而记录异常。

默认情况下，所有请求都会被处理。要自定义过滤器，请提供一个实现 FilterRegistrationBean<ServerHttpObservationFilter> 的 @Bean。

Spring WebFlux 度量标准

自动配置可对 Spring WebFlux 控制器和功能处理程序处理的所有请求进行检测。默认情况下，生成的指标名称为 http.server.requests。您可以通过设置 management.observations.http.server.requests.name 属性来自定义名称。
有关生成的观测值的更多信息，请参阅 Spring Framework 参考文档。
要添加默认标记，请提供一个从 org.springframework.http.server.reactive.observation 包中扩展 DefaultServerRequestObservationConvention 的 @Bean。要替换默认标记，请提供一个实现 ServerRequestObservationConvention 的 @Bean。

在某些情况下，控制器和处理函数中处理的异常不会被记录为请求度量标记。应用程序可以选择将已处理的异常设置为请求属性，从而记录异常。

Jersey Server 度量标准

自动配置可对 Jersey JAX-RS 实现处理的所有请求进行检测。默认情况下，生成的指标名称为 http.server.requests。您可以通过设置 management.observations.http.server.requests.name 属性来自定义名称。
默认情况下，Jersey 服务器指标会标记以下信息：

Tag	描述
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。

HTTP Client 度量指标

Spring Boot Actuator 管理 RestTemplate、WebClient 和 RestClient 的工具。为此，你必须注入自动配置的构建器，并使用它来创建实例：

• 用于 RestTemplate 的 RestTemplateBuilder
• 用于 WebClient 的 WebClient.Builder
• 用于 RestClient 的 RestClient.Builder

您还可以手动应用负责该工具的自定义器，即 ObservationRestTemplateCustomizer、ObservationWebClientCustomizer 和 ObservationRestClientCustomizer。
默认情况下，生成的度量指标名称为 http.client.requests。你可以通过设置 management.observations.http.client.requests.name 属性来自定义名称。
有关生成的观察结果的更多信息，请参阅 Spring Framework 参考文档。
要在使用 RestTemplate 或 RestClient 时自定义标签，请提供一个从 org.springframework.http.client.observation 包中实现 ClientRequestObservationConvention 的 @Bean。要在使用 WebClient 时自定义标签，请提供一个从 org.springframework.web.reactive.function.client 包中实现 ClientRequestObservationConvention 的 @Bean。