spring-boot-actuator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spring Boot Actuator Skill

Spring Boot Actuator 技能文档

Overview

概述

Deliver production-ready observability for Spring Boot services using Actuator endpoints, probes, and Micrometer integration.
Standardize health, metrics, and diagnostics configuration while delegating deep reference material to
```
references/
```
.
Support platform requirements for secure operations, SLO reporting, and incident diagnostics.

借助Actuator端点、探针和Micrometer集成，为Spring Boot服务提供生产就绪的可观测性。
标准化健康检查、指标和诊断配置，详细参考资料请查阅
```
references/
```
目录。
满足安全操作、SLO报告和事件诊断的平台要求。

When to Use

适用场景

Trigger: "enable actuator endpoints" – Bootstrap Actuator for a new or existing Spring Boot service.
Trigger: "secure management port" – Apply Spring Security policies to protect management traffic.
Trigger: "configure health probes" – Define readiness and liveness groups for orchestrators.
Trigger: "export metrics to prometheus" – Wire Micrometer registries and tune metric exposure.
Trigger: "debug actuator startup" – Inspect condition evaluations and startup metrics when endpoints are missing or slow.

触发条件："enable actuator endpoints" – 为新的或已有的Spring Boot服务启动Actuator。
触发条件："secure management port" – 应用Spring Security策略保护管理流量。
触发条件："configure health probes" – 为编排工具定义就绪性和存活性分组。
触发条件："export metrics to prometheus" – 配置Micrometer注册中心并调整指标暴露规则。
触发条件："debug actuator startup" – 当端点缺失或响应缓慢时，检查条件评估和启动指标。

Quick Start

快速开始

Add the starter dependency.

xml

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

gradle

// Gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-actuator"
}

Restart the service and verify
```
/actuator/health
```
and
```
/actuator/info
```
respond with
```
200 OK
```
.

添加启动器依赖。

xml

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

gradle

// Gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-actuator"
}

重启服务，验证
```
/actuator/health
```
和
```
/actuator/info
```
返回
```
200 OK
```
状态。

Implementation Workflow

实施流程

1. Expose the required endpoints

1. 暴露所需端点

Set
```
management.endpoints.web.exposure.include
```
to the precise list or
```
"*"
```
for internal deployments.

Adjust

management.endpoints.web.base-path

(e.g.,

/management

) when the default

/actuator

conflicts with routing.

Review detailed endpoint semantics in
```
references/endpoint-reference.md
```
.

将
```
management.endpoints.web.exposure.include
```
设置为精确的端点列表，内部部署可使用
```
"*"
```
。
当默认路径
```
/actuator
```
与路由冲突时，调整
```
management.endpoints.web.base-path
```
（例如
```
/management
```
）。
端点详细语义请查阅
```
references/endpoint-reference.md
```
。

2. Secure management traffic

2. 保护管理流量

Apply an isolated

SecurityFilterChain

using

EndpointRequest.toAnyEndpoint()

with role-based rules.

Combine
```
management.server.port
```
with firewall controls or service mesh policies for operator-only access.
Keep
```
/actuator/health/**
```
publicly accessible only when required; otherwise enforce authentication.

使用
```
EndpointRequest.toAnyEndpoint()
```
创建独立的
```
SecurityFilterChain
```
，应用基于角色的规则。
结合
```
management.server.port
```
与防火墙控制或服务网格策略，仅允许运维人员访问。
仅在必要时保持
```
/actuator/health/**
```
可公开访问，否则强制要求身份验证。

3. Configure health probes

3. 配置健康探针

Enable

management.endpoint.health.probes.enabled=true

for

/health/liveness

and

/health/readiness

Group indicators via
```
management.endpoint.health.group.*
```
to match platform expectations.

Implement custom indicators by extending

HealthIndicator

ReactiveHealthContributor

; sample implementations live in

references/examples.md#custom-health-indicator

启用

management.endpoint.health.probes.enabled=true

，以支持

/health/liveness

和

/health/readiness

端点。

通过
```
management.endpoint.health.group.*
```
配置指标分组，以匹配平台预期。

继承

HealthIndicator

或

ReactiveHealthContributor

实现自定义指标；示例代码请见

references/examples.md#custom-health-indicator

。

4. Publish metrics and traces

4. 发布指标与追踪

Activate Micrometer exporters (Prometheus, OTLP, Wavefront, StatsD) via
```
management.metrics.export.*
```
.
Apply
```
MeterRegistryCustomizer
```
beans to add
```
application
```
,
```
environment
```
, and business tags for observability correlation.
Surface HTTP request metrics with
```
server.observation.*
```
configuration when using Spring Boot 3.2+.

通过
```
management.metrics.export.*
```
激活Micrometer导出器（Prometheus、OTLP、Wavefront、StatsD）。
应用
```
MeterRegistryCustomizer
```
Bean，添加
```
application
```
、
```
environment
```
和业务标签，以实现可观测性关联。
使用Spring Boot 3.2+时，通过
```
server.observation.*
```
配置暴露HTTP请求指标。

5. Enable diagnostics tooling

5. 启用诊断工具

Turn on
```
/actuator/startup
```
(Spring Boot 3.5+) and
```
/actuator/conditions
```
during incident response to inspect auto-configuration decisions.

HttpExchangeRepository

(e.g.,

InMemoryHttpExchangeRepository

) before enabling

/actuator/httpexchanges

for request auditing.

Consult
```
references/official-actuator-docs.md
```
for endpoint behaviors and limits.

在事件响应期间，开启
```
/actuator/startup
```
（Spring Boot 3.5+）和
```
/actuator/conditions
```
端点，检查自动配置决策。

在启用

/actuator/httpexchanges

进行请求审计前，注册

HttpExchangeRepository

（例如

InMemoryHttpExchangeRepository

）。

端点行为和限制请参考
```
references/official-actuator-docs.md
```
。

Examples

示例

Basic – Expose health and info safely

基础示例 – 安全暴露健康与信息端点

yaml

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: never

yaml

management:
  endpoints:
    web:
      exposure:
        include: "health,info"
  endpoint:
    health:
      show-details: never

Intermediate – Readiness group with custom indicator

中级示例 – 包含自定义指标的就绪性分组

java

@Component
public class PaymentsGatewayHealth implements HealthIndicator {

    private final PaymentsClient client;

    public PaymentsGatewayHealth(PaymentsClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        boolean reachable = client.ping();
        return reachable ? Health.up().withDetail("latencyMs", client.latency()).build()
                         : Health.down().withDetail("error", "Gateway timeout").build();
    }
}

yaml

management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        readiness:
          include: "readinessState,db,paymentsGateway"
          show-details: always

java

@Component
public class PaymentsGatewayHealth implements HealthIndicator {

    private final PaymentsClient client;

    public PaymentsGatewayHealth(PaymentsClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        boolean reachable = client.ping();
        return reachable ? Health.up().withDetail("latencyMs", client.latency()).build()
                         : Health.down().withDetail("error", "Gateway timeout").build();
    }
}

yaml

management:
  endpoint:
    health:
      probes:
        enabled: true
      group:
        readiness:
          include: "readinessState,db,paymentsGateway"
          show-details: always

Advanced – Dedicated management port with Prometheus export

高级示例 – 独立管理端口与Prometheus导出

yaml

management:
  server:
    port: 9091
    ssl:
      enabled: true
  endpoints:
    web:
      exposure:
        include: "health,info,metrics,prometheus"
      base-path: "/management"
  metrics:
    export:
      prometheus:
        descriptions: true
        step: 30s
  endpoint:
    health:
      show-details: when-authorized
      roles: "ENDPOINT_ADMIN"

java

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(c -> c
                .requestMatchers(EndpointRequest.to("health")).permitAll()
                .anyRequest().hasRole("ENDPOINT_ADMIN"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

More end-to-end samples are available in

references/examples.md

yaml

management:
  server:
    port: 9091
    ssl:
      enabled: true
  endpoints:
    web:
      exposure:
        include: "health,info,metrics,prometheus"
      base-path: "/management"
  metrics:
    export:
      prometheus:
        descriptions: true
        step: 30s
  endpoint:
    health:
      show-details: when-authorized
      roles: "ENDPOINT_ADMIN"

java

@Configuration
public class ActuatorSecurityConfig {

    @Bean
    SecurityFilterChain actuatorChain(HttpSecurity http) throws Exception {
        http.securityMatcher(EndpointRequest.toAnyEndpoint())
            .authorizeHttpRequests(c -> c
                .requestMatchers(EndpointRequest.to("health")).permitAll()
                .anyRequest().hasRole("ENDPOINT_ADMIN"))
            .httpBasic(Customizer.withDefaults());
        return http.build();
    }
}

更多端到端示例请见

references/examples.md

。

Best Practices

最佳实践

Keep SKILL.md concise and rely on
```
references/
```
for verbose documentation to conserve context.
Apply the principle of least privilege: expose only required endpoints and restrict sensitive ones.
Use immutable configuration via profile-specific YAML to align environments.
Monitor actuator traffic separately to detect scraping abuse or brute-force attempts.
Automate regression checks by scripting
```
curl
```
probes in CI/CD pipelines.

保持SKILL.md简洁，详细文档请依赖
```
references/
```
目录，以节省上下文空间。
应用最小权限原则：仅暴露必要端点，并限制敏感端点的访问。
通过环境特定的YAML文件使用不可变配置，以对齐不同环境。
单独监控Actuator流量，以检测抓取滥用或暴力破解尝试。
在CI/CD流水线中编写
```
curl
```
探针脚本，自动化回归检查。

Constraints

约束条件

Avoid exposing

/actuator/env

/actuator/configprops

/actuator/logfile

, and

/actuator/heapdump

on public networks.

Do not ship custom health indicators that block event loop threads or exceed 250 ms unless absolutely necessary.
Ensure Actuator metrics exporters run on supported Micrometer registries; unsupported exporters require custom registry beans.
Maintain compatibility with Spring Boot 3.5.x conventions; older versions may lack probes and observation features.

请勿在公网环境暴露

/actuator/env

、

/actuator/configprops

、

/actuator/logfile

和

/actuator/heapdump

端点。

除非绝对必要，否则不要部署会阻塞事件循环线程或响应时间超过250毫秒的自定义健康指标。
确保Actuator指标导出器运行在受支持的Micrometer注册中心；不支持的导出器需要自定义注册中心Bean。
保持与Spring Boot 3.5.x约定的兼容性；旧版本可能缺少探针和观测功能。

Reference Materials

参考资料

Endpoint quick reference
Implementation examples
Official documentation extract
Auditing with Actuator
Cloud Foundry integration
Enabling Actuator features
HTTP exchange recording
JMX exposure
Monitoring and metrics
Logging configuration
Metrics exporters
Observability with Micrometer
Process and Monitoring
Tracing
Scripts directory (
```
scripts/
```
) reserved for future automation; no runtime dependencies today.

端点快速参考
实施示例
官方文档摘要
Actuator审计
Cloud Foundry集成
启用Actuator功能
HTTP请求记录
JMX暴露
监控与指标
日志配置
指标导出器
Micrometer可观测性
进程与监控
追踪
脚本目录(
```
scripts/
```
)预留用于未来自动化；当前无运行时依赖。

Validation Checklist

验证清单

Confirm
```
mvn spring-boot:run
```
or
```
./gradlew bootRun
```
exposes expected endpoints under
```
/actuator
```
(or custom base path).
Verify
```
/actuator/health/readiness
```
returns
```
UP
```
with all mandatory components before promoting to production.

Scrape

/actuator/metrics

/actuator/prometheus

to ensure required meters (

http.server.requests

jvm.memory.used

) are present.

Run security scans to validate only intended ports and endpoints are reachable from outside the trusted network.

确认
```
mvn spring-boot:run
```
或
```
./gradlew bootRun
```
在
```
/actuator
```
（或自定义基础路径）下暴露了预期的端点。
在推广到生产环境前，验证
```
/actuator/health/readiness
```
返回
```
UP
```
状态且所有必填组件正常。

抓取

/actuator/metrics

或

/actuator/prometheus

，确保存在所需指标（如

http.server.requests

、

jvm.memory.used

）。

运行安全扫描，验证可信网络外仅能访问预期的端口和端点。