跳到主要内容

服务健康监控

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 组件详解
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向 yudao-cloud 的服务健康监控体系，围绕“心跳检测、状态上报、异常告警”和“Prometheus 监控集成（指标采集、数据暴露、可视化）”两大主题，系统梳理访问日志过滤器在请求跟踪、性能统计与安全审计中的作用，并提供监控配置说明、指标定义、告警规则与性能基线建议，以及监控数据分析与故障诊断流程。

项目结构​

  • 监控相关能力分布于多个模块：
    • 网关层：提供全局访问日志过滤器，记录请求/响应关键信息，便于性能与安全审计。
    • Web 层：提供 API 访问日志过滤器，统一记录接口调用、参数脱敏、结果与耗时，支撑运营分析与审计。
    • 链路追踪层：提供 Trace 过滤器与工具类，输出 trace-id 并贯穿请求链路，便于跨服务关联定位。
    • 监控指标层：通过 Micrometer 自动装配，统一打点与标签，结合 Actuator 暴露端点。
    • 健康与告警：通过 Spring Boot Admin 与 Prometheus 控制器对接，实现服务发现与告警接收。
    • 配置层：集中于公共配置文件，开放 Actuator 端点、启用 Admin 与指标标签等。

Mermaid Diagram Code:

graph TB
subgraph "网关层"
G1["AccessLogFilter<br/>全局访问日志过滤器"]
end
subgraph "Web层"
W1["ApiAccessLogFilter<br/>API访问日志过滤器"]
end
subgraph "链路追踪"
T1["TraceFilter<br/>Trace 过滤器"]
T2["TracerUtils<br/>Trace 工具类"]
end
subgraph "监控指标"
M1["YudaoMetricsAutoConfiguration<br/>指标标签配置"]
end
subgraph "健康与告警"
H1["PrometheusController<br/>服务发现/告警接收"]
H2["AdminServerConfiguration<br/>Spring Boot Admin"]
H3["ActuatorEnvironmentPostProcessor<br/>健康检查配置注入"]
end
subgraph "配置"
C1["application-common.yaml<br/>Actuator/指标/Admin 配置"]
end
G1 --> |"记录请求/响应/耗时"| W1
W1 --> |"携带 TraceId"| T1
T1 --> T2
M1 --> |"commonTags"| C1
H1 --> |"服务发现/告警"| C1
H2 --> C1
H3 --> C1

图表来源

章节来源

核心组件​

  • 访问日志过滤器（网关）：在网关层对请求/响应进行记录，支持 JSON/Form 请求体读取与响应体合并输出，便于性能与安全审计。
  • 访问日志过滤器（Web）：在业务服务层统一记录接口调用详情，含用户、请求参数、响应体、耗时、操作模块/类型等，支持敏感字段脱敏。
  • 链路追踪过滤器与工具：在响应头输出 trace-id，便于跨服务串联日志与指标，定位问题。
  • 指标与标签：通过 Micrometer 自动装配，统一添加 commonTags，便于多维度聚合分析。
  • Prometheus 集成：提供服务发现接口与告警接收端点，配合注册中心动态发现服务实例。
  • Spring Boot Admin：启用 Admin Server，集中展示各服务实例健康状态与指标概览。
  • Actuator 健康检查：通过配置开放所有端点，便于外部系统（如 Prometheus）抓取指标与健康状态。

章节来源

架构总览​

下图展示了监控体系的关键交互：网关与业务服务分别产生访问日志；链路追踪为跨服务串联提供 trace-id；Micrometer 暴露指标；Prometheus 通过服务发现抓取；Spring Boot Admin 聚合健康状态；Actuator 暴露健康与指标端点。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant GW as "网关 AccessLogFilter"
participant SVC as "业务服务 ApiAccessLogFilter"
participant TR as "TraceFilter/TracerUtils"
participant METRICS as "Micrometer/YudaoMetricsAutoConfiguration"
participant PROM as "PrometheusController"
participant REG as "注册中心"
participant ADMIN as "Spring Boot Admin"
Client->>GW : 请求到达
GW->>GW : 记录请求/响应/耗时
GW->>SVC : 转发请求
SVC->>TR : 输出响应头 trace-id
SVC->>SVC : 记录访问日志(含脱敏)
SVC->>METRICS : 指标打点(带 commonTags)
PROM->>REG : GET /actuator/prometheus/sd
REG-->>PROM : 服务实例列表
PROM-->>PROM : 组装 targets/labels
PROM-->>Client : 返回服务发现结果
ADMIN-->>ADMIN : 聚合服务健康与指标

图表来源

组件详解​

访问日志过滤器（网关）​

  • 功能要点
    • 记录请求方法、URL、查询参数、请求头、用户 IP、开始时间。
    • 对 JSON/Form 请求体进行读取并记录；对响应体进行合并输出，支持 JSON 美化展示。
    • 计算耗时并统一输出到日志，便于性能分析与安全审计。
  • 性能与安全
    • 仅对特定媒体类型（JSON/FORM）读取请求体，避免对大体积/非结构化请求造成额外开销。
    • 通过日志输出而非数据库落盘，降低对下游存储的压力（可按需扩展为异步落库）。

Mermaid Diagram Code:

flowchart TD
Start(["进入过滤器"]) --> ReadHdr["读取请求头与基础信息"]
ReadHdr --> MediaType{"媒体类型为 JSON/FORM?"}
MediaType --> |是| ReadBody["读取请求体并记录"]
MediaType --> |否| NoBody["不读取请求体"]
ReadBody --> WrapResp["包装响应体记录器"]
NoBody --> WrapResp
WrapResp --> Chain["继续链路处理"]
Chain --> Calc["计算耗时/设置响应信息"]
Calc --> Log["输出访问日志"]
Log --> End(["完成"])

图表来源

章节来源

访问日志过滤器（Web）​

  • 功能要点
    • 统一记录接口调用详情：用户、请求参数、响应体、耗时、结果码/消息、操作模块/类型。
    • 支持敏感字段脱敏（如 password、token 等），并对响应体 data 字段进行脱敏保护。
    • 通过注解控制是否记录与记录范围（请求/响应），默认对后台管理接口严格记录。
  • 审计与分析
    • 结合 trace-id 与登录用户信息，支持跨服务审计与问题复盘。
    • 提供导出能力，便于离线分析与合规审计。

Mermaid Diagram Code:

flowchart TD
Enter(["进入过滤器"]) --> StartT["记录开始时间/提取参数"]
StartT --> Chain["继续链路处理"]
Chain --> Result{"是否异常?"}
Result --> |否| BuildOK["构建访问日志(正常)"]
Result --> |是| BuildErr["构建访问日志(异常)"]
BuildOK --> Sanitize["敏感字段脱敏"]
BuildErr --> Sanitize
Sanitize --> AsyncLog["异步写入日志(接口)"]
AsyncLog --> Exit(["完成"])

图表来源

章节来源

链路追踪过滤器与工具​

  • 功能要点
    • 在响应头输出 trace-id，便于客户端与下游服务串联日志。
    • 提供工具类获取 trace-id，贯穿日志与指标采集。
    • 对生产环境机顶盒 API 特例进行过滤，避免不必要的处理。
  • 价值
    • 跨服务定位问题、关联访问日志与指标，提升排障效率。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant F as "TraceFilter"
participant U as "TracerUtils"
Client->>F : 发起请求
F->>F : 设置响应头 trace-id
F-->>Client : 返回响应(含 trace-id)
Client->>U : 获取 trace-id(用于日志/指标)

图表来源

章节来源

指标与标签（Micrometer）​

  • 功能要点
    • 自动装配 MeterRegistry，统一添加 commonTags（如 application），便于多维度聚合。
    • 通过配置开关控制是否启用指标（yudao.metrics.enable）。
  • 价值
    • 为 Prometheus 等监控系统提供标准化指标，便于统一展示与告警。

章节来源

Prometheus 集成​

  • 服务发现
    • 提供 /actuator/prometheus/sd 接口，从注册中心获取服务列表，组装 targets 与 labels（如 __meta_prometheus_job）。
  • 告警接收
    • 提供 /actuator/prometheus/alerts 接口接收告警消息，便于统一处理与联动。
  • 与 Actuator 的关系
    • Actuator 端点全面开放，便于外部系统抓取健康与指标。

Mermaid Diagram Code:

sequenceDiagram
participant P as "Prometheus"
participant C as "PrometheusController"
participant DC as "DiscoveryClient"
P->>C : GET /actuator/prometheus/sd
C->>DC : getServices()
DC-->>C : 服务列表
loop 遍历每个服务
C->>DC : getInstances(service)
DC-->>C : 实例列表(host : port)
C->>C : 组装 targets/labels
end
C-->>P : 返回服务发现结果(JSON)

图表来源

章节来源

Spring Boot Admin​

  • 功能要点
    • 启用 Admin Server，集中展示服务实例健康状态与指标概览。
    • 与 Actuator 配合，统一暴露健康与指标端点。
  • 价值
    • 提供可视化的服务治理界面，便于运维人员快速掌握整体健康状况。

章节来源

Actuator 健康检查配置​

  • 功能要点
    • 开放所有 Actuator 端点（include: '*'），便于外部系统抓取健康与指标。
    • Elasticsearch 健康检查可按需关闭（通过 EnvironmentPostProcessor 注入属性）。
  • 价值
    • 为 Prometheus、Spring Boot Admin 等提供统一的数据源。

章节来源

依赖关系分析​

  • 组件耦合
    • 访问日志过滤器（网关/Web）与链路追踪工具存在协作关系：Web 层日志记录会使用 trace-id，便于跨服务串联。
    • 指标配置与 Actuator 配置共同决定监控数据的暴露方式与范围。
    • Prometheus 控制器依赖注册中心，实现动态服务发现。
  • 外部依赖
    • Micrometer：指标打点与标签。
    • Spring Boot Admin：健康与指标可视化。
    • 注册中心：服务发现。

Mermaid Diagram Code:

graph LR
GW["AccessLogFilter"] --> SVC["ApiAccessLogFilter"]
SVC --> TR["TracerUtils"]
SVC --> METRICS["YudaoMetricsAutoConfiguration"]
PROM["PrometheusController"] --> REG["注册中心"]
PROM --> ACT["Actuator"]
ADMIN["AdminServerConfiguration"] --> ACT

图表来源

章节来源

性能考量​

  • 访问日志
    • 网关层仅对 JSON/FORM 类型请求体进行读取，避免对非结构化或大体积请求造成额外开销。
    • 响应体合并输出采用缓冲区合并策略，减少多次 I/O。
  • 日志记录
    • Web 层采用异步写入日志接口，避免阻塞主请求链路。
    • 敏感字段脱敏在 JSON 层进行，尽量减少异常开销。
  • 指标与标签
    • commonTags 统一打点，便于聚合分析，同时避免重复标签导致的指标膨胀。
  • Actuator
    • 开放所有端点便于抓取，但需关注安全边界与访问控制，避免未授权访问。

[本节为通用指导，不直接分析具体文件]

故障排查指南​

  • 无法获取 trace-id
    • 检查 TraceFilter 是否生效，确认响应头是否包含 trace-id。
    • 确认 TracerUtils 是否能正确获取 trace-id。
  • 访问日志缺失
    • 网关层：确认请求媒体类型是否为 JSON/FORM，否则不会读取请求体。
    • Web 层：确认接口是否标注 @ApiAccessLog 或满足后台管理接口记录条件。
    • 确认敏感字段脱敏是否移除了关键字段。
  • 指标未暴露
    • 检查 Actuator 端点是否开放（include: '*'）。
    • 检查 yudao.metrics.enable 配置是否启用。
  • Prometheus 无法抓取
    • 检查 /actuator/prometheus/sd 返回的服务发现结果是否正确。
    • 检查注册中心是否正常，实例是否注册成功。
  • Spring Boot Admin 无健康信息
    • 检查 Actuator 端点是否开放，Admin Server 是否启用。
    • 检查服务实例注册信息与健康状态。

章节来源

结论​

yudao-cloud 的监控体系通过“网关访问日志 + 业务访问日志 + 链路追踪 + 指标标签 + Prometheus 集成 + Spring Boot Admin”的组合，实现了从请求可观测性到服务健康态的全链路覆盖。建议在生产环境中：

  • 明确日志保留周期与清理策略；
  • 基于 trace-id 建立跨服务问题定位流程；
  • 结合 Prometheus 与 Grafana 建立关键指标看板；
  • 制定告警阈值与升级流程，确保异常及时处置。

[本节为总结性内容，不直接分析具体文件]

附录​

监控配置清单​

  • Actuator 端点开放
    • base-path: /actuator
    • exposure.include: '*'
  • Spring Boot Admin
    • admin.context-path: /admin
    • 实例优先使用 IP 注册
  • 指标标签
    • commonTags: application=${spring.application.name}
  • Prometheus 集成
    • 服务发现接口: /actuator/prometheus/sd
    • 告警接收接口: /actuator/prometheus/alerts
  • Elasticsearch 健康检查
    • 可通过 EnvironmentPostProcessor 关闭健康检查

章节来源

监控指标与告警建议​

  • 指标建议
    • QPS、P95/P99 响应时间、错误率、线程池/连接池使用率、GC 次数与耗时。
  • 告警规则建议
    • 错误率超过阈值、P99 响应时间超过阈值、实例不可用、关键依赖超时。
  • 性能基线
    • 基于历史峰值与 SLA 设定阈值，结合业务高峰时段调整。

[本节为通用指导，不直接分析具体文件]

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答