Skip to content

feat(observability): add generic request correlation and tracing foundation #663

Description

@XiaoSeS

背景

当前 SkillHub 已在异步搜索索引场景中暴露出两个不同层次的问题:

  1. 通用日志关联与链路追踪基础设施不足。
  2. 搜索索引异步重建缺少可靠交付、失败补偿和重放机制。

本 Issue 只处理第 1 项。第 2 项继续由 #597 独立跟踪,不把日志追踪实现和搜索业务耦合。

建设内容

  • 统一校验、生成和传播 X-Request-Id,并保持响应、日志和异步任务的一致关联。
  • 使用 ECS 风格 JSON 日志,输出 request.idtrace.idspan.id 等关联字段,默认不输出 Authorization、Cookie 等敏感请求头。
  • 基于 Micrometer Tracing + OpenTelemetry bridge 提供可插拔链路追踪。
  • 提供 noneotel-sdkexternal-agent 三种互斥部署模式;OTLP 导出仅在显式配置 endpoint 时启用。
  • 传播线程池、Redis Stream scanner 消息和支持的 HTTP 边界上下文。
  • 追踪后端保持可替换,支持通过 OTel Collector 对接 SkyWalking、Elasticsearch/Kibana 等基础设施。

非目标

  • 搜索索引可靠队列、重试、死信、补偿和重放。
  • 动态采样、多租户采样策略和完整企业观测平台。
  • 将日志追踪逻辑写入搜索业务流程。

验收与验证

最终实现由 #664 承载,验证身份如下:

  • PR head:9290fe3ca222964335f94949506a40849fffc5aa
  • 集成验证 big-mainb459b1a82c686603ec0929c68ef69a067943c898

验证结果:

  • targeted tracing regression:13 tests,0 failures,0 errors。
  • Java 21 skillhub-app -am 后端回归通过。
  • 结构化测试矩阵:12/12 通过。
  • 当前 PR head exact-SHA 本地 release preview 通过 smoke 和 runtime auth-config 检查。
  • 集成 big-main 三组件生产镜像 revision 均匹配 b459b1a82c686603ec0929c68ef69a067943c898
  • 共享远端测试机隔离验证:22/22 断言通过,0 failures,0 warnings。
  • 远端覆盖镜像身份、动态 loopback 端口、release smoke、Web runtime config、Request ID 合法/缺失/非法路径、ECS JSON 日志、异常日志隐私、bootstrap admin 登录、发布测试 Skill、Redis Stream scanner 异步 request.id + traceparent 传播、异常扫描、cleanup 和既有 runtime 保持。
  • PR CI、DCO、CLA 和公开内容隐私扫描通过;PR 当前为 MERGEABLE/CLEAN

关联

Metadata

Metadata

Assignees

No one assigned

    Labels

    effort/l大改动或高风险改动,需要 maintainer 负责 / Large or risky change requiring maintainer ownership.priority/p2中优先级 / Medium priority triage bucket.triage/needs-info需要补充更多信息后才能分流 / Issue needs more detail before it can be routed.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions