架构与系统设计 / 系统课时
异步消息如何串起 Trace
异步消息如何串起 Trace
生产端显示发送成功,消费端却只剩孤立日志时,需要连接的是消息两端的执行上下文,而不只是复制一个编号。本篇通过可运行的消息传输实验,把请求、发送和消费关联起来,并明确重试、批量消费和采样时的边界。
学习目标
- 区分追踪上下文、消息标识与业务关联标识。
- 在发送前注入上下文,在消费入口提取并创建处理 Span。
- 验证跨消息的关联关系,避免重试与并发造成错误串链。
消息头中的标识各管什么
Trace 表示关联执行链路,Span 表示其中一次操作。跨进程传播应使用标准传播器处理上下文,而不是让消费者照抄生产者的 Span ID。W3C 定义了 traceparent 和 tracestate 的格式与处理规则。([W3C][1])
| 字段 | 作用 | 本例约定 |
|---|---|---|
traceparent |
携带 Trace ID、上游 Span ID 和追踪标志 | 由 SDK 注入和解析 |
tracestate |
携带厂商相关追踪状态 | 有值时随上下文传播 |
message_id |
标识一条业务事件 | 普通重投保留同一个值 |
correlation_id |
关联同一业务流程中的事件和日志 | 跨多个 Trace 也可保留 |
后两项是应用自定义契约,不是 W3C 的追踪头。Trace ID 可能随重新建链而变化,因此不要拿它代替稳定的事件标识,更不能直接把它当成幂等键。
把关联关系放在正确的执行边界
发送端先创建生产者 Span,再把当前上下文注入消息头;消费端提取消息头,随后创建消费者 Span。注入必须发生在消息交给传输层之前,提取必须发生在业务处理之前。([OpenTelemetry][2])
单条消息可以让处理 Span 使用消息创建上下文作为父节点。OpenTelemetry 消息语义约定也使用 Span Link 表达关联;批量或已有本地父上下文时,不能假设所有消费都会出现在同一棵父子树中。下面选择单消息父子模式,同时保留 Link。([OpenTelemetry][3])

发送 Span 覆盖发送操作,不要为了等待消费者而一直保持它开启。消息排队、实际处理是不同阶段;父 Span 已结束,不妨碍稍后创建与其关联的消费 Span。
运行最小传播实验
准备 Python 3.11 或更高版本,在 Bash 终端执行下面的安装命令。示例固定使用 OpenTelemetry Python 1.42.1,不依赖真实消息中间件或追踪后端。([PyPI][4])
# 在已激活的独立 Python 环境中安装固定版本。
python -m pip install -q opentelemetry-api==1.42.1 opentelemetry-sdk==1.42.1 &&
python -c "from importlib.metadata import version; print(version('opentelemetry-sdk'))"预期输出中的版本校验行如下;安装工具可能另有提示。
1.42.1将下面完整程序保存为 trace_demo.py,执行 python trace_demo.py。程序使用 JSON 往返模拟传输边界,并显式从空上下文提取消息头,避免同进程上下文造成“看似传播成功”的假象。
import json
from uuid import uuid4
from opentelemetry import trace
from opentelemetry.context import Context
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
from opentelemetry.trace import Link, SpanKind
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
def main() -> None:
# 内存导出便于断言;全量采样只用于本地实验。
exporter = InMemorySpanExporter()
provider = TracerProvider(sampler=ALWAYS_ON)
provider.add_span_processor(SimpleSpanProcessor(exporter))
tracer = provider.get_tracer("message-trace-demo")
propagator = TraceContextTextMapPropagator()
with tracer.start_as_current_span("request", kind=SpanKind.SERVER):
with tracer.start_as_current_span("send orders", kind=SpanKind.PRODUCER):
headers = {"message_id": str(uuid4()), "correlation_id": str(uuid4())}
# 必须在发送 Span 内注入,再将消息交给传输层。
propagator.inject(headers)
wire = json.dumps({"headers": headers, "event": "OrderConfirmed"})
# 两个上游 Span 均已结束;空上下文排除同进程隐式继承。
message = json.loads(wire)
remote = propagator.extract(message["headers"], context=Context())
parent = trace.get_current_span(remote).get_span_context()
links = [Link(parent)] if parent.is_valid else []
with tracer.start_as_current_span(
"process orders", context=remote, kind=SpanKind.CONSUMER, links=links
) as consumer:
consumer.set_attribute("messaging.message.id", message["headers"]["message_id"])
consumer.set_attribute("app.correlation_id", message["headers"]["correlation_id"])
sc = consumer.get_span_context()
print(f"trace_id={sc.trace_id:032x} span_id={sc.span_id:016x}")
print(f"message_id={message['headers']['message_id']}")
# 断言针对实际导出的 Span,而不是只比较手工填写的日志。
spans = {span.name: span for span in exporter.get_finished_spans()}
request = spans["request"]
sent = spans["send orders"]
processed = spans["process orders"]
assert request.context.trace_id == sent.context.trace_id == processed.context.trace_id
assert len({span.context.span_id for span in spans.values()}) == 3
assert sent.parent.span_id == request.context.span_id
assert processed.parent.span_id == sent.context.span_id
assert processed.parent.is_remote
assert processed.links[0].context.span_id == sent.context.span_id
print("verified: same trace, distinct spans, remote parent")
provider.shutdown()
if __name__ == "__main__":
main()预期输出如下:
trace_id=<ID> span_id=<ID>
message_id=<ID>
verified: same trace, distinct spans, remote parent三个 <ID> 是不同的动态值:Trace ID 为 32 位十六进制,Span ID 为 16 位十六进制,消息标识为本例生成的 UUID。最后一行说明三个 Span 共用 Trace、Span ID 各不相同,而且消费 Span 的远程父节点确实是发送 Span。([W3C][1])
从实验迁移到真实消费入口
本例只验证上下文传播,不验证 Broker、确认机制或网络导出。接入时,把字典映射为客户端实际支持的消息头,明确字符串与字节的编码,并检查重试、转发后这些头是否仍然保留。
在消费者业务回调中提取上下文,让处理 Span 覆盖实际业务执行。上下文作用域必须在成功和异常路径上都退出;本例的 with 会恢复此前上下文,不能把上一条消息的活动上下文留给下一条。([OpenTelemetry][2])
生产环境还需配置实际导出器与追踪后端;仅有消息头不会自动生成追踪页面。优先确认现有自动埋点已做了什么,避免再包一层重复 Span。验收时同时检查消息头、业务日志中的当前 Trace/Span 标识,以及后端中的父节点或 Link。([OpenTelemetry Python][5])
重试、批量与看不到 Trace 的边界
每次重试建立新的处理 Span,按业务契约保留事件标识并记录尝试次数,不复用已结束的 Span。批量处理涉及多个来源时,用多个 Link 关联来源上下文,不要任意挑第一条消息代表整个批次;使用新 Trace 加 Link 也可以保留因果关联。([OpenTelemetry][3])
消息头存在但后端看不到 Span 时,继续检查采样、导出错误和后端保留范围。上下文传播与数据被记录、导出不是同一件事,因此不能把“查不到 Trace”直接解释为消息丢失。([OpenTelemetry][6])
串起异步追踪的验收标准,是能从消费处理找到真实的发送来源,并区分每一次处理尝试,而不是所有日志恰好打印了同一个字符串。