OpenTelemetry 分布式追踪工程化完全指南:从一次"P99 8 秒但 Zipkin 只显示 800ms"看懂为什么加 Sleuth 远远不够

2023 年我们公司有一套微服务系统 跑在 Kubernetes 上 大概 80 个 service 分布在 6 个 namespace。一开始我们用 spring-cloud 的 Sleuth 接 Zipkin 做调用链追踪 看起来该有的都有 trace_id span_id 服务调用关系图谱也能画出来 看上去很完整。但真正发生故障的时候我们才发现一系列问题。第一种最让我傻眼 某天业务报告下单接口慢 P99 8 秒 我打开 Zipkin 找到对应 trace 一看 8 个 span 总耗时加起来才 800ms 但用户那边明明就是 8 秒 我才意识到我们漏了网关 漏了 service mesh sidecar 漏了客户端到第一个服务之间的网络耗时 trace 不完整。第二种最难缠 我们用了 Sleuth 自动埋点 但有几个内部的异步任务用了线程池 trace_id 没有透传 一查 Zipkin 这些任务的调用链是断的 半个业务流程看不见。第三种最离谱 我们的采样率设了 10% 平时没事 出故障那次因为采样恰好没采到关键链路 全靠日志 grep 拼出调用关系 排查时间被拖了 4 小时。第四种最致命 上线了新版本 trace 数据量瞬间翻倍 ElasticSearch 索引写不进 Zipkin 报错满天飞 storage 容量爆了 backend 整个挂了 trace 全员失明。第五种最莫名其妙 同一个请求在网关 trace_id 是 abc 到了第二跳变成了 xyz 排查发现是中间一个 NGINX 反向代理没有 forward X-B3-TraceId 头 链路断点彻底失踪。我盯着这一连串问题想了很久才彻底想明白第一版错在一个根本的认知上我以为 调用链追踪就是加个 Sleuth 接个 Zipkin 自动就有 trace 可看 出故障翻一翻就知道哪里慢 可这个认知是错的真正能扛业务的分布式追踪是一个 OpenTelemetry 协议选型 加 trace 覆盖度审计 加 context propagation 跨线程跨进程 加 采样策略动态调整 加 存储扩展性 加 trace-log-metric 三大支柱联动 的整套工程方法论 任何一环没做都可能在某次真正的故障里让你抓瞎本文从头梳理分布式追踪的核心模型 OpenTelemetry 的工程实现 context propagation 的常见坑 采样策略的设计 trace 与 log metric 的关联 以及一些把可观测性做扎实要避开的工程坑

问题背景:为什么调用链追踪比看起来复杂得多

很多人对调用链的认知停留在 加个 SDK 就能看到调用图 但生产里你会发现 很多 trace 不完整 很多 trace 段断在中间 高峰时 trace 数据写不进存储 真正出故障时 trace 反而最不可靠。问题的根源在于:

• 调用链追踪本质是 上下文传播:跨进程要靠 header 跨线程要靠 thread local 跨异步要靠手动绑定 任何一步没做都会断链。
• 覆盖度比完美率重要:80% 服务全埋好 比 20% 服务埋得完美 100 倍有用 因为故障经常发生在你没埋点的边缘服务。
• 采样策略影响排障能力:头采样省钱但错过故障 尾采样精准但成本高 必须按业务场景设计混合策略。
• trace 数据量是日志的几倍:微服务每个请求平均 5-15 个 span 一秒 1 万请求就是几万 span ElasticSearch 写入瓶颈不可避免。
• trace log metric 必须能互查:看到一个慢 trace 要能跳到对应日志 看到一条 ERROR 日志要能查到对应 trace 三大支柱不联动等于三个孤岛。
• OpenTelemetry 是事实标准:Zipkin Jaeger 各家协议正在统一到 OTel 新项目应该一步到位 老项目要规划迁移。

一 OpenTelemetry 的核心模型:Trace Span Context

OpenTelemetry 把可观测性抽象成三个支柱 Trace Metric Log 其中 Trace 由 Span 组成 每个 Span 表示一段工作 有开始时间结束时间 父子关系 attributes events status。理解 Span 是入门的基础。

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource

resource = Resource.create({
    'service.name': 'order-service',
    'service.version': '1.4.2',
    'deployment.environment': 'production',
})

provider = TracerProvider(resource=resource)
otlp_exporter = OTLPSpanExporter(endpoint='http://otel-collector:4317', insecure=True)
provider.add_span_processor(BatchSpanProcessor(
    otlp_exporter,
    max_export_batch_size=512,
    schedule_delay_millis=5000,
    max_queue_size=2048,
))
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)

def place_order(order_id: str, user_id: str) -> dict:
    with tracer.start_as_current_span('place_order') as span:
        span.set_attribute('order.id', order_id)
        span.set_attribute('user.id', user_id)
        try:
            validate(order_id)
            with tracer.start_as_current_span('charge_payment') as charge_span:
                charge_span.set_attribute('payment.method', 'card')
                result = charge(order_id)
                charge_span.set_attribute('payment.amount', result['amount'])
            ship(order_id)
            return {'status': 'ok'}
        except Exception as e:
            span.record_exception(e)
            span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
            raise

Resource 是 Span 的元数据 包含 service.name version environment 等 这些属性是后续过滤和聚合的基础 必须规范填。BatchSpanProcessor 把 span 攒批后异步上报 而不是每个 span 都发一次网络 否则性能不可接受。max_queue_size 决定了 buffer 上限 满了会丢 span 必须根据业务 QPS 调大。

二 Context Propagation:跨进程跨线程跨异步

调用链能不能连起来 全看 context propagation 做得好不好。跨进程要在 HTTP header 或 gRPC metadata 里传 traceparent 头 跨线程要把 context 绑到新线程 跨异步任务要在提交 future 时显式传 context。

from opentelemetry.propagate import inject, extract
from opentelemetry import context as otel_context
import requests
from concurrent.futures import ThreadPoolExecutor

# 跨进程 HTTP client 上报时把 traceparent 注入 header
def call_downstream(url: str, payload: dict) -> dict:
    headers = {}
    inject(headers)
    resp = requests.post(url, json=payload, headers=headers, timeout=3)
    return resp.json()

# 跨进程 HTTP server 接收时把 traceparent 从 header 提取出来
def http_handler(request):
    ctx = extract(request.headers)
    token = otel_context.attach(ctx)
    try:
        with tracer.start_as_current_span('handle_request') as span:
            span.set_attribute('http.path', request.path)
            return do_business(request)
    finally:
        otel_context.detach(token)

# 跨线程 必须把 context 显式传到新线程
executor = ThreadPoolExecutor(max_workers=8)

def offload_task(payload: dict):
    ctx = otel_context.get_current()
    def wrapped():
        token = otel_context.attach(ctx)
        try:
            with tracer.start_as_current_span('async_task'):
                handle(payload)
        finally:
            otel_context.detach(token)
    return executor.submit(wrapped)

跨线程是最容易翻车的地方 因为 OpenTelemetry 的 context 默认是 ContextVar 子线程不会继承 必须显式 attach。我们生产里曾经因为某个内部异步任务没传 context 整个下游链路在 Zipkin 上消失 排查了一周才找到这个细节。解法是封装一个 context-aware executor 所有提交进去的任务自动带上当前 context。

对于队列消费场景 跨进程靠 message 的 header 字段:

from kafka import KafkaProducer, KafkaConsumer

class TracedProducer:
    def __init__(self, bootstrap_servers: str):
        self.producer = KafkaProducer(
            bootstrap_servers=bootstrap_servers,
            value_serializer=lambda v: v.encode('utf-8'),
        )

    def send(self, topic: str, value: str) -> None:
        with tracer.start_as_current_span(f'kafka.produce.{topic}') as span:
            carrier = {}
            inject(carrier)
            headers = [(k, v.encode('utf-8')) for k, v in carrier.items()]
            span.set_attribute('messaging.system', 'kafka')
            span.set_attribute('messaging.destination', topic)
            self.producer.send(topic, value=value, headers=headers)


class TracedConsumer:
    def __init__(self, topic: str, bootstrap_servers: str):
        self.consumer = KafkaConsumer(topic, bootstrap_servers=bootstrap_servers)

    def consume_loop(self, handler):
        for message in self.consumer:
            carrier = {k: v.decode('utf-8') for k, v in (message.headers or [])}
            ctx = extract(carrier)
            token = otel_context.attach(ctx)
            try:
                with tracer.start_as_current_span(f'kafka.consume.{message.topic}'):
                    handler(message.value.decode('utf-8'))
            finally:
                otel_context.detach(token)

三 采样策略:头采样 vs 尾采样

分布式追踪的成本主要在存储和带宽 全量采集动辄 TB 级数据 必须做采样。采样有头采样和尾采样两种 头采样在入口决定要不要采 尾采样在 trace 结束后看完整数据再决定 各有优劣。

# OpenTelemetry Collector 头采样配置 ParentBasedSampler + ProbabilitySampler
# 入口服务按 10% 概率采样 下游服务跟随父决策
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  # 概率采样 10% 全量错误 100%
  probabilistic_sampler:
    sampling_percentage: 10

  # 尾采样 trace 完成后按规则筛选
  tail_sampling:
    decision_wait: 10s
    num_traces: 50000
    expected_new_traces_per_sec: 1000
    policies:
      - name: errors_policy
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: slow_traces
        type: latency
        latency: { threshold_ms: 1000 }
      - name: random_sample
        type: probabilistic
        probabilistic: { sampling_percentage: 5 }

exporters:
  otlp/jaeger:
    endpoint: jaeger-collector:4317
    tls: { insecure: true }

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [tail_sampling]
      exporters: [otlp/jaeger]

头采样的好处是省成本 缺点是错过故障 因为故障 trace 命中采样概率与正常 trace 一样 大概率没采到。尾采样的好处是能保证 100% 错误链路和 100% 慢链路都被采到 缺点是 Collector 要 buffer 完整 trace 内存占用高。生产推荐 头采样降流量 + 尾采样保关键 把 错误 慢 异常状态码 等链路全量保留 其他按 1-5% 采样。

[mermaid]flowchart TD
A[请求进入网关] --> B[traceparent 注入]
B --> C[服务 A]
C -->|HTTP 调用| D[服务 B]
D -->|gRPC 调用| E[服务 C]
C -->|Kafka 消息| F[服务 D]
C --> G[OTel SDK 批量上报]
D --> G
E --> G
F --> G
G --> H[OTel Collector]
H --> I[tail sampling 决策]
I -->|错误或慢| J[全量入 Jaeger]
I -->|正常| K[5% 采样入 Jaeger]
J --> L[UI 查询 + 报警]
K --> L

四 trace-log-metric 三支柱联动

trace 只有和 log metric 联动起来才有真正的价值。看到一个慢 trace 要能跳到对应日志 看到 ERROR 日志要能查到 trace 看到 QPS 异常要能下钻到具体 trace。实现这三者联动的关键是 在日志里写 trace_id span_id 在 metric 的 exemplar 里附 trace_id。

import logging
from opentelemetry import trace

class TraceContextFilter(logging.Filter):
    def filter(self, record):
        span = trace.get_current_span()
        ctx = span.get_span_context() if span else None
        if ctx and ctx.is_valid:
            record.trace_id = format(ctx.trace_id, '032x')
            record.span_id = format(ctx.span_id, '016x')
        else:
            record.trace_id = '-'
            record.span_id = '-'
        return True

handler = logging.StreamHandler()
handler.addFilter(TraceContextFilter())
formatter = logging.Formatter(
    '%(asctime)s level=%(levelname)s trace_id=%(trace_id)s span_id=%(span_id)s service=order-service msg=%(message)s'
)
handler.setFormatter(formatter)
root_logger = logging.getLogger()
root_logger.addHandler(handler)
root_logger.setLevel(logging.INFO)

# 业务侧使用
logger = logging.getLogger(__name__)

def process(order_id: str):
    with tracer.start_as_current_span('process_order') as span:
        span.set_attribute('order.id', order_id)
        logger.info(f'start processing order_id={order_id}')

这样每条日志都自带 trace_id 在 Loki ElasticSearch 这些日志后端可以直接按 trace_id 查所有相关日志 反向也可以从 trace UI 跳转到日志。metric 这边用 Prometheus exemplar 在 histogram bucket 里附带一条具体 trace_id 这样在 Grafana 看到延迟尖刺时可以直接点开 exemplar 跳到对应慢 trace:

from prometheus_client import Histogram

request_duration = Histogram(
    'http_request_duration_seconds',
    'HTTP request duration',
    ['method', 'path', 'status'],
    buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10),
)

def observe_request(method: str, path: str, status: int, duration: float):
    span = trace.get_current_span()
    ctx = span.get_span_context() if span else None
    exemplar = None
    if ctx and ctx.is_valid:
        exemplar = {'trace_id': format(ctx.trace_id, '032x')}
    metric = request_duration.labels(method=method, path=path, status=str(status))
    if exemplar:
        metric.observe(duration, exemplar)
    else:
        metric.observe(duration)

五 trace 数据存储与可视化

trace 数据量比想象中大得多 一次中等规模微服务请求平均 10-20 个 span 一秒 1 万 QPS 就是 10-20 万 span/秒 ElasticSearch 在这个量级上的写入成本很高。生产常见的存储选择是 Jaeger 后端 ElasticSearch ClickHouse Cassandra 各有优劣。

# Jaeger Collector + ClickHouse 存储 大规模推荐
# ClickHouse 在 trace 这种结构化日志数据上比 ElasticSearch 写入快 4-10 倍
# 存储成本低 50-70% 查询大表也快得多

version: '3'
services:
  jaeger-collector:
    image: jaegertracing/jaeger-collector:1.50
    environment:
      SPAN_STORAGE_TYPE: grpc-plugin
      GRPC_STORAGE_PLUGIN_BINARY: /plugins/jaeger-clickhouse
      GRPC_STORAGE_PLUGIN_CONFIGURATION_FILE: /config/clickhouse.yaml
    ports:
      - "14250:14250"
      - "4317:4317"

  jaeger-query:
    image: jaegertracing/jaeger-query:1.50
    environment:
      SPAN_STORAGE_TYPE: grpc-plugin
    ports:
      - "16686:16686"

  clickhouse:
    image: clickhouse/clickhouse-server:23.8
    ports:
      - "9000:9000"
    volumes:
      - clickhouse-data:/var/lib/clickhouse

volumes:
  clickhouse-data:

对应的 ClickHouse schema 设计要点 按 service+timestamp 分区 按 trace_id 排序 这样按服务查询和按 trace 查询都快:

CREATE TABLE jaeger_spans (
    timestamp DateTime64(6),
    trace_id String,
    span_id String,
    parent_id String,
    operation_name String,
    service_name LowCardinality(String),
    duration_us UInt64,
    status_code LowCardinality(String),
    tags Map(String, String),
    logs Array(Tuple(DateTime64(6), Map(String, String)))
)
ENGINE = MergeTree
PARTITION BY (service_name, toYYYYMMDD(timestamp))
ORDER BY (service_name, timestamp, trace_id)
TTL toDateTime(timestamp) + INTERVAL 7 DAY
SETTINGS index_granularity = 8192;

-- 按 trace_id 查询所有 span 加二级索引加速
ALTER TABLE jaeger_spans ADD INDEX idx_trace trace_id TYPE bloom_filter GRANULARITY 4;

-- 按服务查询慢请求
SELECT trace_id, operation_name, duration_us, status_code
FROM jaeger_spans
WHERE service_name = 'order-service'
  AND timestamp >= now() - INTERVAL 1 HOUR
  AND duration_us > 1000000
ORDER BY duration_us DESC
LIMIT 100;

ClickHouse 的 TTL 7 天是关键 trace 数据保留 7 天足够排障 再长就是浪费。SLA 故障复盘可以单独把关键 trace 导出到长期存储 不需要全量留。我们的生产环境 80 个服务 平均 5000 QPS trace 数据每天 800GB ClickHouse 集群 3 节点能轻松 hold 住 之前用 ES 同样规模需要 6 节点还经常写入告警。

六 分布式追踪的工程坑:那些文档里学不到的

讲完原理来说几个真实生产里踩过的坑。第一个坑是 service mesh sidecar trace 重复 如果业务代码自己埋了 OTel 又开了 Istio 的 trace 同一段调用会产生两个 span 链路图错乱 必须二选一 或者用 W3C TraceContext header 规范让二者协同。第二个坑是 内部异步任务漏 propagate 我们之前一个对账任务用了 ThreadPoolExecutor 直接 submit 没传 context 链路在那里断了一周才发现。第三个坑是 trace 标签基数过高 比如把 user_id 作为 attribute Prometheus exemplar 那里能压垮指标系统 必须做基数控制。第四个坑是 SDK 版本不一致 不同语言不同版本的 OTel SDK 会因为字段名差异让某些 attribute 不显示 必须统一 SDK 版本。第五个坑是 trace 时钟漂移 不同机器系统时间差几百毫秒 span 的 start_time 排序就乱了 显示出来父 span 比子 span 还晚 必须用 NTP 同步精度到 1ms 以内。

关键概念速查

避坑清单

1. 新项目直接用 OpenTelemetry 不要再用 Zipkin 自带 SDK 协议正在统一。
2. Resource 的 service.name version environment 必须规范填 否则后续过滤聚合都乱。
3. 跨线程异步任务必须显式 attach context 子线程不会自动继承 ContextVar。
4. 跨进程必须用 inject extract 在 HTTP gRPC Kafka header 里传 traceparent 头。
5. NGINX 反向代理必须 forward X-B3-TraceId 或 traceparent 头 否则链路断在中间。
6. 采样策略推荐头采样 + 尾采样混合 错误慢请求全量留 正常请求 1-5% 即可。
7. 每条日志必须带 trace_id span_id 否则 trace 与 log 联动不起来。
8. metric exemplar 在 histogram 里附 trace_id 才能从指标尖刺跳到慢 trace。
9. trace 标签基数严格控制 user_id 这种高基数字段不要进 attribute。
10. 所有埋点节点必须 NTP 同步精度 1ms 以内 否则 span 排序乱。

总结

分布式追踪这事 很多人的直觉是 加个 SDK 接个 Zipkin 就完事了 这其实是把 我会写 tracer.start_as_current_span 和 我能在故障里准确定位问题 混为一谈。前者是会用 SDK 后者是懂可观测性工程。中间隔着的是 OpenTelemetry 协议 context propagation 采样策略 trace-log-metric 联动 存储扩展性 团队协作规范 整整一套工程方法论。

从原型到生产 你需要做的事远不止 加个 tracer。你要懂 OTel 三大支柱模型 要保证跨进程跨线程跨异步 context 都传到 要设计采样策略 要联动日志和指标 要选合适的后端存储 要处理 NGINX service mesh 这些中间代理 要规范 service.name attribute 命名 要监控 OTel Collector 自身的容量。每一项单独看都不复杂 但它们组合在一起 才是一个能在故障时帮你救命的可观测系统。少任何一项 都可能在某次真实故障里让你抓瞎几个小时。

我经常用一个比喻来理解分布式追踪 它有点像快递的物流跟踪。trace_id 是订单号 span 是每个中转站的处理记录 propagation 是订单号在中转间的传递 sampling 是快递公司只详细记录有问题的包裹 trace-log-metric 联动是订单系统 包裹照片 包裹称重三套数据互查。你不能因为有了订单号就以为快递不会丢 还要管中转传递订单号传得完整不完整 异常包裹是不是都记录详细 三套数据是否能互查 这才是一整套物流跟踪工程。

这套架构最难的地方在于 它的复杂度在系统正常运行时几乎完全暴露不了。trace 在那躺着 你看 UI 觉得挺漂亮 觉得可观测性挺好。但真正出故障时 你才发现 99% 的复杂度都在 那 1% 的故障 case 里 异步任务的链路断点 service mesh sidecar 的双重 span 网关没传 header 的链路断头 采样恰好没采到关键 trace 时钟漂移让父子顺序错乱。建议任何想做分布式追踪的团队 上线后定期做 故障演练 故意触发几个慢请求几个错误请求 看 trace 能不能完整还原 看日志能不能跳转 看指标能不能下钻 千万别等真正故障来教你这些细节 那时候你的业务可能已经挂了几十分钟了。

—— 别看了 · 2026