架构与系统设计 / 系统课时

异步消息如何串起 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])

bash
# 在已激活的独立 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'))"

预期输出中的版本校验行如下;安装工具可能另有提示。

text
1.42.1

将下面完整程序保存为 trace_demo.py,执行 python trace_demo.py。程序使用 JSON 往返模拟传输边界,并显式从空上下文提取消息头,避免同进程上下文造成“看似传播成功”的假象。

python
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()

预期输出如下:

text
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])

串起异步追踪的验收标准,是能从消费处理找到真实的发送来源,并区分每一次处理尝试,而不是所有日志恰好打印了同一个字符串。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

异步消息如何串起 Trace

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通