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

2024-01-09 10:41:58

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

度量标准

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

要了解 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 的 v1v2 版本,优先选择 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。除非您定义自己的 GraphiteConfigClock Bean,否则我们会提供自动配置的 GraphiteConfigClock 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。除非您自己定义,否则系统会提供自动配置的 JmxConfigClock 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 可用,自动配置就能对所有可用的 ThreadPoolTaskExecutorThreadPoolTaskScheduler 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请求方法(例如 GETPOST
outcome根据响应的状态代码得出的请求结果。1xx 为 INFORMATIONAL(信息),2xx 为 SUCCESS(成功),3xx 为 REDIRECTION(驳回),4xx 为 CLIENT_ERROR(客户错误),5xx 为 SERVER_ERROR(服务器错误)。
status响应的 HTTP 状态代码(例如 200500
uri如果可能,在变量替换之前的请求 URI 模板(例如,/api/person/{id})。

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

HTTP Client 度量指标

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

  • 用于 RestTemplateRestTemplateBuilder
  • 用于 WebClientWebClient.Builder
  • 用于 RestClientRestClient.Builder

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

文章来源:https://blog.csdn.net/qq_41939901/article/details/135411696
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。