监控组件 (yudao-spring-boot-starter-monitor)

引用文件

本文引用的文件

简介

yudao-spring-boot-starter-monitor 是一个面向微服务的监控组件，围绕链路追踪（BizTrace）、Prometheus 指标采集（Micrometer + Prometheus）、SkyWalking 集成、日志聚合与 Spring Boot Admin 客户端能力，提供开箱即用的可观测性支撑。其特性包括：

业务埋点注解与 AOP 切面，自动记录业务维度标签（如业务类型、业务编号）
响应头注入 trace-id，便于跨服务追踪
Prometheus 指标统一打点与通用标签
SkyWalking 工具包集成，支持 OpenTracing 与日志增强
Spring Boot Admin 客户端能力，用于服务发现与健康状态上报

项目结构

监控组件采用按功能域划分的模块化组织方式，核心代码位于 tracer 子包中，并通过 AutoConfiguration 自动装配。

Mermaid Diagram Code:

graph TB
subgraph "监控组件(yudao-spring-boot-starter-monitor)"
A["注解<br/>BizTrace.java"]
B["AOP切面<br/>BizTraceAspect.java"]
C["工具类<br/>TracerFrameworkUtils.java"]
D["过滤器<br/>TraceFilter.java"]
E["自动配置<br/>YudaoTracerAutoConfiguration.java"]
F["指标配置<br/>YudaoMetricsAutoConfiguration.java"]
G["工具类(公共)<br/>TracerUtils.java"]
H["POM 依赖<br/>pom.xml"]
end
A --> B
B --> C
D --> G
E --> B
E --> D
F --> H
G --> D

图表来源

章节来源

核心组件

业务埋点注解与切面：通过 BizTrace 注解与 BizTraceAspect 切面，自动在方法执行前后创建/完成 Span，并设置业务标签（biz.type、biz.id），同时捕获异常并标记错误。
过滤器：TraceFilter 在请求响应阶段向响应头注入 trace-id，便于客户端与下游服务关联。
自动配置：YudaoTracerAutoConfiguration 与 YudaoMetricsAutoConfiguration 分别负责链路追踪与指标的自动装配与启用控制。
SkyWalking 集成：通过 SkyWalking 提供的 OpenTracing 工具包与日志增强组件，实现链路与日志的统一。
指标采集：基于 Micrometer 与 Prometheus，提供通用标签与指标注册能力。

章节来源

架构总览

监控组件通过自动配置装配切面与过滤器，结合 SkyWalking 与 Micrometer，形成“业务埋点 + 链路追踪 + 指标采集”的一体化监控体系。

Mermaid Diagram Code:

graph TB
Client["客户端/网关"] --> F["TraceFilter<br/>注入 trace-id"]
F --> Svc["业务服务"]
Svc --> AOP["BizTraceAspect<br/>创建/结束Span"]
AOP --> OT["OpenTracing/SkyWalking"]
Svc --> MET["Micrometer<br/>Prometheus指标"]
OT --> SW["SkyWalking OAP"]
MET --> PROM["Prometheus Server"]

图表来源

组件详解

业务埋点注解与 AOP 切面（BizTrace + BizTraceAspect）

注解 BizTrace 定义了业务维度的关键字段：操作名、业务类型与业务编号的标签键名，并要求在 SkyWalking OAP 侧配置可搜索标签以支持查询。
切面 BizTraceAspect 在方法环绕执行期间：
- 构造 Span，设置组件标签为 biz
- 若自定义 operationName 非空则使用前缀拼接；否则默认使用类名/方法名
- 解析表达式获取业务类型与业务编号，设置到 Span 标签
- 捕获异常并记录到 Span，标记错误
- 最终完成 Span 生命周期

Mermaid Diagram Code:

classDiagram
class BizTrace {
+String operationName()
+String id()
+String type()
}
class BizTraceAspect {
-Tracer tracer
+around(joinPoint, trace) Object
-getOperationName(joinPoint, trace) String
-setBizTag(span, joinPoint, trace) void
}
class TracerFrameworkUtils {
+onError(throwable, span) void
}
BizTraceAspect --> BizTrace : "读取注解"
BizTraceAspect --> TracerFrameworkUtils : "异常记录"

图表来源

章节来源

调用链路收集流程（序列图）

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant F as "TraceFilter"
participant S as "业务方法"
participant A as "BizTraceAspect"
participant T as "Tracer(OpenTracing/SkyWalking)"
C->>F : "HTTP 请求"
F-->>C : "响应头添加 trace-id"
C->>S : "携带 trace-id 调用"
S->>A : "进入带 @BizTrace 的方法"
A->>T : "创建 Span 并设置标签"
A->>S : "执行原方法"
S-->>A : "返回或抛出异常"
A->>T : "异常记录/完成 Span"
A-->>C : "响应返回"

图表来源

指标采集与 Prometheus（YudaoMetricsAutoConfiguration）

通过条件注解启用：当存在 MeterRegistryCustomizer 类且 yudao.metrics.enable 为 true（默认启用）时生效
为所有指标添加通用标签 application=应用名，便于多实例聚合与筛选
依赖 micrometer-registry-prometheus，Prometheus 可直接抓取指标端点

Mermaid Diagram Code:

flowchart TD
Start(["启动"]) --> Check["检查 yudao.metrics.enable 与 MeterRegistryCustomizer"]
Check --> |满足| AddTags["注册 MeterRegistryCustomizer<br/>添加通用标签 application"]
Check --> |不满足| Skip["跳过指标配置"]
AddTags --> Export["Prometheus 抓取指标"]
Skip --> End(["完成"])
Export --> End

图表来源

章节来源

SkyWalking 集成与日志聚合

通过 apm-toolkit-trace、apm-toolkit-logback-1.x、apm-toolkit-opentracing 三个 SkyWalking 工具包，实现：
- OpenTracing 兼容的追踪上下文
- 日志增强，使日志与 TraceId 关联
- OpenTracing API 的桥接
需要在 SkyWalking OAP 侧将 biz.type、biz.id 加入可搜索标签，以便在 UI 中检索业务维度

章节来源

pom.xml

过滤器与 trace-id 注入（TraceFilter）

在响应阶段向 Header 写入 trace-id，便于客户端与下游服务进行链路关联
对特定设备 API（生产环境机顶盒）进行豁免，避免不必要的处理

章节来源

TraceFilter.java

自动配置与启用控制

链路追踪自动配置：当存在 BizTraceAspect 与 Servlet Filter 类时启用；可通过 yudao.tracer.enable 控制，默认启用
指标自动配置：当存在 MeterRegistryCustomizer 且 yudao.metrics.enable=true 时启用

章节来源

依赖关系分析

组件依赖 SkyWalking OpenTracing 工具包与 Micrometer Prometheus 注册器
提供 Arthas 与 Spring Boot Admin 客户端能力，便于线上诊断与服务治理

Mermaid Diagram Code:

graph LR
P["pom.xml"] --> SW1["apm-toolkit-trace"]
P --> SW2["apm-toolkit-logback-1.x"]
P --> SW3["apm-toolkit-opentracing"]
P --> MIC["micrometer-registry-prometheus"]
P --> ART["arthas-spring-boot-starter"]
P --> SBA["spring-boot-admin-starter-client"]

图表来源

pom.xml

章节来源

pom.xml

性能考量

AOP 切面与过滤器均为轻量级逻辑，对请求延迟影响较小
指标采集默认开启，建议在高并发场景下关注标签基数与抓取频率
SkyWalking 日志与追踪需评估 OAP 存储与查询成本
建议在生产环境对特定设备 API 豁免 trace-id 注入，减少无意义开销

故障排查指南

无法看到业务标签（biz.type/biz.id）：确认 SkyWalking OAP 已将相应键加入可搜索标签
trace-id 未出现在响应头：检查 yudao.tracer.enable 是否为 true，以及是否命中 shouldNotFilter 的豁免条件
指标未上报：确认 yudao.metrics.enable=true，Prometheus 抓取端点可达，且应用名正确注入通用标签
异常未标记：确保 BizTraceAspect 正常执行，异常被捕获并调用 onError 记录

章节来源

结论

yudao-spring-boot-starter-monitor 通过 BizTrace 注解与 AOP 切面实现了业务维度的链路追踪，结合 SkyWalking 与 Micrometer，提供了从链路到指标的完整监控能力。配合 TraceFilter 的 trace-id 注入与 Spring Boot Admin 客户端，能够快速定位问题并进行性能观测。

附录

配置选项与启用方式

链路追踪启用：yudao.tracer.enable=true（默认启用）
指标采集启用：yudao.metrics.enable=true（默认启用）
SkyWalking OAP 配置：将 biz.type、biz.id 加入可搜索标签键集合

章节来源

监控数据可视化建议

链路追踪：在 SkyWalking UI 中按 trace-id 或业务标签（biz.type、biz.id）检索调用链
指标可视化：在 Prometheus/Grafana 中基于 application 通用标签进行聚合与告警

扩展点与高级特性

自定义指标：通过 MeterRegistry 注册自定义指标，利用通用标签进行多维分析
监控规则与告警：结合 Prometheus 抓取与告警规则，或在 Spring Boot Admin 中配置健康检查与告警
自定义埋点：在关键业务方法上使用 BizTrace 注解，设置 operationName、type、id，实现业务维度的链路追踪

章节来源

目录​

简介​

项目结构​

核心组件​

架构总览​

组件详解​

业务埋点注解与 AOP 切面（BizTrace + BizTraceAspect）​

调用链路收集流程（序列图）​

指标采集与 Prometheus（YudaoMetricsAutoConfiguration）​

SkyWalking 集成与日志聚合​

过滤器与 trace-id 注入（TraceFilter）​

自动配置与启用控制​

依赖关系分析​

性能考量​

故障排查指南​

结论​

附录​

配置选项与启用方式​

监控数据可视化建议​

扩展点与高级特性​

目录

简介

项目结构

核心组件

架构总览

组件详解

业务埋点注解与 AOP 切面（BizTrace + BizTraceAspect）

调用链路收集流程（序列图）

指标采集与 Prometheus（YudaoMetricsAutoConfiguration）

SkyWalking 集成与日志聚合

过滤器与 trace-id 注入（TraceFilter）

自动配置与启用控制

依赖关系分析

性能考量

故障排查指南

结论

附录

配置选项与启用方式

监控数据可视化建议

扩展点与高级特性