生产就绪功能

1. 启用生产就绪功能

spring-boot-actuator模块提供了 Spring Boot 的所有生产就绪功能。 启用这些功能的推荐方法是添加对spring-boot-starter-actuator“入门”。spring-doc.cadn.net.cn

执行器的定义

执行器是一个制造术语,指的是用于移动或控制某物的机械装置。 执行器可以从微小的变化中产生大量的运动。spring-doc.cadn.net.cn

要将执行器添加到基于 Maven 的项目,请添加以下“Starter”依赖项:spring-doc.cadn.net.cn

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
</dependencies>

对于 Gradle,请使用以下声明:spring-doc.cadn.net.cn

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
}

2. 端点

执行器端点允许您监控应用程序并与之交互。 Spring Boot 包括许多内置端点,并允许您添加自己的端点。 例如,health端点提供基本的应用程序运行状况信息。spring-doc.cadn.net.cn

您可以启用或禁用每个单独的端点,并通过 HTTP 或 JMX 公开它们(使其可远程访问)。 当终结点同时启用和公开时,它被视为可用。 内置终结点仅在可用时才自动配置。 大多数应用程序选择通过 HTTP 进行公开,其中终结点的 ID 和前缀/actuator映射到 URL。 例如,默认情况下,healthendpoint 映射到/actuator/health.spring-doc.cadn.net.cn

要了解有关执行器的端点及其请求和响应格式的更多信息,请参阅单独的 API 文档(HTMLPDF)。

以下与技术无关的终结点可用:spring-doc.cadn.net.cn

身份证 描述

auditeventsspring-doc.cadn.net.cn

公开当前应用程序的审核事件信息。 需要AuditEventRepository豆。spring-doc.cadn.net.cn

beansspring-doc.cadn.net.cn

显示应用程序中所有 Spring Bean 的完整列表。spring-doc.cadn.net.cn

cachesspring-doc.cadn.net.cn

公开可用缓存。spring-doc.cadn.net.cn

conditionsspring-doc.cadn.net.cn

显示对配置类和自动配置类进行评估的条件,以及它们匹配或不匹配的原因。spring-doc.cadn.net.cn

configpropsspring-doc.cadn.net.cn

显示所有@ConfigurationProperties. 需要消毒。spring-doc.cadn.net.cn

envspring-doc.cadn.net.cn

公开 Spring 的ConfigurableEnvironment. 需要消毒。spring-doc.cadn.net.cn

flywayspring-doc.cadn.net.cn

显示已应用的任何 Flyway 数据库迁移。 需要一个或多个Flyway豆。spring-doc.cadn.net.cn

healthspring-doc.cadn.net.cn

显示应用程序运行状况信息。spring-doc.cadn.net.cn

httpexchangesspring-doc.cadn.net.cn

显示 HTTP 交换信息(默认情况下,最近 100 个 HTTP 请求-响应交换)。 需要HttpExchangeRepository豆。spring-doc.cadn.net.cn

infospring-doc.cadn.net.cn

显示任意应用程序信息。spring-doc.cadn.net.cn

integrationgraphspring-doc.cadn.net.cn

显示 Spring Integration 图。 需要依赖于spring-integration-core.spring-doc.cadn.net.cn

loggersspring-doc.cadn.net.cn

显示和修改应用程序中记录器的配置。spring-doc.cadn.net.cn

liquibasespring-doc.cadn.net.cn

显示已应用的任何 Liquibase 数据库迁移。 需要一个或多个Liquibase豆。spring-doc.cadn.net.cn

metricsspring-doc.cadn.net.cn

显示当前应用程序的“指标”信息。spring-doc.cadn.net.cn

mappingsspring-doc.cadn.net.cn

显示所有@RequestMapping路径。spring-doc.cadn.net.cn

quartzspring-doc.cadn.net.cn

显示有关 Quartz Scheduler 作业的信息。 需要消毒。spring-doc.cadn.net.cn

scheduledtasksspring-doc.cadn.net.cn

显示应用程序中的计划任务。spring-doc.cadn.net.cn

sessionsspring-doc.cadn.net.cn

允许从 Spring Session 支持的会话存储中检索和删除用户会话。 需要使用 Spring Session 的基于 servlet 的 Web 应用程序。spring-doc.cadn.net.cn

shutdownspring-doc.cadn.net.cn

允许正常关闭应用程序。 仅在使用罐装时有效。 默认禁用。spring-doc.cadn.net.cn

startupspring-doc.cadn.net.cn

显示由ApplicationStartup. 需要SpringApplication配置为BufferingApplicationStartup.spring-doc.cadn.net.cn

threaddumpspring-doc.cadn.net.cn

执行线程转储。spring-doc.cadn.net.cn

如果您的应用程序是 Web 应用程序(Spring MVC、Spring WebFlux 或 Jersey),则可以使用以下其他端点:spring-doc.cadn.net.cn

身份证 描述

heapdumpspring-doc.cadn.net.cn

返回堆转储文件。 在 HotSpot JVM 上,一个HPROF-format 文件。 在 OpenJ9 JVM 上,一个PHD-format 文件。spring-doc.cadn.net.cn

logfilespring-doc.cadn.net.cn

返回日志文件的内容(如果logging.file.namelogging.file.path属性已设置)。支持使用 HTTPRange标头来检索日志文件的部分内容。spring-doc.cadn.net.cn

prometheusspring-doc.cadn.net.cn

以 Prometheus 服务器可抓取的格式公开指标。需要依赖于micrometer-registry-prometheus.spring-doc.cadn.net.cn

2.1. 启用端点

默认情况下,除shutdown已启用。要配置端点的启用,请使用其management.endpoint.<id>.enabled财产。 以下示例启用shutdown端点:spring-doc.cadn.net.cn

性能
management.endpoint.shutdown.enabled=true
亚姆尔
management:
  endpoint:
    shutdown:
      enabled: true

如果您希望终端启用是选择加入而不是选择退出,请将management.endpoints.enabled-by-default属性设置为false并使用单个端点enabled属性以重新选择加入。以下示例启用info端点并禁用所有其他端点:spring-doc.cadn.net.cn

性能
management.endpoints.enabled-by-default=false
management.endpoint.info.enabled=true
亚姆尔
management:
  endpoints:
    enabled-by-default: false
  endpoint:
    info:
      enabled: true
禁用的端点将从应用程序上下文中完全删除。如果只想更改公开端点的技术,请使用includeexclude性能相反。

2.2. 公开端点

默认情况下,只有运行状况终结点通过 HTTP 和 JMX 公开。由于终结点可能包含敏感信息,因此应仔细考虑何时公开它们。spring-doc.cadn.net.cn

若要更改要公开的终结点,请使用以下特定于技术的includeexclude性能:spring-doc.cadn.net.cn

属性 默认值

management.endpoints.jmx.exposure.excludespring-doc.cadn.net.cn

management.endpoints.jmx.exposure.includespring-doc.cadn.net.cn

healthspring-doc.cadn.net.cn

management.endpoints.web.exposure.excludespring-doc.cadn.net.cn

management.endpoints.web.exposure.includespring-doc.cadn.net.cn

healthspring-doc.cadn.net.cn

include属性列出了公开的端点的 ID。 这exclude属性列出了不应公开的端点的 ID。 这exclude属性优先于include财产。 您可以配置includeexclude属性,其中包含端点 ID 列表。spring-doc.cadn.net.cn

例如,要仅公开healthinfoendpoints over JMX,请使用以下属性:spring-doc.cadn.net.cn

性能
management.endpoints.jmx.exposure.include=health,info
亚姆尔
management:
  endpoints:
    jmx:
      exposure:
        include: "health,info"

*可用于选择所有端点。 例如,要通过 HTTP 公开除envbeansendpoints,请使用以下属性:spring-doc.cadn.net.cn

性能
management.endpoints.web.exposure.include=*
management.endpoints.web.exposure.exclude=env,beans
亚姆尔
management:
  endpoints:
    web:
      exposure:
        include: "*"
        exclude: "env,beans"
*在 YAML 中具有特殊含义,因此如果要包含(或排除)所有端点,请务必添加引号。
如果应用程序公开,强烈建议同时保护终结点
如果要在端点公开时实现自己的策略,可以注册EndpointFilter豆。

2.3. 安全性

出于安全考虑,只有/health默认情况下,端点通过 HTTP 公开。 您可以使用management.endpoints.web.exposure.include属性来配置公开的端点。spring-doc.cadn.net.cn

在设置management.endpoints.web.exposure.include,确保公开的执行器不包含敏感信息,通过将它们放置在防火墙后面来保护,或者由 Spring Security 之类的东西保护。

如果 Spring Security 在类路径上并且没有其他SecurityFilterChainbean 存在,除/health由 Spring Boot 自动配置保护。 如果定义自定义SecurityFilterChainbean,Spring Boot 自动配置会回退,让你完全控制执行器访问规则。spring-doc.cadn.net.cn

如果您希望为 HTTP 端点配置自定义安全性(例如,仅允许具有特定角色的用户访问它们),Spring Boot 提供了一些方便的RequestMatcher可以与 Spring Security 结合使用的对象。spring-doc.cadn.net.cn

典型的 Spring Security 配置可能类似于以下示例:spring-doc.cadn.net.cn

Java
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().hasRole("ENDPOINT_ADMIN"));
        http.httpBasic(withDefaults());
        return http.build();
    }

}
Kotlin
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.Customizer.withDefaults
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
            requests.anyRequest().hasRole("ENDPOINT_ADMIN")
        }
        http.httpBasic(withDefaults())
        return http.build()
    }

}

前面的示例使用EndpointRequest.toAnyEndpoint()将请求与任何端点匹配,然后确保所有端点都有ENDPOINT_ADMIN角色。 其他几种匹配器方法也可在EndpointRequest. 有关详细信息,请参阅 API 文档(HTMLPDF)。spring-doc.cadn.net.cn

如果将应用程序部署在防火墙后面,则可能希望无需身份验证即可访问所有执行器端点。 您可以通过更改management.endpoints.web.exposure.include属性,如下所示:spring-doc.cadn.net.cn

性能
management.endpoints.web.exposure.include=*
亚姆尔
management:
  endpoints:
    web:
      exposure:
        include: "*"

此外,如果存在 Spring Security,则需要添加自定义安全配置,允许对端点进行未经身份验证的访问,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration(proxyBeanMethods = false)
public class MySecurityConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint());
        http.authorizeHttpRequests((requests) -> requests.anyRequest().permitAll());
        return http.build();
    }

}
Kotlin
import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain

@Configuration(proxyBeanMethods = false)
class MySecurityConfiguration {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http.securityMatcher(EndpointRequest.toAnyEndpoint()).authorizeHttpRequests { requests ->
            requests.anyRequest().permitAll()
        }
        return http.build()
    }

}
在上述两个示例中,配置仅适用于执行器端点。 由于 Spring Boot 的安全配置在存在任何SecurityFilterChainbean,您需要配置一个额外的SecurityFilterChainbean 具有适用于应用程序其余部分的规则。

2.3.1. 跨站请求伪造保护

由于 Spring Boot 依赖于 Spring Security 的默认值,因此默认情况下打开 CSRF 保护。 这意味着需要POST(关闭和记录器端点),一个PUTDELETE使用默认安全配置时,收到 403(禁止)错误。spring-doc.cadn.net.cn

我们建议仅在创建由非浏览器客户端使用的服务时完全禁用 CSRF 保护。

您可以在 Spring Security 参考指南中找到有关 CSRF 保护的其他信息。spring-doc.cadn.net.cn

2.4. 配置端点

端点会自动缓存对不采用任何参数的读取作的响应。 要配置端点缓存响应的时间量,请使用其cache.time-to-live财产。 以下示例设置beans端点的缓存到 10 秒:spring-doc.cadn.net.cn

性能
management.endpoint.beans.cache.time-to-live=10s
亚姆尔
management:
  endpoint:
    beans:
      cache:
        time-to-live: "10s"
management.endpoint.<name>prefix 唯一标识正在配置的终结点。

2.5. 清理敏感值

返回的信息/env,/configprops/quartz端点可能是敏感的,因此默认情况下,值始终完全清理(替换为 )。******spring-doc.cadn.net.cn

只有在以下情况下,才能以未经清理的形式查看值:spring-doc.cadn.net.cn

show-values可以为可清理的端点配置为以下值之一:spring-doc.cadn.net.cn

对于 HTTP 端点,如果用户已进行身份验证并具有由端点的 roles 属性配置的角色,则该用户被视为已授权。 默认情况下,任何经过身份验证的用户都是授权的。spring-doc.cadn.net.cn

对于 JMX 端点,所有用户始终获得授权。spring-doc.cadn.net.cn

以下示例允许所有使用adminrole 从/env端点的原始形式。 未经授权的用户,或没有adminrole,将仅看到经过清理的值。spring-doc.cadn.net.cn

性能
management.endpoint.env.show-values=WHEN_AUTHORIZED
management.endpoint.env.roles=admin
亚姆尔
management:
  endpoint:
    env:
      show-values: WHEN_AUTHORIZED
      roles: "admin"
此示例假设没有SanitizingFunctionbean 已被定义。

2.6. 执行器 Web 端点的超介质

将添加一个“发现页面”,其中包含指向所有端点的链接。 “发现页面”可在/actuator默认情况下。spring-doc.cadn.net.cn

若要禁用“发现页”,请将以下属性添加到应用程序属性:spring-doc.cadn.net.cn

性能
management.endpoints.web.discovery.enabled=false
亚姆尔
management:
  endpoints:
    web:
      discovery:
        enabled: false

配置自定义管理上下文路径后,“发现页面”会自动从/actuator到管理上下文的根目录。例如,如果管理上下文路径为/management,则发现页面可从/management. 当管理上下文路径设置为 时,将禁用发现页面,以防止与其他映射发生冲突的可能性。/spring-doc.cadn.net.cn

2.7. CORS 支持

跨域资源共享 (CORS) 是 W3C 规范,允许您以灵活的方式指定授权的跨域请求类型。如果您使用 Spring MVC 或 Spring WebFlux,则可以配置 Actuator 的 Web 端点以支持此类场景。spring-doc.cadn.net.cn

默认情况下,CORS 支持处于禁用状态,并且仅在将management.endpoints.web.cors.allowed-origins财产。 以下配置允许GETPOST来自example.com域:spring-doc.cadn.net.cn

性能
management.endpoints.web.cors.allowed-origins=https://example.com
management.endpoints.web.cors.allowed-methods=GET,POST
亚姆尔
management:
  endpoints:
    web:
      cors:
        allowed-origins: "https://example.com"
        allowed-methods: "GET,POST"
CorsEndpointProperties获取完整的选项列表。

2.8. 实现自定义端点

如果您添加@Bean注释为@Endpoint,任何用@ReadOperation,@WriteOperation@DeleteOperation通过 JMX 自动公开,在 Web 应用程序中也通过 HTTP 自动公开。 可以使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 公开端点。 如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。spring-doc.cadn.net.cn

以下示例公开了返回自定义对象的读取作:spring-doc.cadn.net.cn

Java
@ReadOperation
public CustomData getData() {
    return new CustomData("test", 5);
}
Kotlin
@ReadOperation
fun getData(): CustomData {
    return CustomData("test", 5)
}

您还可以使用@JmxEndpoint@WebEndpoint. 这些端点仅限于各自的技术。 例如@WebEndpoint仅通过 HTTP 公开,而不是通过 JMX。spring-doc.cadn.net.cn

您可以使用以下命令编写特定于技术的扩展@EndpointWebExtension@EndpointJmxExtension. 这些注释允许您提供特定于技术的作来扩充现有端点。spring-doc.cadn.net.cn

最后,如果您需要访问特定于 Web 框架的功能,您可以实现 servlet 或 Spring@Controller@RestController端点的代价是它们无法通过 JMX 或使用不同的 Web 框架时使用。spring-doc.cadn.net.cn

2.8.1. 接收输入

端点上的作通过其参数接收输入。 通过 Web 公开时,这些参数的值取自 URL 的查询参数和 JSON 请求正文。 当通过 JMX 公开时,参数将映射到 MBean作的参数。 默认情况下,参数是必需的。 可以通过使用以下任一注释来使它们成为可选的@javax.annotation.Nullable@org.springframework.lang.Nullable.spring-doc.cadn.net.cn

您可以将 JSON 请求正文中的每个根属性映射到终结点的参数。 考虑以下 JSON 请求正文:spring-doc.cadn.net.cn

{
    "name": "test",
    "counter": 42
}

您可以使用它来调用写入作,该作需要String nameint counter参数,如以下示例所示:spring-doc.cadn.net.cn

Java
@WriteOperation
public void updateData(String name, int counter) {
    // injects "test" and 42
}
Kotlin
@WriteOperation
fun updateData(name: String?, counter: Int) {
    // injects "test" and 42
}
由于终结点与技术无关,因此只能在方法签名中指定简单类型。 特别是,使用CustomData定义namecounter不支持属性。
为了让输入映射到作方法的参数,实现端点的 Java 代码应该使用-parameters,并且实现端点的 Kotlin 代码应使用-java-parameters. 如果您使用 Spring Boot 的 Gradle 插件或使用 Maven 和spring-boot-starter-parent.
输入类型转换

如有必要,传递给端点作方法的参数会自动转换为所需的类型。 在调用作方法之前,通过 JMX 或 HTTP 接收到的输入将使用ApplicationConversionService以及任何ConverterGenericConverter符合条件的豆子@EndpointConverter.spring-doc.cadn.net.cn

2.8.2. 自定义 Web 端点

@Endpoint,@WebEndpoint@EndpointWebExtension使用 Jersey、Spring MVC 或 Spring WebFlux 通过 HTTP 自动公开。 如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。spring-doc.cadn.net.cn

Web 端点请求谓词

为公开 Web 的终结点上的每个作自动生成请求谓词。spring-doc.cadn.net.cn

路径

谓词的路径由端点的 ID 和 Web 公开的端点的基本路径确定。 默认基本路径为/actuator. 例如,ID 为sessions使用/actuator/sessions作为谓词中的路径。spring-doc.cadn.net.cn

您可以通过在作方法的一个或多个参数上添加注释来进一步自定义路径@Selector. 此类参数将作为路径变量添加到路径谓词中。 调用端点作时,变量的值将传递到作方法中。 如果要捕获所有剩余的路径元素,可以将@Selector(Match=ALL_REMAINING)添加到最后一个参数,并使其成为与String[].spring-doc.cadn.net.cn

HTTP 方法

谓词的HTTP方法由作类型决定,如下表所示:spring-doc.cadn.net.cn

操作 HTTP 方法

@ReadOperationspring-doc.cadn.net.cn

GETspring-doc.cadn.net.cn

@WriteOperationspring-doc.cadn.net.cn

POSTspring-doc.cadn.net.cn

@DeleteOperationspring-doc.cadn.net.cn

DELETEspring-doc.cadn.net.cn

消耗

对于一个@WriteOperation(HTTPPOST)使用请求正文的consumes谓词的子句是application/vnd.spring-boot.actuator.v2+json, application/json. 对于所有其他作,consumes子句为空。spring-doc.cadn.net.cn

生产

produces谓词的子句可以由produces属性的@DeleteOperation,@ReadOperation@WriteOperation附注。 该属性是可选的。如果不使用它,则produces子句是自动确定的。spring-doc.cadn.net.cn

如果作方法返回voidVoidproduces子句为空。如果作方法返回org.springframework.core.io.Resourceproduces子句是application/octet-stream. 对于所有其他作,produces子句是application/vnd.spring-boot.actuator.v2+json, application/json.spring-doc.cadn.net.cn

Web 端点响应状态

终结点作的默认响应状态取决于作类型(读取、写入或删除)以及作返回的内容(如果有)。spring-doc.cadn.net.cn

如果@ReadOperation返回一个值,响应状态将为 200(正常)。如果它不返回值,则响应状态将为 404(未找到)。spring-doc.cadn.net.cn

如果@WriteOperation@DeleteOperation返回一个值,响应状态将为 200(正常)。如果它不返回值,则响应状态将为 204(无内容)。spring-doc.cadn.net.cn

如果调用作时没有必需参数或参数无法转换为所需类型,则不会调用作方法,响应状态将为 400(错误请求)。spring-doc.cadn.net.cn

Web 端点范围请求

您可以使用 HTTP 范围请求来请求 HTTP 资源的一部分。使用 Spring MVC 或 Spring Web Flux 时,返回org.springframework.core.io.Resource自动支持范围请求。spring-doc.cadn.net.cn

使用 Jersey 时不支持范围请求。
Web 端点安全

对 Web 端点或特定于 Web 的端点扩展的作可以接收当前java.security.Principalorg.springframework.boot.actuate.endpoint.SecurityContext作为方法参数。 前者通常与@Nullable为经过身份验证和未经身份验证的用户提供不同的行为。 后者通常用于通过使用其isUserInRole(String)方法。spring-doc.cadn.net.cn

2.8.3. Servlet 端点

Servlet 可以通过实现一个用@ServletEndpoint这也实现了Supplier<EndpointServlet>. Servlet 端点提供了与 Servlet 容器的更深入的集成,但以牺牲可移植性为代价。 它们旨在用于将现有 servlet 公开为端点。 对于新端点,@Endpoint@WebEndpoint应尽可能优先使用注释。spring-doc.cadn.net.cn

2.8.4. 控制器端点

您可以使用@ControllerEndpoint@RestControllerEndpoint实现仅由 Spring MVC 或 Spring WebFlux 公开的端点。 使用 Spring MVC 和 Spring WebFlux 的标准注释映射方法,例如@RequestMapping@GetMapping,端点的 ID 用作路径的前缀。 控制器端点提供了与 Spring 的 Web 框架的更深入的集成,但以牺牲可移植性为代价。 这@Endpoint@WebEndpoint应尽可能优先使用注释。spring-doc.cadn.net.cn

2.9. 健康信息

您可以使用运行状况信息来检查正在运行的应用程序的状态。 监控软件通常使用它来在生产系统出现故障时向某人发出警报。 由healthendpoint 依赖于management.endpoint.health.show-detailsmanagement.endpoint.health.show-components属性,可以使用以下值之一进行配置:spring-doc.cadn.net.cn

名称 描述

neverspring-doc.cadn.net.cn

从不显示详细信息。spring-doc.cadn.net.cn

when-authorizedspring-doc.cadn.net.cn

详细信息仅显示给授权用户。可以使用management.endpoint.health.roles.spring-doc.cadn.net.cn

alwaysspring-doc.cadn.net.cn

详细信息将显示给所有用户。spring-doc.cadn.net.cn

默认值为never. 当用户处于一个或多个端点的角色时,该用户被视为已授权。如果端点没有配置角色(默认),则所有经过身份验证的用户都被视为已授权。您可以使用management.endpoint.health.roles财产。spring-doc.cadn.net.cn

如果您已保护您的应用程序并希望使用always,则安全配置必须允许经过身份验证和未经身份验证的用户访问运行状况终结点。

健康信息是从HealthContributorRegistry(默认情况下,所有HealthContributorApplicationContext). Spring Boot 包括许多自动配置的HealthContributors,您也可以编写自己的。spring-doc.cadn.net.cn

一个HealthContributor可以是HealthIndicatorCompositeHealthContributor. 一个HealthIndicator提供实际的健康信息,包括Status. 一个CompositeHealthContributor提供其他HealthContributors. 总之,参与者形成一个树结构来表示整个系统运行状况。spring-doc.cadn.net.cn

默认情况下,最终系统运行状况由StatusAggregator,它对每个HealthIndicator基于状态的有序列表。排序列表中的第一个状态用作整体运行状况。如果没有HealthIndicator返回已知的状态StatusAggregatorUNKNOWN状态。spring-doc.cadn.net.cn

您可以使用HealthContributorRegistry在运行时注册和注销运行状况指标。

2.9.1. 自动配置的 HealthIndicators

在适当的时候,Spring Boot 会自动配置HealthIndicators如下表所示。 您还可以通过配置来启用或禁用选定的指标management.health.key.enabled, 使用key如下表所示:spring-doc.cadn.net.cn

钥匙 名称 描述

cassandraspring-doc.cadn.net.cn

CassandraDriverHealthIndicatorspring-doc.cadn.net.cn

检查 Cassandra 数据库是否已启动。spring-doc.cadn.net.cn

couchbasespring-doc.cadn.net.cn

CouchbaseHealthIndicatorspring-doc.cadn.net.cn

检查 Couchbase 集群是否已启动。spring-doc.cadn.net.cn

dbspring-doc.cadn.net.cn

DataSourceHealthIndicatorspring-doc.cadn.net.cn

检查与DataSource可以获得。spring-doc.cadn.net.cn

diskspacespring-doc.cadn.net.cn

DiskSpaceHealthIndicatorspring-doc.cadn.net.cn

检查磁盘空间不足。spring-doc.cadn.net.cn

elasticsearchspring-doc.cadn.net.cn

ElasticsearchRestClientHealthIndicatorspring-doc.cadn.net.cn

检查 Elasticsearch 集群是否已启动。spring-doc.cadn.net.cn

hazelcastspring-doc.cadn.net.cn

HazelcastHealthIndicatorspring-doc.cadn.net.cn

检查 Hazelcast 服务器是否已启动。spring-doc.cadn.net.cn

influxdbspring-doc.cadn.net.cn

InfluxDbHealthIndicatorspring-doc.cadn.net.cn

检查 InfluxDB 服务器是否已启动。spring-doc.cadn.net.cn

jmsspring-doc.cadn.net.cn

JmsHealthIndicatorspring-doc.cadn.net.cn

检查 JMS 代理是否已启动。spring-doc.cadn.net.cn

ldapspring-doc.cadn.net.cn

LdapHealthIndicatorspring-doc.cadn.net.cn

检查 LDAP 服务器是否已启动。spring-doc.cadn.net.cn

mailspring-doc.cadn.net.cn

MailHealthIndicatorspring-doc.cadn.net.cn

检查邮件服务器是否已启动。spring-doc.cadn.net.cn

mongospring-doc.cadn.net.cn

MongoHealthIndicatorspring-doc.cadn.net.cn

检查 Mongo 数据库是否已启动。spring-doc.cadn.net.cn

neo4jspring-doc.cadn.net.cn

Neo4jHealthIndicatorspring-doc.cadn.net.cn

检查 Neo4j 数据库是否已启动。spring-doc.cadn.net.cn

pingspring-doc.cadn.net.cn

PingHealthIndicatorspring-doc.cadn.net.cn

始终以UP.spring-doc.cadn.net.cn

rabbitspring-doc.cadn.net.cn

RabbitHealthIndicatorspring-doc.cadn.net.cn

检查 Rabbit 服务器是否已启动。spring-doc.cadn.net.cn

redisspring-doc.cadn.net.cn

RedisHealthIndicatorspring-doc.cadn.net.cn

检查 Redis 服务器是否已启动。spring-doc.cadn.net.cn

您可以通过设置management.health.defaults.enabled财产。

附加HealthIndicators可用,但默认情况下未启用:spring-doc.cadn.net.cn

钥匙 名称 描述

livenessstatespring-doc.cadn.net.cn

LivenessStateHealthIndicatorspring-doc.cadn.net.cn

公开“活动”应用程序可用性状态。spring-doc.cadn.net.cn

readinessstatespring-doc.cadn.net.cn

ReadinessStateHealthIndicatorspring-doc.cadn.net.cn

公开“就绪”应用程序可用性状态。spring-doc.cadn.net.cn

2.9.2. 编写自定义 HealthIndicators

要提供自定义运行状况信息,您可以注册实现HealthIndicator接口。 您需要提供health()方法并返回一个Health响应。 这Health响应应包括状态,并且可以选择包含要显示的其他详细信息。以下代码显示了一个示例HealthIndicator实现:spring-doc.cadn.net.cn

Java
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyHealthIndicator implements HealthIndicator {

    @Override
    public Health health() {
        int errorCode = check();
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build();
        }
        return Health.up().build();
    }

    private int check() {
        // perform some specific health check
        return ...
    }

}
Kotlin
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.HealthIndicator
import org.springframework.stereotype.Component

@Component
class MyHealthIndicator : HealthIndicator {

    override fun health(): Health {
        val errorCode = check()
        if (errorCode != 0) {
            return Health.down().withDetail("Error Code", errorCode).build()
        }
        return Health.up().build()
    }

    private fun check(): Int {
        // perform some specific health check
        return  ...
    }

}
给定的标识符HealthIndicator是 bean 的名称,不带HealthIndicator后缀,如果存在。 在前面的示例中,运行状况信息在名为my.
运行状况指示器通常通过 HTTP 调用,需要在任何连接超时之前做出响应。 Spring Boot 将记录任何响应时间超过 10 秒的运行状况指示器的警告消息。 如果要配置此阈值,可以使用management.endpoint.health.logging.slow-indicator-threshold财产。

除了 Spring Boot 的预定义Status类型Health可以返回自定义Status这代表一种新的系统状态。 在这种情况下,您还需要提供StatusAggregator接口,或者您必须使用management.endpoint.health.status.orderconfiguration 属性。spring-doc.cadn.net.cn

例如,假设新的Status代码为FATAL正在您的一个HealthIndicator实现。 要配置严重性顺序,请将以下属性添加到应用程序属性:spring-doc.cadn.net.cn

性能
management.endpoint.health.status.order=fatal,down,out-of-service,unknown,up
亚姆尔
management:
  endpoint:
    health:
      status:
        order: "fatal,down,out-of-service,unknown,up"

响应中的 HTTP 状态代码反映了整体运行状况。 默认情况下,OUT_OF_SERVICEDOWN映射到 503。 任何未映射的运行状况,包括UP,映射到 200。 如果通过 HTTP 访问运行状况终结点,您可能还需要注册自定义状态映射。 配置自定义映射会禁用DOWNOUT_OF_SERVICE. 如果要保留默认映射,则必须显式配置它们以及任何自定义映射。 例如,以下属性映射FATAL设置为 503(服务不可用),并保留DOWNOUT_OF_SERVICE:spring-doc.cadn.net.cn

性能
management.endpoint.health.status.http-mapping.down=503
management.endpoint.health.status.http-mapping.fatal=503
management.endpoint.health.status.http-mapping.out-of-service=503
亚姆尔
management:
  endpoint:
    health:
      status:
        http-mapping:
          down: 503
          fatal: 503
          out-of-service: 503
如果您需要更多控制,可以定义自己的控制HttpCodeStatusMapper豆。

下表显示了内置状态的默认状态映射:spring-doc.cadn.net.cn

地位 映射

DOWNspring-doc.cadn.net.cn

SERVICE_UNAVAILABLE (503)spring-doc.cadn.net.cn

OUT_OF_SERVICEspring-doc.cadn.net.cn

SERVICE_UNAVAILABLE (503)spring-doc.cadn.net.cn

UPspring-doc.cadn.net.cn

默认情况下没有映射,因此 HTTP 状态为200spring-doc.cadn.net.cn

UNKNOWNspring-doc.cadn.net.cn

默认情况下没有映射,因此 HTTP 状态为200spring-doc.cadn.net.cn

2.9.3. 反应性健康指标

对于响应式应用程序,例如那些使用 Spring WebFlux 的应用程序,ReactiveHealthContributor提供用于获取应用程序运行状况的非阻塞协定。 类似于传统的HealthContributor,健康信息是从ReactiveHealthContributorRegistry(默认情况下,所有HealthContributorReactiveHealthContributorApplicationContext). 定期HealthContributors不检查响应式 API 的 API 在弹性调度程序上执行。spring-doc.cadn.net.cn

在响应式应用程序中,您应该使用ReactiveHealthContributorRegistry在运行时注册和注销运行状况指标。 如果您需要注册常规HealthContributor,你应该用ReactiveHealthContributor#adapt.

要从响应式 API 提供自定义运行状况信息,您可以注册实现ReactiveHealthIndicator接口。 以下代码显示了一个示例ReactiveHealthIndicator实现:spring-doc.cadn.net.cn

Java
import reactor.core.publisher.Mono;

import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.ReactiveHealthIndicator;
import org.springframework.stereotype.Component;

@Component
public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {

    @Override
    public Mono<Health> health() {
        return doHealthCheck().onErrorResume((exception) ->
            Mono.just(new Health.Builder().down(exception).build()));
    }

    private Mono<Health> doHealthCheck() {
        // perform some specific health check
        return ...
    }

}
Kotlin
import org.springframework.boot.actuate.health.Health
import org.springframework.boot.actuate.health.ReactiveHealthIndicator
import org.springframework.stereotype.Component
import reactor.core.publisher.Mono

@Component
class MyReactiveHealthIndicator : ReactiveHealthIndicator {

    override fun health(): Mono<Health> {
        return doHealthCheck()!!.onErrorResume { exception: Throwable? ->
            Mono.just(Health.Builder().down(exception).build())
        }
    }

    private fun doHealthCheck(): Mono<Health>? {
        // perform some specific health check
        return  ...
    }

}
要自动处理错误,请考虑从AbstractReactiveHealthIndicator.

2.9.4. 自动配置的 ReactiveHealthIndicators

在适当的情况下,Spring Boot 会自动配置以下内容ReactiveHealthIndicators:spring-doc.cadn.net.cn

钥匙 名称 描述

cassandraspring-doc.cadn.net.cn

CassandraDriverReactiveHealthIndicatorspring-doc.cadn.net.cn

检查 Cassandra 数据库是否已启动。spring-doc.cadn.net.cn

couchbasespring-doc.cadn.net.cn

CouchbaseReactiveHealthIndicatorspring-doc.cadn.net.cn

检查 Couchbase 集群是否已启动。spring-doc.cadn.net.cn

elasticsearchspring-doc.cadn.net.cn

ElasticsearchReactiveHealthIndicatorspring-doc.cadn.net.cn

检查 Elasticsearch 集群是否已启动。spring-doc.cadn.net.cn

mongospring-doc.cadn.net.cn

MongoReactiveHealthIndicatorspring-doc.cadn.net.cn

检查 Mongo 数据库是否已启动。spring-doc.cadn.net.cn

neo4jspring-doc.cadn.net.cn

Neo4jReactiveHealthIndicatorspring-doc.cadn.net.cn

检查 Neo4j 数据库是否已启动。spring-doc.cadn.net.cn

redisspring-doc.cadn.net.cn

RedisReactiveHealthIndicatorspring-doc.cadn.net.cn

检查 Redis 服务器是否已启动。spring-doc.cadn.net.cn

如有必要,反应指示器取代常规指示器。 此外,任何HealthIndicator未显式处理的自动包装。

2.9.5. 健康组

有时将健康指标组织成可用于不同目的的组很有用。spring-doc.cadn.net.cn

要创建运行状况指示器组,您可以使用management.endpoint.health.group.<name>属性,并指定运行状况指示器 ID 列表,以includeexclude. 例如,要创建仅包含数据库指示器的组,您可以定义以下内容:spring-doc.cadn.net.cn

性能
management.endpoint.health.group.custom.include=db
亚姆尔
management:
  endpoint:
    health:
      group:
        custom:
          include: "db"

同样,要创建一个从组中排除数据库指示器并包括所有其他指示器的组,您可以定义以下内容:spring-doc.cadn.net.cn

性能
management.endpoint.health.group.custom.exclude=db
亚姆尔
management:
  endpoint:
    health:
      group:
        custom:
          exclude: "db"

默认情况下,如果运行状况组包含或排除不存在的运行状况指示器,则启动将失败。 要禁用此行为,请management.endpoint.health.validate-group-membershipfalse.spring-doc.cadn.net.cn

默认情况下,组继承相同的StatusAggregatorHttpCodeStatusMapper设置作为系统运行状况。 但是,您也可以按组定义这些值。 您还可以覆盖show-detailsroles属性(如果需要):spring-doc.cadn.net.cn

性能
management.endpoint.health.group.custom.show-details=when-authorized
management.endpoint.health.group.custom.roles=admin
management.endpoint.health.group.custom.status.order=fatal,up
management.endpoint.health.group.custom.status.http-mapping.fatal=500
management.endpoint.health.group.custom.status.http-mapping.out-of-service=500
亚姆尔
management:
  endpoint:
    health:
      group:
        custom:
          show-details: "when-authorized"
          roles: "admin"
          status:
            order: "fatal,up"
            http-mapping:
              fatal: 500
              out-of-service: 500
您可以使用@Qualifier("groupname")如果您需要注册自定义StatusAggregatorHttpCodeStatusMapper用于组的豆子。

运行状况组还可以包含/排除CompositeHealthContributor. 您还可以仅包含/排除CompositeHealthContributor. 这可以使用组件的完全限定名称来完成,如下所示:spring-doc.cadn.net.cn

management.endpoint.health.group.custom.include="test/primary"
management.endpoint.health.group.custom.exclude="test/primary/b"

在上面的示例中,custom组将包括HealthContributor与名称primary它是复合材料的一个组成部分test. 这里primary本身是一个复合,而HealthContributor与名称b将被排除在custom群。spring-doc.cadn.net.cn

可以在主端口或管理端口上的附加路径上提供运行状况组。 这在 Kubernetes 等云环境中非常有用,在云环境中,出于安全目的,为执行器端点使用单独的管理端口是很常见的。 使用单独的端口可能会导致运行状况检查不可靠,因为即使运行状况检查成功,主应用程序也可能无法正常工作。 可以配置运行状况组的其他路径,如下所示:spring-doc.cadn.net.cn

management.endpoint.health.group.live.additional-path="server:/healthz"

这将使live运行状况组在主服务器端口上可用,位于/healthz. 前缀是强制性的,必须是server:(代表主服务器端口)或management:(表示管理端口(如果已配置)。 路径必须是单个路径段。spring-doc.cadn.net.cn

2.9.6. 数据源运行状况

DataSource运行状况指示器显示标准数据源和路由数据源 Bean 的运行状况。 路由数据源的运行状况包括其每个目标数据源的运行状况。 在运行状况终结点的响应中,每个路由数据源的目标都使用其路由键命名。 如果您不想在指标的输出中包含路由数据源,请将management.health.db.ignore-routing-data-sourcestrue.spring-doc.cadn.net.cn

2.10. Kubernetes 探针

部署在 Kubernetes 上的应用程序可以使用容器探针提供有关其内部状态的信息。 根据您的 Kubernetes 配置,kubelet 会调用这些探针并对结果做出反应。spring-doc.cadn.net.cn

默认情况下,Spring Boot 管理应用程序可用性状态。 如果部署在 Kubernetes 环境中,执行器会从ApplicationAvailability接口,并在专用的运行状况指标中使用该信息:LivenessStateHealthIndicatorReadinessStateHealthIndicator. 这些指示器显示在全局运行状况终结点 ("/actuator/health"). 它们还通过使用运行状况组作为单独的 HTTP 探测公开:"/actuator/health/liveness""/actuator/health/readiness".spring-doc.cadn.net.cn

然后,您可以使用以下端点信息配置 Kubernetes 基础架构:spring-doc.cadn.net.cn

livenessProbe:
  httpGet:
    path: "/actuator/health/liveness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...

readinessProbe:
  httpGet:
    path: "/actuator/health/readiness"
    port: <actuator-port>
  failureThreshold: ...
  periodSeconds: ...
<actuator-port>应设置为执行器端点可用的端口。 它可以是主 Web 服务器端口,也可以是单独的管理端口,如果"management.server.port"属性已设置。

仅当应用程序在 Kubernetes 环境中运行时,才会自动启用这些运行状况组。 您可以使用management.endpoint.health.probes.enabledconfiguration 属性。spring-doc.cadn.net.cn

如果应用程序启动时间超过配置的活跃期,Kubernetes 会提到"startupProbe"作为可能的解决方案。 一般来说,"startupProbe"这里不一定需要,因为"readinessProbe"失败,直到所有启动任务完成。 这意味着您的应用程序在准备就绪之前不会接收流量。 但是,如果您的应用程序需要很长时间才能启动,请考虑使用"startupProbe"以确保 Kubernetes 不会在应用程序启动过程中终止您的应用程序。 请参阅描述探测在应用程序生命周期中如何运行的部分。

如果执行器端点部署在单独的管理上下文中,则端点不会使用与主应用程序相同的 Web 基础结构(端口、连接池、框架组件)。 在这种情况下,即使主应用程序无法正常工作(例如,它无法接受新连接),探测检查也可能成功。 因此,最好将livenessreadiness主服务器端口上可用的运行状况组。 这可以通过设置以下属性来完成:spring-doc.cadn.net.cn

management.endpoint.health.probes.add-additional-paths=true

这将使liveness团体可在以下位置购买/livezreadiness团体可在以下位置购买/readyz在主服务器端口上。 可以使用additional-path属性,请参阅运行状况组了解详细信息。spring-doc.cadn.net.cn

2.10.1. 使用 Kubernetes 探针检查外部状态

执行器将“活动”和“就绪”探测配置为运行状况组。 这意味着所有运行状况组功能都可供他们使用。 例如,您可以配置其他运行状况指示器:spring-doc.cadn.net.cn

性能
management.endpoint.health.group.readiness.include=readinessState,customCheck
亚姆尔
management:
  endpoint:
    health:
      group:
        readiness:
          include: "readinessState,customCheck"

默认情况下,Spring Boot 不会向这些组添加其他健康指标。spring-doc.cadn.net.cn

“活跃度”探测不应依赖于外部系统的运行状况检查。 如果应用程序的活跃状态被破坏,Kubernetes 会尝试通过重新启动应用程序实例来解决该问题。 这意味着,如果外部系统(例如数据库、Web API 或外部缓存)发生故障,Kubernetes 可能会重新启动所有应用程序实例并产生级联故障。spring-doc.cadn.net.cn

至于“就绪”探测,应用程序开发人员必须仔细选择检查外部系统。 因此,Spring Boot 在就绪情况探测中不包含任何其他健康检查。 如果应用程序实例的就绪状态为“未就绪”,则 Kubernetes 不会将流量路由到该实例。 某些外部系统可能不由应用程序实例共享,在这种情况下,它们可以包含在就绪性探测中。 其他外部系统可能对应用程序不是必需的(应用程序可能具有断路器和回退),在这种情况下,它们绝对不应该包含在内。 遗憾的是,所有应用程序实例共享的外部系统很常见,您必须进行判断调用:将其包含在就绪探测中,并期望在外部服务关闭时应用程序停止服务,或者将其排除在外并处理堆栈上层的故障,也许是在调用者中使用断路器。spring-doc.cadn.net.cn

如果应用程序的所有实例都未就绪,则具有type=ClusterIPNodePort不接受任何传入连接。 没有 HTTP 错误响应(503 等),因为没有连接。 一项服务type=LoadBalancer可能接受也可能不接受连接,具体取决于提供商。 具有显式入口的服务也会以依赖于实现的方式进行响应——入口服务本身必须决定如何处理来自下游的“拒绝连接”。 HTTP 503 很可能在负载均衡器和入口的情况下出现。

此外,如果应用程序使用 Kubernetes 自动缩放,则它可能会对从负载均衡器中取出的应用程序做出不同的反应,具体取决于其自动缩放器配置。spring-doc.cadn.net.cn

2.10.2. 应用程序生命周期和探测状态

Kubernetes 探针支持的一个重要方面是它与应用程序生命周期的一致性。 之间存在显着差异AvailabilityState(即应用程序的内存内部状态) 以及实际的探针(暴露了该状态)。 根据应用程序生命周期的阶段,探测可能不可用。spring-doc.cadn.net.cn

Spring Boot 在启动和关闭期间发布应用程序事件,并且探针可以监听此类事件并公开AvailabilityState信息。spring-doc.cadn.net.cn

下表显示了AvailabilityState以及不同阶段的 HTTP 连接器状态。spring-doc.cadn.net.cn

当 Spring Boot 应用程序启动时:spring-doc.cadn.net.cn

启动阶段 LivenessState 就绪状态 HTTP 服务器 笔记

开始spring-doc.cadn.net.cn

BROKENspring-doc.cadn.net.cn

REFUSING_TRAFFICspring-doc.cadn.net.cn

未开始spring-doc.cadn.net.cn

Kubernetes 会检查“活动性”探针,如果时间过长,则重新启动应用程序。spring-doc.cadn.net.cn

开始spring-doc.cadn.net.cn

CORRECTspring-doc.cadn.net.cn

REFUSING_TRAFFICspring-doc.cadn.net.cn

拒绝请求spring-doc.cadn.net.cn

应用程序上下文将刷新。应用程序执行启动任务,但尚未接收流量。spring-doc.cadn.net.cn

准备spring-doc.cadn.net.cn

CORRECTspring-doc.cadn.net.cn

ACCEPTING_TRAFFICspring-doc.cadn.net.cn

接受请求spring-doc.cadn.net.cn

启动任务已完成。应用程序正在接收流量。spring-doc.cadn.net.cn

当 Spring Boot 应用程序关闭时:spring-doc.cadn.net.cn

关机阶段 活跃状态 就绪状态 HTTP 服务器 笔记

运行spring-doc.cadn.net.cn

CORRECTspring-doc.cadn.net.cn

ACCEPTING_TRAFFICspring-doc.cadn.net.cn

接受请求spring-doc.cadn.net.cn

已请求关闭。spring-doc.cadn.net.cn

正常关机spring-doc.cadn.net.cn

CORRECTspring-doc.cadn.net.cn

REFUSING_TRAFFICspring-doc.cadn.net.cn

新请求被拒绝spring-doc.cadn.net.cn

如果启用,则正常关闭会处理正在进行的请求spring-doc.cadn.net.cn

关机完成spring-doc.cadn.net.cn

不适用spring-doc.cadn.net.cn

不适用spring-doc.cadn.net.cn

服务器已关闭spring-doc.cadn.net.cn

应用程序上下文已关闭,应用程序已关闭。spring-doc.cadn.net.cn

有关 Kubernetes 部署的更多信息,请参阅 Kubernetes 容器生命周期部分

2.11. 应用信息

应用程序信息公开从所有InfoContributorbean 在ApplicationContext. Spring Boot 包括许多自动配置的InfoContributorbean,你可以自己写。spring-doc.cadn.net.cn

2.11.1. 自动配置的 InfoContributors

在适当的情况下,Spring 会自动配置以下内容InfoContributor豆:spring-doc.cadn.net.cn

身份证 名称 描述 前提条件

buildspring-doc.cadn.net.cn

BuildInfoContributorspring-doc.cadn.net.cn

公开生成信息。spring-doc.cadn.net.cn

一个META-INF/build-info.properties资源。spring-doc.cadn.net.cn

envspring-doc.cadn.net.cn

EnvironmentInfoContributorspring-doc.cadn.net.cn

Environment名字开头为info..spring-doc.cadn.net.cn

没有。spring-doc.cadn.net.cn

gitspring-doc.cadn.net.cn

GitInfoContributorspring-doc.cadn.net.cn

公开 git 信息。spring-doc.cadn.net.cn

一个git.properties资源。spring-doc.cadn.net.cn

javaspring-doc.cadn.net.cn

JavaInfoContributorspring-doc.cadn.net.cn

公开 Java 运行时信息。spring-doc.cadn.net.cn

没有。spring-doc.cadn.net.cn

osspring-doc.cadn.net.cn

OsInfoContributorspring-doc.cadn.net.cn

公开作系统信息。spring-doc.cadn.net.cn

没有。spring-doc.cadn.net.cn

是否启用单个贡献者由其控制management.info.<id>.enabled财产。 不同的参与者对此属性有不同的默认值,具体取决于其前提条件和他们公开的信息的性质。spring-doc.cadn.net.cn

由于没有前提条件来指示应启用它们,因此env,javaos默认情况下,贡献者处于禁用状态。可以通过设置其management.info.<id>.enabled属性设置为true.spring-doc.cadn.net.cn

buildgit信息贡献者默认启用。可以通过设置其management.info.<id>.enabled属性设置为false. 或者,要禁用通常默认启用的每个贡献者,请将management.info.defaults.enabled属性设置为false.spring-doc.cadn.net.cn

2.11.2. 自定义应用程序信息

envcontributor 启用后,您可以自定义infoendpoint 通过设置info.*弹簧属性。 都Environment属性下的info键会自动公开。 例如,您可以将以下设置添加到application.properties文件:spring-doc.cadn.net.cn

性能
info.app.encoding=UTF-8
info.app.java.source=17
info.app.java.target=17
亚姆尔
info:
  app:
    encoding: "UTF-8"
    java:
      source: "17"
      target: "17"

除了对这些值进行硬编码,您还可以在构建时扩展信息属性spring-doc.cadn.net.cn

假设您使用 Maven,您可以重写前面的示例,如下所示:spring-doc.cadn.net.cn

亚姆尔
info:
  app:
    encoding: "@project.build.sourceEncoding@"
    java:
      source: "@java.version@"
      target: "@java.version@"

2.11.3. Git 提交信息

另一个有用的功能infoendpoint 是它发布有关您的状态的信息的能力git生成项目时的源代码存储库。 如果GitPropertiesbean 可用,您可以使用infoendpoint 来公开这些属性。spring-doc.cadn.net.cn

一个GitProperties如果git.properties文件位于类路径的根目录中。 有关更多详细信息,请参阅“如何生成 git 信息”。

默认情况下,终结点会公开git.branch,git.commit.idgit.commit.time属性(如果存在)。 如果您不希望在端点响应中包含任何这些属性,则需要将它们从git.properties文件。 如果要显示完整的 git 信息(即git.properties),使用management.info.git.mode属性,如下所示:spring-doc.cadn.net.cn

性能
management.info.git.mode=full
亚姆尔
management:
  info:
    git:
      mode: "full"

要从infoendpoint 完全,请将management.info.git.enabled属性设置为false如下:spring-doc.cadn.net.cn

性能
management.info.git.enabled=false
亚姆尔
management:
  info:
    git:
      enabled: false

2.11.4. 构建信息

如果BuildPropertiesbean 可用,则infoendpoint 还可以发布有关您的构建的信息。 如果META-INF/build-info.properties文件在类路径中可用。spring-doc.cadn.net.cn

Maven 和 Gradle 插件都可以生成该文件。 有关更多详细信息,请参阅“如何生成构建信息”。

2.11.5. Java 信息

infoendpoint 发布有关 Java 运行时环境的信息,请参阅JavaInfo了解更多详情。spring-doc.cadn.net.cn

2.11.6.作系统信息

infoendpoint 发布有关您的作系统的信息,请参阅OsInfo了解更多详情。spring-doc.cadn.net.cn

2.11.7. 编写自定义 InfoContributors

要提供自定义应用程序信息,您可以注册实现InfoContributor接口。spring-doc.cadn.net.cn

以下示例贡献了example条目:spring-doc.cadn.net.cn

Java
import java.util.Collections;

import org.springframework.boot.actuate.info.Info;
import org.springframework.boot.actuate.info.InfoContributor;
import org.springframework.stereotype.Component;

@Component
public class MyInfoContributor implements InfoContributor {

    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("example", Collections.singletonMap("key", "value"));
    }

}
Kotlin
import org.springframework.boot.actuate.info.Info
import org.springframework.boot.actuate.info.InfoContributor
import org.springframework.stereotype.Component
import java.util.Collections

@Component
class MyInfoContributor : InfoContributor {

    override fun contribute(builder: Info.Builder) {
        builder.withDetail("example", Collections.singletonMap("key", "value"))
    }

}

如果您达到infoendpoint,您应该会看到包含以下附加条目的响应:spring-doc.cadn.net.cn

{
    "example": {
        "key" : "value"
    }
}

3. 通过 HTTP 进行监控和管理

如果您正在开发 Web 应用程序,Spring Boot Actuator 会自动配置所有已启用的端点以通过 HTTP 公开。 默认约定是使用id前缀为/actuator作为 URL 路径。 例如health公开为/actuator/health.spring-doc.cadn.net.cn

Spring MVC、Spring WebFlux 和 Jersey 原生支持 Actuator。 如果 Jersey 和 Spring MVC 都可用,则使用 Spring MVC。
Jackson 是获取 API 文档(HTMLPDF)中记录的正确 JSON 响应所需的依赖项。

3.1. 自定义管理端点路径

有时,自定义管理端点的前缀很有用。 例如,您的应用程序可能已经使用/actuator为了另一个目的。 您可以使用management.endpoints.web.base-path属性来更改管理终结点的前缀,如以下示例所示:spring-doc.cadn.net.cn

性能
management.endpoints.web.base-path=/manage
亚姆尔
management:
  endpoints:
    web:
      base-path: "/manage"

前面的application.properties示例将端点从/actuator/{id}/manage/{id}(例如,/manage/info).spring-doc.cadn.net.cn

除非管理端口已配置为使用不同的 HTTP 端口公开端点management.endpoints.web.base-path相对于server.servlet.context-path(对于 servlet Web 应用程序)或spring.webflux.base-path(对于响应式 Web 应用程序)。 如果management.server.port已配置,management.endpoints.web.base-path相对于management.server.base-path.

如果要将端点映射到其他路径,可以使用management.endpoints.web.path-mapping财产。spring-doc.cadn.net.cn

以下示例重新映射/actuator/health/healthcheck:spring-doc.cadn.net.cn

性能
management.endpoints.web.base-path=/
management.endpoints.web.path-mapping.health=healthcheck
亚姆尔
management:
  endpoints:
    web:
      base-path: "/"
      path-mapping:
        health: "healthcheck"

3.2. 自定义管理服务器端口

使用默认 HTTP 端口公开管理终结点是基于云的部署的明智选择。 但是,如果您的应用程序在您自己的数据中心内运行,您可能更愿意使用不同的 HTTP 端口来公开端点。spring-doc.cadn.net.cn

您可以将management.server.port属性来更改 HTTP 端口,如以下示例所示:spring-doc.cadn.net.cn

性能
management.server.port=8081
亚姆尔
management:
  server:
    port: 8081
在 Cloud Foundry 上,默认情况下,应用程序仅在端口 8080 上接收 HTTP 和 TCP 路由的请求。 如果要在 Cloud Foundry 上使用自定义管理端口,则需要显式设置应用程序的路由,以将流量转发到自定义端口。

3.3. 配置特定于管理的SSL

当配置为使用自定义端口时,您还可以使用各种management.server.ssl.*性能。 例如,这样做可以让管理服务器通过 HTTP 可用,而主应用程序使用 HTTPS,如以下属性设置所示:spring-doc.cadn.net.cn

性能
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:store.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=false
亚姆尔
server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:store.jks"
    key-password: "secret"
management:
  server:
    port: 8080
    ssl:
      enabled: false

或者,主服务器和管理服务器都可以使用 SSL,但密钥存储不同,如下所示:spring-doc.cadn.net.cn

性能
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:main.jks
server.ssl.key-password=secret
management.server.port=8080
management.server.ssl.enabled=true
management.server.ssl.key-store=classpath:management.jks
management.server.ssl.key-password=secret
亚姆尔
server:
  port: 8443
  ssl:
    enabled: true
    key-store: "classpath:main.jks"
    key-password: "secret"
management:
  server:
    port: 8080
    ssl:
      enabled: true
      key-store: "classpath:management.jks"
      key-password: "secret"

3.4. 自定义管理服务器地址

您可以通过设置management.server.address财产。 如果您只想在内部或面向作的网络上侦听,或者只想侦听来自localhost.spring-doc.cadn.net.cn

仅当端口与主服务器端口不同时,您才能侦听不同的地址。

以下示例application.properties不允许远程管理连接:spring-doc.cadn.net.cn

性能
management.server.port=8081
management.server.address=127.0.0.1
亚姆尔
management:
  server:
    port: 8081
    address: "127.0.0.1"

3.5. 禁用 HTTP 端点

如果不想通过 HTTP 公开端点,可以将管理端口设置为-1,如以下示例所示:spring-doc.cadn.net.cn

性能
management.server.port=-1
亚姆尔
management:
  server:
    port: -1

您也可以使用management.endpoints.web.exposure.exclude属性,如以下示例所示:spring-doc.cadn.net.cn

性能
management.endpoints.web.exposure.exclude=*
亚姆尔
management:
  endpoints:
    web:
      exposure:
        exclude: "*"

4. 通过 JMX 进行监控和管理

Java 管理扩展 (JMX) 提供了一种标准机制来监视和管理应用程序。 默认情况下,此功能未启用。 您可以通过设置spring.jmx.enabled配置属性设置为true. Spring Boot 暴露最合适的MBeanServer作为 ID 为mbeanServer. 任何使用 Spring JMX 注释(@ManagedResource,@ManagedAttribute@ManagedOperation)暴露于其中。spring-doc.cadn.net.cn

如果您的平台提供标准MBeanServer,Spring Boot 使用它并默认为 VMMBeanServer,如有必要。 如果所有这些都失败了,则新的MBeanServer被创建。spring-doc.cadn.net.cn

spring.jmx.enabled仅影响 Spring 提供的管理 Bean。 启用其他库(例如 Log4j2 或 Quartz)提供的管理 Bean 是独立的。

请参阅JmxAutoConfigurationclass 了解更多详情。spring-doc.cadn.net.cn

默认情况下,Spring Boot 还将管理端点公开为 JMX MBeanorg.springframework.boot域。 要完全控制 JMX 域中的端点注册,请考虑注册您自己的端点EndpointObjectNameFactory实现。spring-doc.cadn.net.cn

4.1. 自定义MBean名称

MBean 的名称通常从id的端点。 例如,healthendpoint 公开为org.springframework.boot:type=Endpoint,name=Health.spring-doc.cadn.net.cn

如果您的应用程序包含多个 SpringApplicationContext,您可能会发现名称冲突。 要解决此问题,您可以将spring.jmx.unique-names属性设置为true因此 MBean 名称始终是唯一的。spring-doc.cadn.net.cn

您还可以自定义在下公开端点的 JMX 域。 以下设置显示了在application.properties:spring-doc.cadn.net.cn

性能
spring.jmx.unique-names=true
management.endpoints.jmx.domain=com.example.myapp
亚姆尔
spring:
  jmx:
    unique-names: true
management:
  endpoints:
    jmx:
      domain: "com.example.myapp"

4.2. 禁用 JMX 端点

如果您不想通过 JMX 公开端点,您可以将management.endpoints.jmx.exposure.exclude属性设置为 ,如以下示例所示:*spring-doc.cadn.net.cn

性能
management.endpoints.jmx.exposure.exclude=*
亚姆尔
management:
  endpoints:
    jmx:
      exposure:
        exclude: "*"

5. 可观测性

可观测性是从外部观察运行系统内部状态的能力。 它由三个支柱组成:日志记录、指标和跟踪。spring-doc.cadn.net.cn

对于指标和跟踪,Spring Boot 使用 Micrometer Observation。 要创建自己的观察结果(这将导致指标和跟踪),您可以注入ObservationRegistry.spring-doc.cadn.net.cn

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
public class MyCustomObservation {

    private final ObservationRegistry observationRegistry;

    public MyCustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    public void doSomething() {
        Observation.createNotStarted("doSomething", this.observationRegistry)
            .lowCardinalityKeyValue("locale", "en-US")
            .highCardinalityKeyValue("userId", "42")
            .observe(() -> {
                // Execute business logic here
            });
    }

}
低基数标记将添加到指标和跟踪中,而高基数标记将仅添加到跟踪中。

Beans类型ObservationPredicate,GlobalObservationConvention,ObservationFilterObservationHandler将自动注册在ObservationRegistry. 您可以额外注册任意数量的ObservationRegistryCustomizerbean 来进一步配置注册表。spring-doc.cadn.net.cn

可观测性支持依赖于上下文传播库跨线程和响应式管道转发当前观察。 默认情况下,ThreadLocal值不会在响应式运算符中自动恢复。 此行为由spring.reactor.context-propagation属性,可以设置为auto以启用自动传播。spring-doc.cadn.net.cn

有关观测的更多详细信息,请参阅千分尺观测文档spring-doc.cadn.net.cn

JDBC 的可观测性可以使用单独的项目进行配置。 Datasource Micrometer 项目提供了一个 Spring Boot Starters,它在调用 JDBC作时自动创建观察结果。 在参考文档中阅读有关它的更多信息。
R2DBC 的可观测性内置于 Spring Boot 中。 要启用它,请将io.r2dbc:r2dbc-proxy依赖项目。

5.1. 常用标签

通用标签一般用于对运行环境进行维度下钻,如主机、实例、地域、堆栈等。 通用标记作为低基数标记应用于所有观测值,并且可以进行配置,如以下示例所示:spring-doc.cadn.net.cn

性能
management.observations.key-values.region=us-east-1
management.observations.key-values.stack=prod
亚姆尔
management:
  observations:
    key-values:
      region: "us-east-1"
      stack: "prod"

前面的示例将regionstack标记添加到值为us-east-1prod分别。spring-doc.cadn.net.cn

5.2. 防止观察

如果要阻止报告某些观察结果,可以使用management.observations.enable性能:spring-doc.cadn.net.cn

性能
management.observations.enable.denied.prefix=false
management.observations.enable.another.denied.prefix=false
亚姆尔
management:
  observations:
    enable:
      denied:
        prefix: false
      another:
        denied:
          prefix: false

前面的示例将阻止名称以denied.prefixanother.denied.prefix.spring-doc.cadn.net.cn

如果要阻止 Spring Security 报告观察结果,请将属性management.observations.enable.spring.securityfalse.

如果您需要更好地控制观察的预防,您可以注册类型为ObservationPredicate. 仅当所有ObservationPredicate豆子返回true为了那个观察。spring-doc.cadn.net.cn

import io.micrometer.observation.Observation.Context;
import io.micrometer.observation.ObservationPredicate;

import org.springframework.stereotype.Component;

@Component
class MyObservationPredicate implements ObservationPredicate {

    @Override
    public boolean test(String name, Context context) {
        return !name.contains("denied");
    }

}

前面的示例将阻止名称包含“denied”的所有观察。spring-doc.cadn.net.cn

5.3. OpenTelemetry 支持

有多种方法可以在应用程序中支持 OpenTelemetry。 您可以使用 OpenTelemetry Java 代理OpenTelemetry Spring Boot Starter, 由 OTel 社区支持;指标和跟踪使用OTel库定义的语义约定。 本文档描述了 Spring 团队使用 Micrometer 和 OTLP 导出器正式支持的 OpenTelemetry; 指标和跟踪使用 Spring 项目文档中描述的语义约定,例如 Spring Framework

Spring Boot 的执行器模块包括对 OpenTelemetry 的基本支持。spring-doc.cadn.net.cn

它提供了一种类型的 beanOpenTelemetry,如果存在类型SdkTracerProvider,ContextPropagators,SdkLoggerProviderSdkMeterProvider在应用程序上下文中,它们会自动注册。 此外,它还提供了一个Resource豆。 自动配置的属性Resource可以通过management.opentelemetry.resource-attributesconfiguration 属性。 如果您已经定义了自己的Resourcebean,情况将不再如此。spring-doc.cadn.net.cn

Spring Boot 不提供 OpenTelemetry 指标或日志记录的自动配置。 OpenTelemetry 跟踪仅在与 Micrometer Tracking 一起使用时自动配置。

接下来的部分将提供有关日志记录、指标和跟踪的更多详细信息。spring-doc.cadn.net.cn

5.4. 千分尺观察注释支持

启用指标扫描和跟踪注释,例如@Timed,@Counted,@MeterTag@NewSpan注释,您需要将management.observations.annotations.enabled属性设置为true. 此功能直接支持千分尺,请参阅千分尺千分尺追踪参考文档。spring-doc.cadn.net.cn

6. 记录仪

Spring Boot Actuator 包括在运行时查看和配置应用程序日志级别的功能。 您可以查看整个列表或单个记录器的配置,该配置由显式配置的日志记录级别以及日志记录框架给出的有效日志记录级别组成。 这些级别可以是以下级别之一:spring-doc.cadn.net.cn

null表示没有显式配置。spring-doc.cadn.net.cn

6.1. 配置记录器

要配置给定的记录器,POST资源 URI 的部分实体,如以下示例所示:spring-doc.cadn.net.cn

{
    "configuredLevel": "DEBUG"
}
要“重置”记录器的特定级别(并改用默认配置),您可以传递一个null作为configuredLevel.

7. 计量指标

Spring Boot Actuator 为 Micrometer 提供依赖管理和自动配置,Micrometer 是一种支持众多监控系统的应用程序指标外观,包括:spring-doc.cadn.net.cn

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

7.1. 开始使用

Spring Boot 自动配置复合MeterRegistry并为它在类路径上找到的每个受支持的实现向复合添加一个注册表。 依赖于micrometer-registry-{system}足以让 Spring Boot 配置注册表。spring-doc.cadn.net.cn

大多数注册管理机构具有共同的功能。 例如,即使 Micrometer 注册表实现在类路径上,您也可以禁用特定的注册表。 以下示例禁用 Datadog:spring-doc.cadn.net.cn

性能
management.datadog.metrics.export.enabled=false
亚姆尔
management:
  datadog:
    metrics:
      export:
        enabled: false

您还可以禁用所有注册表,除非特定于注册表的属性另有说明,如以下示例所示:spring-doc.cadn.net.cn

性能
management.defaults.metrics.export.enabled=false
亚姆尔
management:
  defaults:
    metrics:
      export:
        enabled: false

Spring Boot 还会将任何自动配置的注册表添加到Metrics类,除非你明确告诉它不要:spring-doc.cadn.net.cn

性能
management.metrics.use-global-registry=false
亚姆尔
management:
  metrics:
    use-global-registry: false

您可以注册任意数量的MeterRegistryCustomizerbean 以进一步配置注册表,例如在向注册表注册任何仪表注册之前应用通用标签:spring-doc.cadn.net.cn

Java
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");
    }

}
Kotlin
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)
class MyMeterRegistryConfiguration {

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

}

可以通过更具体地描述泛型类型,将自定义项应用于特定的注册表实现:spring-doc.cadn.net.cn

Java
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 ...
    }

}
Kotlin
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)
class MyMeterRegistryConfiguration {

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

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

}

Spring Boot 还配置了内置检测,您可以通过配置或专用注释标记进行控制。spring-doc.cadn.net.cn

7.2. 支持的监控系统

本节简要介绍每个受支持的监控系统。spring-doc.cadn.net.cn

7.2.1. 应用光学

默认情况下,AppOptics 注册表会定期将指标推送到api.appoptics.com/v1/measurements. 要将指标导出到 SaaS AppOptics,必须提供您的 API Tokens:spring-doc.cadn.net.cn

性能
management.appoptics.metrics.export.api-token=YOUR_TOKEN
亚姆尔
management:
  appoptics:
    metrics:
      export:
        api-token: "YOUR_TOKEN"

7.2.2. 地图集

默认情况下,指标将导出到本地计算机上运行的 Atlas。 您可以提供 Atlas 服务器的位置:spring-doc.cadn.net.cn

性能
management.atlas.metrics.export.uri=https://atlas.example.com:7101/api/v1/publish
亚姆尔
management:
  atlas:
    metrics:
      export:
        uri: "https://atlas.example.com:7101/api/v1/publish"

7.2.3. 数据狗

Datadog 注册表会定期将指标推送到 datadoghq。 要将指标导出到 Datadog,您必须提供您的 API 密钥:spring-doc.cadn.net.cn

性能
management.datadog.metrics.export.api-key=YOUR_KEY
亚姆尔
management:
  datadog:
    metrics:
      export:
        api-key: "YOUR_KEY"

如果另外提供应用程序密钥(可选),则还将导出计量说明、类型和基本单位等元数据:spring-doc.cadn.net.cn

性能
management.datadog.metrics.export.api-key=YOUR_API_KEY
management.datadog.metrics.export.application-key=YOUR_APPLICATION_KEY
亚姆尔
management:
  datadog:
    metrics:
      export:
        api-key: "YOUR_API_KEY"
        application-key: "YOUR_APPLICATION_KEY"

默认情况下,指标被发送到 Datadog US 站点 (api.datadoghq.com). 如果您的 Datadog 项目托管在其他站点之一上,或者您需要通过代理发送指标,请相应地配置 URI:spring-doc.cadn.net.cn

性能
management.datadog.metrics.export.uri=https://api.datadoghq.eu
亚姆尔
management:
  datadog:
    metrics:
      export:
        uri: "https://api.datadoghq.eu"

您还可以更改将指标发送到 Datadog 的时间间隔:spring-doc.cadn.net.cn

性能
management.datadog.metrics.export.step=30s
亚姆尔
management:
  datadog:
    metrics:
      export:
        step: "30s"

7.2.4. Dynatrace

Dynatrace 提供了两个指标摄取 API,这两个 API 都是为 Micrometer 实现的。 您可以在此处找到有关 Micrometer 指标摄取的 Dynatrace 文档。 配置属性中的v1命名空间仅在导出到 Timeseries v1 API 时适用。 配置属性中的v2命名空间仅在导出到 Metrics v2 API 时适用。 请注意,此集成只能导出到v1v2API 版本,使用v2是首选。 如果device-id(v1 需要,但在 v2 中不使用)在v1命名空间,则指标将导出到v1端点。 否则v2被假设。spring-doc.cadn.net.cn

v2 API

您可以通过两种方式使用 v2 API。spring-doc.cadn.net.cn

自动配置

Dynatrace 自动配置适用于由 OneAgent 或 Dynatrace Operator for Kubernetes 监控的主机。spring-doc.cadn.net.cn

本地 OneAgent:如果主机上正在运行 OneAgent,则指标会自动导出到本地 OneAgent 摄取端点。 摄取端点将指标转发到 Dynatrace 后端。spring-doc.cadn.net.cn

Dynatrace Kubernetes Operator:在安装了 Dynatrace Operator 的 Kubernetes 中运行时,注册表将自动从操作员那里获取您的端点 URI 和 API Tokens。spring-doc.cadn.net.cn

这是默认行为,除了依赖io.micrometer:micrometer-registry-dynatrace.spring-doc.cadn.net.cn

手动配置

如果没有可用的自动配置,则需要指标 v2 API 的端点和 API Tokens。API Tokens必须具有“引入指标”(metrics.ingest) 权限集。我们建议将Tokens的范围限制为此一个权限。您必须确保终端节点 URI 包含路径(例如,/api/v2/metrics/ingest):spring-doc.cadn.net.cn

指标 API v2 引入终结点的 URL 因部署选项而异:spring-doc.cadn.net.cn

以下示例使用example环境 ID:spring-doc.cadn.net.cn

性能
management.dynatrace.metrics.export.uri=https://example.live.dynatrace.com/api/v2/metrics/ingest
management.dynatrace.metrics.export.api-token=YOUR_TOKEN
亚姆尔
management:
  dynatrace:
    metrics:
      export:
        uri: "https://example.live.dynatrace.com/api/v2/metrics/ingest"
        api-token: "YOUR_TOKEN"

使用 Dynatrace v2 API 时,可以使用以下可选功能(更多详细信息可以在 Dynatrace 文档中找到):spring-doc.cadn.net.cn

  • 指标键前缀:设置前缀,该前缀附加到所有导出的指标键。spring-doc.cadn.net.cn

  • 使用 Dynatrace 元数据进行扩充:如果 OneAgent 或 Dynatrace 运算符正在运行,请使用其他元数据(例如,关于主机、进程或 Pod)来扩充指标。spring-doc.cadn.net.cn

  • 默认维度:指定添加到所有导出指标的键值对。如果使用 Micrometer 指定具有相同键的标记,它们将覆盖默认维度。spring-doc.cadn.net.cn

  • 使用 Dynatrace 摘要工具:在某些情况下,Micrometer Dynatrace 注册表创建的指标被拒绝。在 Micrometer 1.9.x 中,通过引入特定于 Dynatrace 的摘要工具修复了此问题。将此切换设置为false强制 Micrometer 回退到 1.9.x 之前的默认行为。只有在从 Micrometer 1.8.x 迁移到 1.9.x 时遇到问题时才应使用它。spring-doc.cadn.net.cn

  • 导出仪表元数据:从 Micrometer 1.12.0 开始,Dynatrace 导出器还将默认导出仪表元数据,例如单位和描述。 使用export-meter-metadata切换以关闭此功能。spring-doc.cadn.net.cn

可以不指定 URI 和 API Tokens,如以下示例所示。在此方案中,使用自动配置的终结点:spring-doc.cadn.net.cn

性能
management.dynatrace.metrics.export.v2.metric-key-prefix=your.key.prefix
management.dynatrace.metrics.export.v2.enrich-with-dynatrace-metadata=true
management.dynatrace.metrics.export.v2.default-dimensions.key1=value1
management.dynatrace.metrics.export.v2.default-dimensions.key2=value2
management.dynatrace.metrics.export.v2.use-dynatrace-summary-instruments=true
management.dynatrace.metrics.export.v2.export-meter-metadata=true
亚姆尔
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 Tokens、设备 ID 和 URI:spring-doc.cadn.net.cn

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

对于 v1 API,必须指定不带路径的基本环境 URI,因为 v1 终结点路径是自动添加的。spring-doc.cadn.net.cn

与版本无关的设置

除了 API 端点和Tokens之外,您还可以更改将指标发送到 Dynatrace 的时间间隔。 默认导出间隔为60s. 以下示例将导出间隔设置为 30 秒:spring-doc.cadn.net.cn

性能
management.dynatrace.metrics.export.step=30s
亚姆尔
management:
  dynatrace:
    metrics:
      export:
        step: "30s"

您可以在 Micrometer 文档Dynatrace 文档中找到有关如何为 Micrometer 设置 Dynatrace 导出器的更多信息。spring-doc.cadn.net.cn

7.2.5. 弹性

默认情况下,指标将导出到本地计算机上运行的 Elastic。 您可以使用以下属性提供要使用的弹性服务器的位置:spring-doc.cadn.net.cn

性能
management.elastic.metrics.export.host=https://elastic.example.com:8086
亚姆尔
management:
  elastic:
    metrics:
      export:
        host: "https://elastic.example.com:8086"

7.2.6. 神经节

默认情况下,指标将导出到本地计算机上运行的 Ganglia。 您可以提供 Ganglia 服务器主机和端口,如以下示例所示:spring-doc.cadn.net.cn

性能
management.ganglia.metrics.export.host=ganglia.example.com
management.ganglia.metrics.export.port=9649
亚姆尔
management:
  ganglia:
    metrics:
      export:
        host: "ganglia.example.com"
        port: 9649

7.2.7. 石墨

默认情况下,指标将导出到本地计算机上运行的 Graphite。 您可以提供 Graphite 服务器主机和端口,如以下示例所示:spring-doc.cadn.net.cn

性能
management.graphite.metrics.export.host=graphite.example.com
management.graphite.metrics.export.port=9004
亚姆尔
management:
  graphite:
    metrics:
      export:
         host: "graphite.example.com"
         port: 9004

Micrometer 提供默认的HierarchicalNameMapper控制如何将维度计 ID 映射到平面分层名称spring-doc.cadn.net.cn

要控制此行为,请定义您的GraphiteMeterRegistry并提供您自己的HierarchicalNameMapper. 自动配置的GraphiteConfigClock除非您定义自己的 bean:spring-doc.cadn.net.cn

Java
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 ...
    }

}
Kotlin
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)
class MyGraphiteConfiguration {

    @Bean
    fun graphiteMeterRegistry(config: GraphiteConfig, clock: Clock): GraphiteMeterRegistry {
        return GraphiteMeterRegistry(config, clock, this::toHierarchicalName)
    }
    private fun toHierarchicalName(id: Meter.Id, convention: NamingConvention): String {
        return  ...
    }

}

7.2.8. 腐殖

默认情况下,Humio 注册表会定期将指标推送到 cloud.humio.com。 要将指标导出到 SaaS Humio,您必须提供 API Tokens:spring-doc.cadn.net.cn

性能
management.humio.metrics.export.api-token=YOUR_TOKEN
亚姆尔
management:
  humio:
    metrics:
      export:
        api-token: "YOUR_TOKEN"

还应配置一个或多个标记,以标识将指标推送到的数据源:spring-doc.cadn.net.cn

性能
management.humio.metrics.export.tags.alpha=a
management.humio.metrics.export.tags.bravo=b
亚姆尔
management:
  humio:
    metrics:
      export:
        tags:
          alpha: "a"
          bravo: "b"

7.2.9. 涌入

默认情况下,指标将导出到具有默认配置的本地计算机上运行的 Influx v1 实例。 要将指标导出到 InfluxDB v2,请配置org,bucket和身份验证token用于编写指标。 您可以使用以下方法提供要使用的 Influx 服务器的位置:spring-doc.cadn.net.cn

性能
management.influx.metrics.export.uri=https://influx.example.com:8086
亚姆尔
management:
  influx:
    metrics:
      export:
        uri: "https://influx.example.com:8086"

7.2.10. JMX

Micrometer 提供了与 JMX 的分层映射,主要作为一种廉价且可移植的方式在本地查看指标。 默认情况下,指标将导出到metricsJMX 域。 您可以使用以下方法提供要使用的域:spring-doc.cadn.net.cn

性能
management.jmx.metrics.export.domain=com.example.app.metrics
亚姆尔
management:
  jmx:
    metrics:
      export:
        domain: "com.example.app.metrics"

Micrometer 提供默认的HierarchicalNameMapper控制如何将维度计 ID 映射到平面分层名称spring-doc.cadn.net.cn

要控制此行为,请定义您的JmxMeterRegistry并提供您自己的HierarchicalNameMapper. 自动配置的JmxConfigClock除非您定义自己的 bean:spring-doc.cadn.net.cn

Java
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 ...
    }

}
Kotlin
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)
class MyJmxConfiguration {

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

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

}

7.2.11. 凯罗斯数据库

默认情况下,指标将导出到本地计算机上运行的 KairosDB。您可以使用以下方法提供要使用的 KairosDB 服务器的位置:spring-doc.cadn.net.cn

性能
management.kairos.metrics.export.uri=https://kairosdb.example.com:8080/api/v1/datapoints
亚姆尔
management:
  kairos:
    metrics:
      export:
        uri: "https://kairosdb.example.com:8080/api/v1/datapoints"

7.2.12. 新遗迹

New Relic 注册表定期将指标推送到 New Relic。 要将指标导出到 New Relic,您必须提供您的 API 密钥和帐户 ID:spring-doc.cadn.net.cn

性能
management.newrelic.metrics.export.api-key=YOUR_KEY
management.newrelic.metrics.export.account-id=YOUR_ACCOUNT_ID
亚姆尔
management:
  newrelic:
    metrics:
      export:
        api-key: "YOUR_KEY"
        account-id: "YOUR_ACCOUNT_ID"

您还可以更改将指标发送到 New Relic 的时间间隔:spring-doc.cadn.net.cn

性能
management.newrelic.metrics.export.step=30s
亚姆尔
management:
  newrelic:
    metrics:
      export:
        step: "30s"

默认情况下,指标通过 REST 调用发布,但如果 Java Agent API 位于类路径上,也可以使用它:spring-doc.cadn.net.cn

性能
management.newrelic.metrics.export.client-provider-type=insights-agent
亚姆尔
management:
  newrelic:
    metrics:
      export:
        client-provider-type: "insights-agent"

最后,您可以通过定义自己的NewRelicClientProvider豆。spring-doc.cadn.net.cn

7.2.13. OpenTelemetry

默认情况下,指标将导出到本地计算机上运行的 OpenTelemetry。 可以使用以下方法提供要使用的 OpenTelemetry 指标终结点的位置:spring-doc.cadn.net.cn

性能
management.otlp.metrics.export.url=https://otlp.example.com:4318/v1/metrics
亚姆尔
management:
  otlp:
    metrics:
      export:
        url: "https://otlp.example.com:4318/v1/metrics"

7.2.14. 普罗米修斯

Prometheus 希望抓取或轮询单个应用程序实例以获取指标。 Spring Boot 提供了一个执行器端点/actuator/prometheus以适当的格式呈现 Prometheus 抓取spring-doc.cadn.net.cn

默认情况下,终结点不可用,必须公开。有关更多详细信息,请参阅公开终结点

以下示例scrape_config添加到prometheus.yml:spring-doc.cadn.net.cn

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

还支持 Prometheus Exemplars。 要启用此功能,请SpanContextSupplier豆子应该存在。 如果您使用千分尺追踪,这将为您自动配置,但如果您愿意,您可以随时创建自己的追踪。 请查看 Prometheus 文档,因为该功能需要在 Prometheus 端显式启用,并且仅支持 OpenMetrics 格式。spring-doc.cadn.net.cn

对于可能存在时间不够长而无法抓取的临时或批处理作业,您可以使用 Prometheus Pushgateway 支持将指标公开给 Prometheus。 要启用 Prometheus Pushgateway 支持,请向项目添加以下依赖项:spring-doc.cadn.net.cn

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

当 Prometheus Pushgateway 依赖项存在于类路径上并且management.prometheus.metrics.export.pushgateway.enabled属性设置为true一个PrometheusPushGatewayManagerbean 是自动配置的。 这管理将指标推送到 Prometheus Pushgateway。spring-doc.cadn.net.cn

您可以调整PrometheusPushGatewayManager通过使用management.prometheus.metrics.export.pushgateway. 对于高级配置,您还可以提供自己的配置PrometheusPushGatewayManager豆。spring-doc.cadn.net.cn

7.2.15. 信号FX

SignalFx 注册表定期将指标推送到 SignalFx。 若要将指标导出到 SignalFx,必须提供访问Tokens:spring-doc.cadn.net.cn

性能
management.signalfx.metrics.export.access-token=YOUR_ACCESS_TOKEN
亚姆尔
management:
  signalfx:
    metrics:
      export:
        access-token: "YOUR_ACCESS_TOKEN"

您还可以更改将指标发送到 SignalFx 的时间间隔:spring-doc.cadn.net.cn

性能
management.signalfx.metrics.export.step=30s
亚姆尔
management:
  signalfx:
    metrics:
      export:
        step: "30s"

7.2.16. 简单

Micrometer 附带了一个简单的内存中后端,如果没有配置其他注册表,则会自动将其用作回退。 这样,您就可以查看指标端点中收集了哪些指标。spring-doc.cadn.net.cn

一旦您使用任何其他可用后端,内存中后端就会自行禁用。 您也可以显式禁用它:spring-doc.cadn.net.cn

性能
management.simple.metrics.export.enabled=false
亚姆尔
management:
  simple:
    metrics:
      export:
        enabled: false

7.2.17. 堆栈驱动程序

Stackdriver 注册表会定期将指标推送到 Stackdriver。 要将指标导出到 SaaS Stackdriver,您必须提供您的 Google Cloud 项目 ID:spring-doc.cadn.net.cn

性能
management.stackdriver.metrics.export.project-id=my-project
亚姆尔
management:
  stackdriver:
    metrics:
      export:
        project-id: "my-project"

您还可以更改将指标发送到 Stackdriver 的时间间隔:spring-doc.cadn.net.cn

性能
management.stackdriver.metrics.export.step=30s
亚姆尔
management:
  stackdriver:
    metrics:
      export:
        step: "30s"

7.2.18. 统计D

StatsD 注册表急切地通过 UDP 将指标推送到 StatsD 代理。 默认情况下,指标将导出到本地计算机上运行的 StatsD 代理。 您可以使用以下方法提供要使用的 StatsD 代理主机、端口和协议:spring-doc.cadn.net.cn

性能
management.statsd.metrics.export.host=statsd.example.com
management.statsd.metrics.export.port=9125
management.statsd.metrics.export.protocol=udp
亚姆尔
management:
  statsd:
    metrics:
      export:
        host: "statsd.example.com"
        port: 9125
        protocol: "udp"

您还可以更改要使用的 StatsD 线协议(默认为 Datadog):spring-doc.cadn.net.cn

性能
management.statsd.metrics.export.flavor=etsy
亚姆尔
management:
  statsd:
    metrics:
      export:
        flavor: "etsy"

7.2.19. 波前

Wavefront 注册表会定期将指标推送到 Wavefront。 如果要将指标直接导出到 Wavefront,则必须提供 API Tokens:spring-doc.cadn.net.cn

性能
management.wavefront.api-token=YOUR_API_TOKEN
亚姆尔
management:
  wavefront:
    api-token: "YOUR_API_TOKEN"

或者,您可以使用环境中的 Wavefront Sidecar 或内部代理将指标数据转发到 Wavefront API 主机:spring-doc.cadn.net.cn

性能
management.wavefront.uri=proxy://localhost:2878
亚姆尔
management:
  wavefront:
    uri: "proxy://localhost:2878"
如果您将指标发布到 Wavefront 代理(如 Wavefront 文档中所述),则主机必须位于proxy://HOST:PORT格式。

您还可以更改将指标发送到 Wavefront 的时间间隔:spring-doc.cadn.net.cn

性能
management.wavefront.metrics.export.step=30s
亚姆尔
management:
  wavefront:
    metrics:
      export:
        step: "30s"

7.3. 支持的指标和仪表

Spring Boot 为各种技术提供自动仪表注册。 在大多数情况下,默认值提供了合理的指标,可以发布到任何受支持的监控系统。spring-doc.cadn.net.cn

7.3.1. JVM 指标

自动配置通过使用核心 Micrometer 类启用 JVM 指标。JVM 指标发布在jvm.仪表名称。spring-doc.cadn.net.cn

提供了以下 JVM 指标:spring-doc.cadn.net.cn

7.3.2. 系统指标

自动配置通过使用核心 Micrometer 类启用系统度量。 系统指标发布在system.,process.disk.仪表名称。spring-doc.cadn.net.cn

提供以下系统指标:spring-doc.cadn.net.cn

7.3.3. 应用程序启动指标

自动配置公开应用程序启动时间指标:spring-doc.cadn.net.cn

指标由应用程序类的完全限定名称标记。spring-doc.cadn.net.cn

7.3.4. Logger 指标

自动配置启用 Logback 和 Log4J2 的事件指标。 详细信息发布在log4j2.events.logback.events.仪表名称。spring-doc.cadn.net.cn

7.3.5. 任务执行和调度指标

自动配置支持所有可用仪器ThreadPoolTaskExecutorThreadPoolTaskScheduler豆子,只要下属ThreadPoolExecutor可用。 指标由执行器的名称标记,该名称派生自 Bean 名称。spring-doc.cadn.net.cn

7.3.6. JMS 指标

自动配置支持所有可用仪器JmsTemplatebeans 和@JmsListener带注释的方法。 这将产生"jms.message.publish""jms.message.process"指标。有关生成的观察的更多信息,请参阅 Spring Framework 参考文档spring-doc.cadn.net.cn

7.3.7. Spring MVC 指标

自动配置允许检测 Spring MVC 控制器和功能处理程序处理的所有请求。默认情况下,指标的生成名称为http.server.requests. 您可以通过设置management.observations.http.server.requests.name财产。spring-doc.cadn.net.cn

要添加到默认标记,请提供@Bean延伸DefaultServerRequestObservationConventionorg.springframework.http.server.observation包。 要替换默认标记,请提供一个@Bean实现ServerRequestObservationConvention.spring-doc.cadn.net.cn

在某些情况下,Web 控制器中处理的异常不会记录为请求指标标记。 应用程序可以通过将已处理的异常设置为请求属性来选择加入并记录异常。

默认情况下,将处理所有请求。 要自定义过滤器,请提供@Bean实现FilterRegistrationBean<ServerHttpObservationFilter>.spring-doc.cadn.net.cn

7.3.8. Spring WebFlux 指标

自动配置允许检测 Spring WebFlux 控制器和功能处理程序处理的所有请求。 默认情况下,生成指标的名称为http.server.requests. 您可以通过设置management.observations.http.server.requests.name财产。spring-doc.cadn.net.cn

要添加到默认标记,请提供@Bean延伸DefaultServerRequestObservationConventionorg.springframework.http.server.reactive.observation包。 要替换默认标记,请提供一个@Bean实现ServerRequestObservationConvention.spring-doc.cadn.net.cn

在某些情况下,控制器和处理程序函数中处理的异常不会记录为请求指标标记。 应用程序可以通过将已处理的异常设置为请求属性来选择加入并记录异常。

7.3.9. Jersey服务器指标

自动配置支持检测 Jersey JAX-RS 实现处理的所有请求。 默认情况下,生成指标的名称为http.server.requests. 您可以通过设置management.observations.http.server.requests.name财产。spring-doc.cadn.net.cn

默认情况下,Jersey服务器指标使用以下信息进行标记:spring-doc.cadn.net.cn

标记 描述

exceptionspring-doc.cadn.net.cn

处理请求时引发的任何异常的简单类名。spring-doc.cadn.net.cn

methodspring-doc.cadn.net.cn

请求的方法(例如GETPOST)spring-doc.cadn.net.cn

outcomespring-doc.cadn.net.cn

请求的结果,基于响应的状态代码。 1xx 是INFORMATIONAL,2xx 是SUCCESS,3xx 是REDIRECTION,4xx 是CLIENT_ERROR,5xx 是SERVER_ERRORspring-doc.cadn.net.cn

statusspring-doc.cadn.net.cn

响应的 HTTP 状态代码(例如200500)spring-doc.cadn.net.cn

urispring-doc.cadn.net.cn

如果可能,请求的 URI 模板在变量替换之前(例如,/api/person/{id})spring-doc.cadn.net.cn

要自定义标记,请提供@Bean实现JerseyTagsProvider.spring-doc.cadn.net.cn

7.3.10. HTTP 客户端指标

Spring Boot Actuator 管理RestTemplate,WebClientRestClient. 为此,您必须注入自动配置的构建器并使用它来创建实例:spring-doc.cadn.net.cn

您还可以手动应用负责此检测的定制器,即ObservationRestTemplateCustomizer,ObservationWebClientCustomizerObservationRestClientCustomizer.spring-doc.cadn.net.cn

默认情况下,生成指标的名称为http.client.requests. 您可以通过设置management.observations.http.client.requests.name财产。spring-doc.cadn.net.cn

在使用RestTemplateRestClient,提供一个@Bean实现ClientRequestObservationConventionorg.springframework.http.client.observation包。 在使用WebClient,提供一个@Bean实现ClientRequestObservationConventionorg.springframework.web.reactive.function.client包。spring-doc.cadn.net.cn

7.3.11. Tomcat 指标

自动配置仅在MBeanRegistry已启用。 默认情况下,MBeanRegistry已禁用,但您可以通过将server.tomcat.mbeanregistry.enabledtrue.spring-doc.cadn.net.cn

Tomcat 指标发布在tomcat.仪表名称。spring-doc.cadn.net.cn

7.3.12. 缓存指标

自动配置支持所有可用仪器Cache启动时的实例,指标前缀为cache. 缓存检测针对一组基本指标进行了标准化。 还提供其他特定于缓存的指标。spring-doc.cadn.net.cn

支持以下缓存库:spring-doc.cadn.net.cn

指标由缓存的名称和CacheManager,源自 bean 名称。spring-doc.cadn.net.cn

只有在启动时配置的缓存才会绑定到注册表。 对于缓存配置中未定义的缓存,例如动态创建的缓存或在启动阶段后以编程方式创建的缓存,需要显式注册。 一个CacheMetricsRegistrarbean 的提供使该过程更容易。

7.3.13. Spring 批处理指标

7.3.14. Spring GraphQL 指标

7.3.15. 数据源指标

自动配置支持所有可用仪器DataSource指标前缀为jdbc.connections. 数据源检测生成仪表,这些仪表表示池中当前活动、空闲、允许的最大连接数和允许的最小连接数。spring-doc.cadn.net.cn

指标还由DataSource根据 Bean 名称计算。spring-doc.cadn.net.cn

默认情况下,Spring Boot 为所有受支持的数据源提供元数据。 您可以添加其他DataSourcePoolMetadataProviderbean,如果不支持您最喜欢的数据源。 看DataSourcePoolMetadataProvidersConfiguration例如。

此外,特定于 Hikari 的指标会通过hikaricp前缀。 每个指标都由池的名称标记(您可以使用spring.datasource.name).spring-doc.cadn.net.cn

7.3.16. Hibernate 指标

如果org.hibernate.orm:hibernate-micrometer在类路径上,所有可用的休眠EntityManagerFactory启用了统计信息的实例使用名为hibernate.spring-doc.cadn.net.cn

指标还由EntityManagerFactory,源自 bean 名称。spring-doc.cadn.net.cn

要启用统计信息,请标准 JPA 属性hibernate.generate_statistics必须设置为true. 您可以在自动配置的EntityManagerFactory:spring-doc.cadn.net.cn

性能
spring.jpa.properties[hibernate.generate_statistics]=true
亚姆尔
spring:
  jpa:
    properties:
      "[hibernate.generate_statistics]": true

7.3.17. Spring Data Repository指标

自动配置支持所有 Spring Data 的检测Repository方法调用。 默认情况下,生成指标的名称为spring.data.repository.invocations. 您可以通过设置management.metrics.data.repository.metric-name财产。spring-doc.cadn.net.cn

@Timed注释io.micrometer.core.annotation软件包支持Repository接口和方法。 如果您不想记录所有指标Repository调用,您可以将management.metrics.data.repository.autotime.enabledfalse并专门使用@Timed注释。spring-doc.cadn.net.cn

一个@Timed注释longTask = true为该方法启用较长的任务计时器。 长任务计时器需要单独的指标名称,并且可以与短任务计时器堆叠。

默认情况下,与存储库调用相关的指标使用以下信息进行标记:spring-doc.cadn.net.cn

标记 描述

repositoryspring-doc.cadn.net.cn

源的简单类名Repository.spring-doc.cadn.net.cn

methodspring-doc.cadn.net.cn

的名称Repository方法。spring-doc.cadn.net.cn

statespring-doc.cadn.net.cn

结果状态 (SUCCESS,ERROR,CANCELEDRUNNING).spring-doc.cadn.net.cn

exceptionspring-doc.cadn.net.cn

从调用引发的任何异常的简单类名。spring-doc.cadn.net.cn

要替换默认标记,请提供一个@Bean实现RepositoryTagsProvider.spring-doc.cadn.net.cn

7.3.18. RabbitMQ 指标

自动配置允许检测所有可用的 RabbitMQ 连接工厂,其指标名为rabbitmq.spring-doc.cadn.net.cn

7.3.19. Spring 集成指标

Spring Integration 每当MeterRegistry豆子可用。 指标发布在spring.integration.仪表名称。spring-doc.cadn.net.cn

7.3.20. Kafka 指标

自动配置注册一个MicrometerConsumerListenerMicrometerProducerListener分别用于自动配置的使用者工厂和生产者工厂。 它还注册了一个KafkaStreamsMicrometerListenerStreamsBuilderFactoryBean. 有关更多详细信息,请参阅 Spring Kafka 文档的 Micrometer Native Metrics 部分。spring-doc.cadn.net.cn

7.3.21. MongoDB 指标

本节简要介绍 MongoDB 的可用指标。spring-doc.cadn.net.cn

MongoDB 命令指标

自动配置注册一个MongoMetricsCommandListener使用自动配置的MongoClient.spring-doc.cadn.net.cn

名为mongodb.driver.commands为向底层 MongoDB 驱动程序发出的每个命令创建。 默认情况下,每个指标都使用以下信息进行标记:spring-doc.cadn.net.cn

标记 描述

commandspring-doc.cadn.net.cn

发出的命令的名称。spring-doc.cadn.net.cn

cluster.idspring-doc.cadn.net.cn

命令发送到的集群的标识符。spring-doc.cadn.net.cn

server.addressspring-doc.cadn.net.cn

命令发送到的服务器的地址。spring-doc.cadn.net.cn

statusspring-doc.cadn.net.cn

命令 (SUCCESSFAILED).spring-doc.cadn.net.cn

要替换默认指标标记,请定义一个MongoCommandTagsProviderbean,如以下示例所示:spring-doc.cadn.net.cn

Java
import io.micrometer.core.instrument.binder.mongodb.MongoCommandTagsProvider;

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

@Configuration(proxyBeanMethods = false)
public class MyCommandTagsProviderConfiguration {

    @Bean
    public MongoCommandTagsProvider customCommandTagsProvider() {
        return new CustomCommandTagsProvider();
    }

}
Kotlin
import io.micrometer.core.instrument.binder.mongodb.MongoCommandTagsProvider
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyCommandTagsProviderConfiguration {

    @Bean
    fun customCommandTagsProvider(): MongoCommandTagsProvider? {
        return CustomCommandTagsProvider()
    }

}

要禁用自动配置的命令指标,请设置以下属性:spring-doc.cadn.net.cn

性能
management.metrics.mongo.command.enabled=false
亚姆尔
management:
  metrics:
    mongo:
      command:
        enabled: false
MongoDB 连接池指标

自动配置注册一个MongoMetricsConnectionPoolListener使用自动配置的MongoClient.spring-doc.cadn.net.cn

为连接池创建以下仪表指标:spring-doc.cadn.net.cn

默认情况下,每个指标都使用以下信息进行标记:spring-doc.cadn.net.cn

标记 描述

cluster.idspring-doc.cadn.net.cn

连接池对应的集群的标识符。spring-doc.cadn.net.cn

server.addressspring-doc.cadn.net.cn

连接池对应的服务器的地址。spring-doc.cadn.net.cn

要替换默认指标标记,请定义一个MongoConnectionPoolTagsProvider豆:spring-doc.cadn.net.cn

Java
import io.micrometer.core.instrument.binder.mongodb.MongoConnectionPoolTagsProvider;

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

@Configuration(proxyBeanMethods = false)
public class MyConnectionPoolTagsProviderConfiguration {

    @Bean
    public MongoConnectionPoolTagsProvider customConnectionPoolTagsProvider() {
        return new CustomConnectionPoolTagsProvider();
    }

}
Kotlin
import io.micrometer.core.instrument.binder.mongodb.MongoConnectionPoolTagsProvider
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyConnectionPoolTagsProviderConfiguration {

    @Bean
    fun customConnectionPoolTagsProvider(): MongoConnectionPoolTagsProvider {
        return CustomConnectionPoolTagsProvider()
    }

}

要禁用自动配置的连接池衡量指标,请设置以下属性:spring-doc.cadn.net.cn

性能
management.metrics.mongo.connectionpool.enabled=false
亚姆尔
management:
  metrics:
    mongo:
      connectionpool:
        enabled: false

7.3.22. Jetty 指标

自动配置绑定 Jetty 的指标ThreadPool通过使用 Micrometer 的JettyServerThreadPoolMetrics. Jetty 的指标Connector实例使用 Micrometer 的JettyConnectionMetrics并且,当server.ssl.enabled设置为true, 千分尺的JettySslHandshakeMetrics.spring-doc.cadn.net.cn

7.3.23. @Timed Commentation 支持

启用扫描@Timed注释,您需要将management.observations.annotations.enabled属性设置为true. 请参阅千分尺文档spring-doc.cadn.net.cn

7.3.24. Redis 指标

自动配置注册一个MicrometerCommandLatencyRecorder对于自动配置的LettuceConnectionFactory. 有关更多详细信息,请参阅 Lettuce 文档的 Micrometer Metrics 部分spring-doc.cadn.net.cn

7.4. 注册自定义指标

要注册自定义指标,请注入MeterRegistry到你的组件中:spring-doc.cadn.net.cn

Java
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Tags;

import org.springframework.stereotype.Component;

@Component
public class MyBean {

    private final Dictionary dictionary;

    public MyBean(MeterRegistry registry) {
        this.dictionary = Dictionary.load();
        registry.gauge("dictionary.size", Tags.empty(), this.dictionary.getWords().size());
    }

}
Kotlin
import io.micrometer.core.instrument.MeterRegistry
import io.micrometer.core.instrument.Tags
import org.springframework.stereotype.Component

@Component
class MyBean(registry: MeterRegistry) {

    private val dictionary: Dictionary

    init {
        dictionary = Dictionary.load()
        registry.gauge("dictionary.size", Tags.empty(), dictionary.words.size)
    }

}

如果您的指标依赖于其他 Bean,我们建议您使用MeterBinder要注册它们:spring-doc.cadn.net.cn

Java
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.binder.MeterBinder;

import org.springframework.context.annotation.Bean;

public class MyMeterBinderConfiguration {

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

}
Kotlin
import io.micrometer.core.instrument.Gauge
import io.micrometer.core.instrument.binder.MeterBinder
import org.springframework.context.annotation.Bean

class MyMeterBinderConfiguration {

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

}

使用MeterBinder确保设置了正确的依赖关系,并且在检索度量值时 Bean 可用。 一个MeterBinder如果您发现跨组件或应用程序重复检测一套指标,则实施也很有用。spring-doc.cadn.net.cn

默认情况下,来自所有MeterBinderbean 会自动绑定到 Spring 管理的MeterRegistry.

7.5. 自定义单个指标

如果需要将自定义应用于特定Meter实例中,您可以使用io.micrometer.core.instrument.config.MeterFilter接口。spring-doc.cadn.net.cn

例如,如果要将mytag.region标签设置为mytag.area对于以com.example,您可以执行以下作:spring-doc.cadn.net.cn

Java
import io.micrometer.core.instrument.config.MeterFilter;

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

@Configuration(proxyBeanMethods = false)
public class MyMetricsFilterConfiguration {

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

}
Kotlin
import io.micrometer.core.instrument.config.MeterFilter
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyMetricsFilterConfiguration {

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

}
默认情况下,所有MeterFilterbean 会自动绑定到 Spring 管理的MeterRegistry. 确保使用 Spring 托管的MeterRegistry而不是任何静态方法Metrics. 这些使用非 Spring 管理的全局注册表。

7.5.1. 常用标签

通用标签一般用于运行环境的维度下钻,如主机、实例、地域、堆栈等。通用标签应用于所有仪表,可以配置,如下例所示:spring-doc.cadn.net.cn

性能
management.metrics.tags.region=us-east-1
management.metrics.tags.stack=prod
亚姆尔
management:
  metrics:
    tags:
      region: "us-east-1"
      stack: "prod"

前面的示例将regionstack标记添加到所有值为us-east-1prod分别。spring-doc.cadn.net.cn

如果您使用 Graphite,则常见标签的顺序很重要。由于使用这种方法无法保证常见标签的顺序,因此建议 Graphite 用户定义自定义MeterFilter相反。

7.5.2. 每米属性

除了MeterFilterbean,您可以使用属性按米应用一组有限的自定义。使用 Spring Boot 的PropertiesMeterFilter,转换为以给定名称开头的任何仪表 ID。以下示例筛选出 ID 开头为 的任何仪表example.remote.spring-doc.cadn.net.cn

性能
management.metrics.enable.example.remote=false
亚姆尔
management:
  metrics:
    enable:
      example:
        remote: false

以下属性允许按计量自定义:spring-doc.cadn.net.cn

表 1.每米定制
属性 描述

management.metrics.enablespring-doc.cadn.net.cn

是否接受具有特定 ID 的仪表。 不接受的仪表将从MeterRegistry.spring-doc.cadn.net.cn

management.metrics.distribution.percentiles-histogramspring-doc.cadn.net.cn

是否发布适合计算可聚合(跨维度)百分位近似的直方图。spring-doc.cadn.net.cn

management.metrics.distribution.minimum-expected-value,management.metrics.distribution.maximum-expected-valuespring-doc.cadn.net.cn

通过限制预期值的范围来发布更少的直方图桶。spring-doc.cadn.net.cn

management.metrics.distribution.percentilesspring-doc.cadn.net.cn

发布在应用程序中计算的百分位值spring-doc.cadn.net.cn

management.metrics.distribution.expiry,management.metrics.distribution.buffer-lengthspring-doc.cadn.net.cn

通过将最近的 Samples累积在环形缓冲区中来赋予它们更大的权重,这些缓冲区在可配置的到期后旋转,并使用 可配置的缓冲区长度。spring-doc.cadn.net.cn

management.metrics.distribution.slospring-doc.cadn.net.cn

发布累积直方图,其中包含由服务级别目标定义的存储桶。spring-doc.cadn.net.cn

有关背后概念的更多详细信息percentiles-histogram,percentilesslo,请参阅千分尺文档的“直方图和百分位数”部分spring-doc.cadn.net.cn

7.6. 指标端点

Spring Boot 提供了一个metrics端点,您可以诊断地使用它来检查应用程序收集的指标。 默认情况下,终结点不可用,必须公开。 有关更多详细信息,请参阅公开终结点spring-doc.cadn.net.cn

导航到/actuator/metrics显示可用仪表名称的列表。 您可以通过提供特定仪表的名称作为选择器来向下钻取以查看有关其信息,例如/actuator/metrics/jvm.memory.max.spring-doc.cadn.net.cn

您在此处使用的名称应与代码中使用的名称匹配,而不是为它交付到的监视系统进行命名约定规范化后的名称。 换句话说,如果jvm.memory.max显示为jvm_memory_max在 Prometheus 中,由于其蛇形命名约定,您仍然应该使用jvm.memory.max作为检查仪表时的选择器metrics端点。spring-doc.cadn.net.cn

您还可以添加任意数量的tag=KEY:VALUE查询参数到URL末尾,以对仪表进行维度向下钻取,例如,/actuator/metrics/jvm.memory.max?tag=area:nonheap.spring-doc.cadn.net.cn

报告的测量值是与仪表名称匹配的所有仪表的统计数据和已应用的任何标记的统计数据的总和。 在前面的示例中,返回的Valuestatistic 是堆的“代码缓存”、“压缩类空间”和“元空间”区域的最大内存占用量的总和。如果您只想查看“元空间”的最大大小,您可以添加一个额外的tag=id:Metaspace——也就是说,/actuator/metrics/jvm.memory.max?tag=area:nonheap&tag=id:Metaspace.spring-doc.cadn.net.cn

7.7. 与千分尺观察集成

一个DefaultMeterObservationHandler自动注册在ObservationRegistry,它为每个已完成的观察创建指标。spring-doc.cadn.net.cn

8. 追踪

Spring Boot Actuator 为 Micrometer Tracking 提供依赖管理和自动配置,Micrometer Tracking 是流行的跟踪器库的外观。spring-doc.cadn.net.cn

要了解有关千分尺追踪功能的更多信息,请参阅其参考文档

8.1. 支持的跟踪器

Spring Boot 为以下跟踪器提供自动配置:spring-doc.cadn.net.cn

8.2. 入门

我们需要一个示例应用程序,可以使用它来开始跟踪。 就我们的目的而言,“getting-started.html”部分中介绍的简单“Hello World!” Web 应用程序就足够了。 我们将使用 OpenTelemetry 跟踪器和 Zipkin 作为跟踪后端。spring-doc.cadn.net.cn

回顾一下,我们的主要应用程序代码如下所示:spring-doc.cadn.net.cn

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@SpringBootApplication
public class MyApplication {

    private static final Log logger = LogFactory.getLog(MyApplication.class);

    @RequestMapping("/")
    String home() {
        logger.info("home() has been called");
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
home()方法,这在以后会很重要。

现在我们必须添加以下依赖项:spring-doc.cadn.net.cn

添加以下应用程序属性:spring-doc.cadn.net.cn

性能
management.tracing.sampling.probability=1.0
亚姆尔
management:
  tracing:
    sampling:
      probability: 1.0

默认情况下,Spring Boot 仅采样 10% 的请求,以防止跟踪后端不堪重负。 此属性将其切换为 100%,以便将每个请求发送到跟踪后端。spring-doc.cadn.net.cn

为了收集和可视化跟踪,我们需要一个正在运行的跟踪后端。 我们在这里使用 Zipkin 作为跟踪后端。 Zipkin 快速入门指南提供了如何在本地启动 Zipkin 的说明。spring-doc.cadn.net.cn

Zipkin 运行后,您可以启动应用程序。spring-doc.cadn.net.cn

如果您打开 Web 浏览器以localhost:8080,您应该会看到以下输出:spring-doc.cadn.net.cn

Hello World!

在后台,已经为 HTTP 请求创建了一个观察,该观察又被桥接到 OpenTelemetry,后者向 Zipkin 报告新的跟踪。spring-doc.cadn.net.cn

现在打开 Zipkin UIlocalhost:9411,然后按“运行查询”按钮列出所有收集的跟踪。 您应该会看到一条痕迹。 按“显示”按钮可查看该跟踪的详细信息。spring-doc.cadn.net.cn

8.3. 记录相关 ID

相关 ID 提供了一种有用的方法,用于将日志文件中的行链接到跨度/跟踪。 如果您使用的是 Micrometer Tracing,Spring Boot 将默认在您的日志中包含相关 ID。spring-doc.cadn.net.cn

默认关联 ID 是从traceIdspanId MDC 值。 例如,如果千分尺跟踪已添加 MDCtraceId803B448A0489F84084905D3093480352和 MDCspanId3425F23BB2432450日志输出将包括相关 ID[803B448A0489F84084905D3093480352-3425F23BB2432450].spring-doc.cadn.net.cn

如果您更喜欢对相关 ID 使用不同的格式,可以使用logging.pattern.correlation属性来定义一个。 例如,以下内容将以 Spring Cloud Sleuth 以前使用的格式提供 Logback 的相关 ID:spring-doc.cadn.net.cn

性能
logging.pattern.correlation=[${spring.application.name:},%X{traceId:-},%X{spanId:-}] 
logging.include-application-name=false
亚姆尔
logging:
  pattern:
    correlation: "[${spring.application.name:},%X{traceId:-},%X{spanId:-}] "
  include-application-name: false
在上面的示例中,logging.include-application-name设置为false以避免应用程序名称在日志消息 (logging.pattern.correlation已经包含它)。 还值得一提的是logging.pattern.correlation包含尾随空格,以便它与默认情况下紧跟在它后面的记录器名称分开。

8.4. 传播跟踪

要通过网络自动传播跟踪,请使用自动配置的RestTemplateBuilder,RestClient.BuilderWebClient.Builder以构建客户端。spring-doc.cadn.net.cn

如果您创建RestTemplateRestClientWebClient如果不使用自动配置的构建器,自动跟踪传播将不起作用!

8.5. 跟踪器实现

由于 Micrometer Tracer 支持多个跟踪器实现,因此 Spring Boot 可能有多种依赖项组合。spring-doc.cadn.net.cn

所有跟踪器实现都需要org.springframework.boot:spring-boot-starter-actuatorDependency。spring-doc.cadn.net.cn

8.5.1. 使用 Zipkin 的 OpenTelemetry

使用 OpenTelemetry 进行跟踪并向 Zipkin 报告需要以下依赖项:spring-doc.cadn.net.cn

  • io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cadn.net.cn

  • io.opentelemetry:opentelemetry-exporter-zipkin- 向 Zipkin 报告痕迹。spring-doc.cadn.net.cn

使用management.zipkin.tracing.*配置属性来配置向 Zipkin 报告。spring-doc.cadn.net.cn

8.5.2. 带有波前的 OpenTelemetry

使用 OpenTelemetry 进行跟踪并向 Wavefront 报告需要以下依赖项:spring-doc.cadn.net.cn

  • io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cadn.net.cn

  • io.micrometer:micrometer-tracing-reporter-wavefront- 向 Wavefront 报告跟踪。spring-doc.cadn.net.cn

使用management.wavefront.*配置属性以配置对 Wavefront 的报告。spring-doc.cadn.net.cn

8.5.3. 使用 OTLP 的 OpenTelemetry

使用 OpenTelemetry 进行跟踪并使用 OTLP 进行报告需要以下依赖项:spring-doc.cadn.net.cn

  • io.micrometer:micrometer-tracing-bridge-otel- 将 Micrometer Observation API 桥接到 OpenTelemetry。spring-doc.cadn.net.cn

  • io.opentelemetry:opentelemetry-exporter-otlp- 向可以接受 OTLP 的收集器报告跟踪。spring-doc.cadn.net.cn

使用management.otlp.tracing.*配置属性,以使用 OTLP 配置报告。spring-doc.cadn.net.cn

8.5.4. OpenZipkin Brave 与 Zipkin

使用 OpenZipkin Brave 进行跟踪并向 Zipkin 报告需要以下依赖项:spring-doc.cadn.net.cn

如果您的项目不使用 Spring MVC 或 Spring WebFlux,则io.zipkin.reporter2:zipkin-sender-urlconnection依赖性也是需要的。

使用management.zipkin.tracing.*配置属性来配置向 Zipkin 报告。spring-doc.cadn.net.cn

8.5.5. OpenZipkin Brave 带波前

使用 OpenZipkin Brave 进行跟踪并向 Wavefront 报告需要以下依赖项:spring-doc.cadn.net.cn

使用management.wavefront.*配置属性以配置对 Wavefront 的报告。spring-doc.cadn.net.cn

8.6. 与千分尺观察集成

一个TracingAwareMeterObservationHandler自动注册在ObservationRegistry,这将为每个已完成的观测点创建跨度。spring-doc.cadn.net.cn

8.7. 创建自定义跨度

您可以通过开始观测来创建自己的跨度。 为此,注入ObservationRegistry到你的组件中:spring-doc.cadn.net.cn

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;

import org.springframework.stereotype.Component;

@Component
class CustomObservation {

    private final ObservationRegistry observationRegistry;

    CustomObservation(ObservationRegistry observationRegistry) {
        this.observationRegistry = observationRegistry;
    }

    void someOperation() {
        Observation observation = Observation.createNotStarted("some-operation", this.observationRegistry);
        observation.lowCardinalityKeyValue("some-tag", "some-value");
        observation.observe(() -> {
            // Business logic ...
        });
    }

}

这将创建一个名为“some-operation”的观察,标签为“some-tag=some-value”。spring-doc.cadn.net.cn

如果要在不创建指标的情况下创建范围,则需要使用较低级别Tracer应用程序接口来自千分尺。

8.8. 行李

您可以使用Tracer应用程序接口:spring-doc.cadn.net.cn

import io.micrometer.tracing.BaggageInScope;
import io.micrometer.tracing.Tracer;

import org.springframework.stereotype.Component;

@Component
class CreatingBaggage {

    private final Tracer tracer;

    CreatingBaggage(Tracer tracer) {
        this.tracer = tracer;
    }

    void doSomething() {
        try (BaggageInScope scope = this.tracer.createBaggageInScope("baggage1", "value1")) {
            // Business logic
        }
    }

}

此示例创建名为baggage1与值value1. 如果您使用的是 W3C 传播,则行李会自动通过网络传播。如果您使用的是 B3 传播,则行李不会自动传播。要通过网络手动传播行李,请使用management.tracing.baggage.remote-fieldsconfiguration 属性(这也适用于 W3C)。对于上面的示例,将此属性设置为baggage1结果为 HTTP 标头baggage1: value1.spring-doc.cadn.net.cn

如果要将行李传播到 MDC,请使用management.tracing.baggage.correlation.fieldsconfiguration 属性。对于上面的示例,将此属性设置为baggage1导致名为baggage1.spring-doc.cadn.net.cn

8.9. 测试

使用@SpringBootTest. 有关更多详细信息,请参阅测试部分spring-doc.cadn.net.cn

9. 审计

一旦 Spring Security 开始运行,Spring Boot Actuator 就有一个灵活的审计框架,可以发布事件(默认情况下,“身份验证成功”、“失败”和“访问被拒绝”异常)。此功能对于报告和实施基于身份验证失败的锁定策略非常有用。spring-doc.cadn.net.cn

您可以通过提供类型为AuditEventRepository在应用程序的配置中。 为方便起见,Spring Boot 提供了一个InMemoryAuditEventRepository.InMemoryAuditEventRepository功能有限,建议仅将其用于开发环境。 对于生产环境,请考虑创建自己的替代项AuditEventRepository实现。spring-doc.cadn.net.cn

9.1. 自定义审计

要自定义已发布的安全事件,您可以提供自己的实现AbstractAuthenticationAuditListenerAbstractAuthorizationAuditListener.spring-doc.cadn.net.cn

您还可以将审计服务用于您自己的业务事件。 为此,请将AuditEventRepositorybean 到您自己的组件中并直接使用它或发布AuditApplicationEvent与Spring一起ApplicationEventPublisher(通过实现ApplicationEventPublisherAware).spring-doc.cadn.net.cn

10. 记录 HTTP 交换

您可以通过提供类型为HttpExchangeRepository在应用程序的配置中。 为方便起见,Spring Boot 提供InMemoryHttpExchangeRepository,默认情况下,它存储最近 100 个请求-响应交换。InMemoryHttpExchangeRepository与跟踪解决方案相比有限,我们建议仅将其用于开发环境。 对于生产环境,建议使用生产就绪的跟踪或可观测性解决方案,例如 Zipkin 或 OpenTelemetry。 或者,您可以创建自己的HttpExchangeRepository.spring-doc.cadn.net.cn

您可以使用httpexchangesendpoint 以获取有关存储在HttpExchangeRepository.spring-doc.cadn.net.cn

10.1. 自定义 HTTP 交换记录

要自定义每个记录的交换中包含的项目,请使用management.httpexchanges.recording.includeconfiguration 属性。spring-doc.cadn.net.cn

要完全禁用录制,请将management.httpexchanges.recording.enabledfalse.spring-doc.cadn.net.cn

11. 过程监控

spring-boot模块中,您可以找到两个类来创建通常对进程监控有用的文件:spring-doc.cadn.net.cn

  • ApplicationPidFileWriter创建一个包含应用程序 PID 的文件(默认情况下,在文件名为application.pid).spring-doc.cadn.net.cn

  • WebServerPortFileWriter创建一个(或多个文件),其中包含正在运行的 Web 服务器的端口(默认情况下,在文件名为application.port).spring-doc.cadn.net.cn

默认情况下,这些写入器不会激活,但您可以启用它们:spring-doc.cadn.net.cn

11.1. 扩展配置

META-INF/spring.factories文件,您可以激活写入 PID 文件的监听器(或监听器):spring-doc.cadn.net.cn

org.springframework.context.ApplicationListener=\
org.springframework.boot.context.ApplicationPidFileWriter,\
org.springframework.boot.web.context.WebServerPortFileWriter

11.2. 以编程方式启用进程监控

您还可以通过调用SpringApplication.addListeners(…​)方法并传递适当的Writer对象。 此方法还允许您自定义文件名和路径Writer构造 函数。spring-doc.cadn.net.cn

12. Cloud Foundry 支持

Spring Boot 的执行器模块包括额外的支持,当您部署到兼容的 Cloud Foundry 实例时,这些支持会激活。 这/cloudfoundryapplicationpath 为所有@Endpoint豆。spring-doc.cadn.net.cn

扩展支持允许使用 Spring Boot 执行器信息增强 Cloud Foundry 管理 UI(例如可用于查看已部署应用程序的 Web 应用程序)。例如,应用程序状态页面可以包含完整的运行状况信息,而不是典型的“正在运行”或“已停止”状态。spring-doc.cadn.net.cn

/cloudfoundryapplication普通用户无法直接访问路径。 若要使用终结点,必须在请求中传递有效的 UAA Tokens。

12.1. 禁用扩展的 Cloud Foundry 执行器支持

如果您想完全禁用/cloudfoundryapplicationendpoints,您可以将以下设置添加到application.properties文件:spring-doc.cadn.net.cn

性能
management.cloudfoundry.enabled=false
亚姆尔
management:
  cloudfoundry:
    enabled: false

12.2. Cloud Foundry 自签名证书

默认情况下,安全验证/cloudfoundryapplicationendpoints 对各种 Cloud Foundry 服务进行 SSL 调用。 如果您的 Cloud Foundry UAA 或 Cloud Controller 服务使用自签名证书,则需要设置以下属性:spring-doc.cadn.net.cn

性能
management.cloudfoundry.skip-ssl-validation=true
亚姆尔
management:
  cloudfoundry:
    skip-ssl-validation: true

12.3. 自定义上下文路径

如果服务器的上下文路径已配置为 以外的任何内容,那么 Cloud Foundry 端点在应用程序的根目录中不可用。 例如,如果/server.servlet.context-path=/app,Cloud Foundry 端点可在以下位置获得/app/cloudfoundryapplication/*.spring-doc.cadn.net.cn

如果您希望 Cloud Foundry 端点始终在/cloudfoundryapplication/*,无论服务器的上下文路径如何,您都需要在应用程序中显式配置它。 配置因使用的 Web 服务器而异。 对于 Tomcat,您可以添加以下配置:spring-doc.cadn.net.cn

Java
import java.io.IOException;
import java.util.Collections;

import jakarta.servlet.GenericServlet;
import jakarta.servlet.Servlet;
import jakarta.servlet.ServletContainerInitializer;
import jakarta.servlet.ServletContext;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import org.apache.catalina.Host;
import org.apache.catalina.core.StandardContext;
import org.apache.catalina.startup.Tomcat;

import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.servlet.ServletContextInitializer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class MyCloudFoundryConfiguration {

    @Bean
    public TomcatServletWebServerFactory servletWebServerFactory() {
        return new TomcatServletWebServerFactory() {

            @Override
            protected void prepareContext(Host host, ServletContextInitializer[] initializers) {
                super.prepareContext(host, initializers);
                StandardContext child = new StandardContext();
                child.addLifecycleListener(new Tomcat.FixContextListener());
                child.setPath("/cloudfoundryapplication");
                ServletContainerInitializer initializer = getServletContextInitializer(getContextPath());
                child.addServletContainerInitializer(initializer, Collections.emptySet());
                child.setCrossContext(true);
                host.addChild(child);
            }

        };
    }

    private ServletContainerInitializer getServletContextInitializer(String contextPath) {
        return (classes, context) -> {
            Servlet servlet = new GenericServlet() {

                @Override
                public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException {
                    ServletContext context = req.getServletContext().getContext(contextPath);
                    context.getRequestDispatcher("/cloudfoundryapplication").forward(req, res);
                }

            };
            context.addServlet("cloudfoundry", servlet).addMapping("/*");
        };
    }

}
Kotlin
import jakarta.servlet.GenericServlet
import jakarta.servlet.Servlet
import jakarta.servlet.ServletContainerInitializer
import jakarta.servlet.ServletContext
import jakarta.servlet.ServletException
import jakarta.servlet.ServletRequest
import jakarta.servlet.ServletResponse
import org.apache.catalina.Host
import org.apache.catalina.core.StandardContext
import org.apache.catalina.startup.Tomcat.FixContextListener
import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory
import org.springframework.boot.web.servlet.ServletContextInitializer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import java.io.IOException
import java.util.Collections.emptySet

@Configuration(proxyBeanMethods = false)
class MyCloudFoundryConfiguration {

    @Bean
    fun servletWebServerFactory(): TomcatServletWebServerFactory {
        return object : TomcatServletWebServerFactory() {

            override fun prepareContext(host: Host, initializers: Array<ServletContextInitializer>) {
                super.prepareContext(host, initializers)
                val child = StandardContext()
                child.addLifecycleListener(FixContextListener())
                child.path = "/cloudfoundryapplication"
                val initializer = getServletContextInitializer(contextPath)
                child.addServletContainerInitializer(initializer, emptySet())
                child.crossContext = true
                host.addChild(child)
            }

        }
    }

    private fun getServletContextInitializer(contextPath: String): ServletContainerInitializer {
        return ServletContainerInitializer { classes: Set<Class<*>?>?, context: ServletContext ->
            val servlet: Servlet = object : GenericServlet() {

                @Throws(ServletException::class, IOException::class)
                override fun service(req: ServletRequest, res: ServletResponse) {
                    val servletContext = req.servletContext.getContext(contextPath)
                    servletContext.getRequestDispatcher("/cloudfoundryapplication").forward(req, res)
                }

            }
            context.addServlet("cloudfoundry", servlet).addMapping("/*")
        }
    }
}

如果您使用的是基于 Webflux 的应用程序,则可以使用以下配置:spring-doc.cadn.net.cn

Java
import java.util.Map;

import reactor.core.publisher.Mono;

import org.springframework.boot.autoconfigure.web.reactive.WebFluxProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.server.reactive.ContextPathCompositeHandler;
import org.springframework.http.server.reactive.HttpHandler;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.web.server.adapter.WebHttpHandlerBuilder;

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(WebFluxProperties.class)
public class MyReactiveCloudFoundryConfiguration {

    @Bean
    public HttpHandler httpHandler(ApplicationContext applicationContext, WebFluxProperties properties) {
        HttpHandler httpHandler = WebHttpHandlerBuilder.applicationContext(applicationContext).build();
        return new CloudFoundryHttpHandler(properties.getBasePath(), httpHandler);
    }

    private static final class CloudFoundryHttpHandler implements HttpHandler {

        private final HttpHandler delegate;

        private final ContextPathCompositeHandler contextPathDelegate;

        private CloudFoundryHttpHandler(String basePath, HttpHandler delegate) {
            this.delegate = delegate;
            this.contextPathDelegate = new ContextPathCompositeHandler(Map.of(basePath, delegate));
        }

        @Override
        public Mono<Void> handle(ServerHttpRequest request, ServerHttpResponse response) {
            // Remove underlying context path first (e.g. Servlet container)
            String path = request.getPath().pathWithinApplication().value();
            if (path.startsWith("/cloudfoundryapplication")) {
                return this.delegate.handle(request, response);
            }
            else {
                return this.contextPathDelegate.handle(request, response);
            }
        }

    }

}
Kotlin
import org.springframework.boot.autoconfigure.web.reactive.WebFluxProperties
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.ApplicationContext
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.server.reactive.ContextPathCompositeHandler
import org.springframework.http.server.reactive.HttpHandler
import org.springframework.http.server.reactive.ServerHttpRequest
import org.springframework.http.server.reactive.ServerHttpResponse
import org.springframework.web.server.adapter.WebHttpHandlerBuilder
import reactor.core.publisher.Mono

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(WebFluxProperties::class)
class MyReactiveCloudFoundryConfiguration {

    @Bean
    fun httpHandler(applicationContext: ApplicationContext, properties: WebFluxProperties): HttpHandler {
        val httpHandler = WebHttpHandlerBuilder.applicationContext(applicationContext).build()
        return CloudFoundryHttpHandler(properties.basePath, httpHandler)
    }

    private class CloudFoundryHttpHandler(basePath: String, private val delegate: HttpHandler) : HttpHandler {
        private val contextPathDelegate = ContextPathCompositeHandler(mapOf(basePath to delegate))

        override fun handle(request: ServerHttpRequest, response: ServerHttpResponse): Mono<Void> {
            // Remove underlying context path first (e.g. Servlet container)
            val path = request.path.pathWithinApplication().value()
            return if (path.startsWith("/cloudfoundryapplication")) {
                delegate.handle(request, response)
            } else {
                contextPathDelegate.handle(request, response)
            }
        }
    }
}

13. 接下来要读什么

您可能想阅读有关图形工具的信息,例如 Graphitespring-doc.cadn.net.cn

否则,您可以继续阅读有关“部署选项”的信息,或跳转到有关 Spring Boot 构建工具插件的一些深入信息。spring-doc.cadn.net.cn