Spring Boot Actuator 监控 + 可观测性 -----21

 

 

内置监控端点、自定义健康检查、动态运维能力、OpenTelemetry 链路追踪、Trace ID 透传。基于 Spring Boot 3.x 自动配置，极少代码实现生产级可观测能力，严格遵循行业最佳实践。

---

一、项目结构（极简 5 个文件）

plaintext

 

 

com.example.observability
├── ObservabilityApplication.java    # 启动类
├── config
│   ├── CustomHealthIndicator.java   # 自定义健康检查
│   └── TraceIdFilter.java           # 全局响应返回Trace ID
└── controller└── DemoController.java          # 测试接口

 

 

配置文件：src/main/resources/application.yml

---

二、第一步：pom.xml 核心依赖

xml

 <?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.2.0</version></parent><groupId>com.example</groupId><artifactId>actuator-observability-demo</artifactId><version>1.0.0</version><properties><java.version>17</java.version></properties><dependencies><!-- Web 基础 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- Actuator 内置监控端点（核心）对应215集 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency><!-- Prometheus 指标格式（生产监控标准）对应218集 --><dependency><groupId>io.micrometer</groupId><artifactId>micrometer-registry-prometheus</artifactId></dependency><!-- OpenTelemetry 链路追踪桥接 对应221~223集 --><!-- 零侵入自动生成调用链路，无需手写代码 --><dependency><groupId>io.micrometer</groupId><artifactId>micrometer-tracing-bridge-otel</artifactId></dependency><!-- Lombok 简化代码 --><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency></dependencies>
</project>

 

---

三、第二步：全局配置 application.yml

一次性配置好：端点暴露规则、健康详情、应用元数据、链路采样、日志格式、日志文件

yaml

 

 
spring:application:name: observability-demo# ========== Actuator 监控配置（对应215~220集） ==========
management:endpoints:web:exposure:# 暴露所有端点（学习用）；生产建议只暴露 health,info,prometheusinclude: "*"endpoint:health:show-details: always  # 健康检查显示详细信息shutdown:enabled: true         # 开启远程停机端点（对应220集，生产谨慎开启）info:env:enabled: true         # 开启info元数据端点（对应219集）# 应用元数据（info端点返回，对应219集）
info:app:name: observability-demoversion: 1.0.0author: demodescription: Spring Boot 可观测性演示项目# ========== 日志配置（打印Trace ID） ==========
logging:pattern:console: "%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] [%X{traceId}/%X{spanId}] %logger{36} : %msg%n"file:name: ./logs/app.log  # 日志文件路径，可通过 /actuator/logfile 在线查看# ========== 链路追踪配置（对应222~223集） ==========tracing:sampling:probability: 1.0  # 采样率：1.0=全采样（学习用），生产建议0.1~0.3

 

 

---

四、第三步：启动类

java

 

运行

 

 

package com.example.observability;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication
public class ObservabilityApplication {public static void main(String[] args) {SpringApplication.run(ObservabilityApplication.class, args);}
}

 

---

五、第四步：自定义健康检查（对应 216 集）

扩展系统健康检查，增加业务维度的健康状态监控

java

 

运行

 

 
package com.example.observability.config;import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;/*** 自定义业务健康检查* 访问 /actuator/health 时会自动包含此检查项*/
@Component
public class CustomHealthIndicator implements HealthIndicator {@Overridepublic Health health() {// 这里可以写真实的业务检查逻辑：// 比如第三方接口连通性、缓存状态、队列堆积量等boolean bizServiceIsUp = true;if (bizServiceIsUp) {return Health.up().withDetail("status", "业务服务正常").withDetail("queueSize", 12).build();} else {return Health.down().withDetail("error", "业务服务异常").build();}}
}

 

 

---

六、第五步：全局 Trace ID 透传（对应 225 集）

所有接口响应头自动返回 X-Trace-Id，前端可直接获取，用于问题排查

java

 

运行

 

 

package com.example.observability.config;import io.micrometer.tracing.Tracer;
import jakarta.servlet.*;
import jakarta.servlet.http.HttpServletResponse;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;import java.io.IOException;/*** 全局过滤器：所有响应头自动添加 Trace ID* 对应225集：让客户端能看到Trace ID*/
@Component
@RequiredArgsConstructor
public class TraceIdFilter implements Filter {private final Tracer tracer;@Overridepublic void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)throws IOException, ServletException {HttpServletResponse httpResp = (HttpServletResponse) response;// 从链路上下文获取当前Trace ID，放入响应头if (tracer.currentSpan() != null) {String traceId = tracer.currentSpan().context().traceId();httpResp.addHeader("X-Trace-Id", traceId);}chain.doFilter(request, response);}
}

 

 

---

七、第六步：测试接口

java

 

运行

 

 

package com.example.observability.controller;import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@Slf4j
@RestController
@RequestMapping("/api/demo")
public class DemoController {@GetMapping("/hello")public String hello() {log.info("收到hello请求");return "Hello Observability!";}@GetMapping("/user/{id}")public String getUser(@PathVariable Long id) {log.info("查询用户信息，userId={}", id);// 模拟业务处理return "用户" + id + "的信息";}
}

 

---

八、核心功能验证方式

1. Actuator 常用端点（对应 215~220 集）

启动后浏览器直接访问：

表格

 

端点地址	功能说明	对应课程
http://localhost:8080/actuator	所有可用端点列表	215
http://localhost:8080/actuator/health	应用健康状态（含自定义检查）	216
http://localhost:8080/actuator/info	应用元数据信息	219
http://localhost:8080/actuator/beans	Spring 容器所有 Bean	217
http://localhost:8080/actuator/env	环境变量与配置	217
http://localhost:8080/actuator/metrics	运行指标列表	218
http://localhost:8080/actuator/prometheus	Prometheus 格式指标	218
http://localhost:8080/actuator/logfile	在线查看日志文件	220
http://localhost:8080/actuator/loggers	动态调整日志级别（POST）	220
POST /actuator/shutdown	远程优雅停机应用	220

2. 可观测性验证（对应 221~225 集）

1. 调用 http://localhost:8080/api/demo/hello
2. 查看控制台日志：每行日志都自动带有 [traceId/spanId]
3. 查看响应头：自动包含 X-Trace-Id 字段，前端可直接获取

---

九、课程对应表

表格

 

集数	核心内容	对应代码 / 配置
215	Actuator 内置健康监控	pom.xml 引入 actuator + 基础端点
216	健康检查使用与扩展	CustomHealthIndicator 自定义健康检查
217	查看 Bean、配置、环境变量	/actuator/beans、/actuator/env 端点
218	指标、日志、映射实时洞察	metrics、prometheus、logfile 端点
219	应用元数据智能暴露	info 配置 + /actuator/info 端点
220	停机、缓存、日志控制高级用法	shutdown 端点、loggers 动态调级别
221	可观测性与 OpenTelemetry 介绍	OTel 依赖引入 + 自动配置
222	可观测技术栈（Micrometer/OTEL/LGTM）	micrometer-tracing-bridge-otel 桥接
223	极少代码实现可观测性	自动配置，零侵入生成链路
224	链路、指标、日志实战	日志打印 traceId + Prometheus 指标
225	客户端可见 Trace ID	TraceIdFilter 全局响应头透传

---

十、生产级最佳实践总结

1. 端点安全
   • 生产环境绝对不要 include: "*"，只暴露必要的 health, info, prometheus
   • 敏感端点加 Spring Security 保护，设置账号密码才能访问
   • shutdown 端点生产默认关闭，需要时再开启
2. 链路追踪
   • 生产环境采样率不要 100%，建议 10%~30%，降低性能损耗
   • Trace ID 统一透传到响应头，方便前后端联合排查问题
   • 日志必须打印 traceId，实现日志 - 链路关联
3. 指标监控
   • 统一用 Prometheus 格式，对接 Grafana 可视化
   • 核心业务接口自定义业务指标（下单量、注册量等）
4. 健康检查
   • 除了系统默认检查，补充核心依赖的健康检查（数据库、缓存、MQ、第三方接口）
   • 健康检查详情只对内网暴露，公网只返回 UP/DOWN 状态