DDK Tracer Starter

基于 Micrometer Tracing + OpenTelemetry 的链路追踪，DDK 额外做一件事：每个 HTTP 响应都带上本次请求的 traceId，调用方报障时贴上这个值，就能直接定位整条调用链。

能做什么

HTTP 请求
  ServerHttpObservationFilter   HIGHEST_PRECEDENCE + 1   Spring Boot 开启请求 span
  TraceIdResponseFilter         HIGHEST_PRECEDENCE + 2   写入 X-Trace-Id: <traceId>
  DispatcherServlet
    Controller → Service → Repository                    子 span 共享同一个 traceId

能力	提供方
Tracer、上下文传播、采样	spring-boot-starter-opentelemetry，management.tracing.*
导出到 OTLP	opentelemetry-exporter-otlp，management.otlp.*
日志里的 traceId / spanId	Spring Boot 自动加入日志关联字段，logging.pattern.correlation
traceId 响应头	本 starter，ddk.tracer.*

引入方式

<dependency>
    <groupId>com.ddk</groupId>
    <artifactId>ddk-tracer-starter</artifactId>
    <version>${ddk.version}</version>
</dependency>

传递引入 Spring Boot 4 的 spring-boot-starter-opentelemetry（包含 Micrometer Tracing 的 OTel 桥接与 OTLP 导出器），不再引入整个 actuator。

management:
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://otel-collector:4318/v1/traces

配置项

配置项	类型	默认值	说明
ddk.tracer.response-header.enabled	boolean	true	是否把 traceId 写进响应头
ddk.tracer.response-header.name	String	X-Trace-Id	响应头名称

浏览器端要读取这个头，需要在 DDK Web Starter 中配置 ddk.web.cors.exposed-headers=X-Trace-Id。

装配条件与降级行为

• 自动配置类：com.ddk.tracer.starter.config.DdkTracerAutoConfiguration，after = MicrometerTracingAutoConfiguration，确保判断 Tracer 是否存在时 Boot 已注册完。
• 过滤器只在 Servlet Web 应用且容器里有 Tracer 时注册。spring-web 与 Servlet API 是可选依赖，非 Web 应用引入不会被带上 Web 依赖。
• 过滤器在调用后续过滤器链之前写头：响应一旦提交，之后设置的头会被静默丢弃。
• 当前没有活动 span（例如关闭了 HTTP 观测）时不写头，请求照常处理。

不适用的场景 / 已知问题

1. 默认采样率是 Boot 的 10%。未被采样的请求仍会返回 traceId，但链路系统里查不到；排查偶发问题时要调高 management.tracing.sampling.probability。
2. 不带 actuator 端点。需要 /actuator/** 健康检查或指标端点时，自行引入 spring-boot-starter-actuator 并收敛暴露范围。
3. 只带了 OTLP 导出器。要用 Zipkin 等其他协议需自行加依赖。
4. WebFlux 应用不注册响应头过滤器，目前只支持 Servlet 栈。
5. 没有验证 span 真的导出到后端，那需要起一个 OTLP Collector 做集成测试。