OpenTelemetry

wow-opentelemetry 为命令/事件发送、聚合、EventStore、SnapshotStore、投影、Saga、事件处理和等待计划创建 tracing instrumenter。需要跨服务定位延迟与错误时使用；只需要 Micrometer 指标时无需引入它。

该模块只创建 span 和传播上下文，不初始化 OpenTelemetry SDK、Agent、sampler、exporter 或 Collector。GlobalOpenTelemetry 必须在 Wow instrumenter 创建前完成初始化。

安装

implementation("me.ahoo.wow:wow-spring-boot-starter") {
    capabilities { requireCapability("me.ahoo.wow:opentelemetry-support") }
}

非 Spring 应用可直接依赖 me.ahoo.wow:wow-opentelemetry，但必须自行装饰 bus/store/gateway 并注册 filters。classpath 只有模块并不会自动完成这些工作。

OTLP 快速接入

最小运行路径是让 Java Agent 在应用启动前初始化全局实例：

export JAVA_TOOL_OPTIONS="-javaagent:/opt/otel/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME=order-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
java -jar app.jar

endpoint、protocol、headers、采样和资源属性属于 Agent/SDK。Wow module check 或本地 span 只证明 instrumentation 行为；Collector/backend receipt 才证明导出成功。

配置

Wow 只有一个开关，默认开启：

wow:
  opentelemetry:
    enabled: true

设为 false 只停止 Wow tracing filters/decorators，不停止 Java Agent 或其他库的 span。不要重复配置两套 exporter；指标仍由 Micrometer Registry 负责，详见可观测性配置。

链路追踪如何装配

WowOpenTelemetryAutoConfiguration 注册 aggregate、projection、snapshot、stateless Saga、event processor 五类 filter。TracingBeanPostProcessor 以最高优先级装饰受支持的 local/distributed buses、EventStore、SnapshotStore 和 CommandGateway，并通过 Traced 防止重复包装。

Reactor publisher 在订阅时创建 span，在完成、错误、取消或同步 subscribe 异常时结束。消息 producer 注入上下文，consumer/exchange 从消息恢复；属性只出现在注册了对应 extractor 的 instrumenter 上，不能假设所有 span 都有全部 wow.message.*/wow.aggregate.* 字段。

已验证失败边界：全局 SDK 初始化过晚会让已创建 instrumenter 使用旧全局实例；底层 publisher 错误会记录到 span 并继续传播；关闭开关后只移除 Wow 埋点，不改变业务调用。聚焦检查：

./gradlew :wow-opentelemetry:check

链路追踪示例

一条命令通常形成 command send/wait → aggregate handler → event append/send → projection/Saga/snapshot 的父子链。实际 span 是否出现取决于该路径是否运行、采样是否保留以及 exporter 是否成功。

下一步阅读可观测性了解 span/属性合同，再用目标 Collector 保存真实 trace receipt。