在 Kubernetes 集群中，一个前端请求可能经过网关、订单服务、库存服务、支付服务和消息队列。日志只能说明每个 Pod 自己做了什么，指标只能说明资源使用和请求速率，当某个接口变慢时，很难快速确定是网络抖动、数据库慢查询还是某个服务内部阻塞。分布式追踪通过给每次请求生成唯一的 trace ID，并在进程边界传递上下文，让每个服务记录的 span 都能按同一 ID 聚合起来。Kubernetes 环境中的追踪配置不只是启动一个 Jaeger 容器，还涉及采集器部署、注入策略和存储选型，下面按模块展开。
一、从数据流角度理解 Kubernetes 追踪组件
分布式追踪的数据流通常包含应用埋点、采集器、存储和查询界面四层。应用通过 OpenTelemetry SDK 或者兼容的 Agent 生成 span，并把数据发送到 Collector。Collector 负责接收、批处理、过滤、采样和导出，避免每个服务直接连后端导致连接数爆炸。后端可以选择 Jaeger、Grafana Tempo、Elastic APM 或其他支持 OTLP 的存储。查询界面从后端读取 trace ID 对应的完整链路。
在 Kubernetes 中，Collector 通常以 Deployment 或 DaemonSet 运行。Deployment 模式适合中心化接收，所有 Pod 通过 Service 把追踪数据发送到固定地址。DaemonSet 适合做节点级预聚合，例如采集主机网络信息或者减少跨节点流量。对于大多数中小集群，先部署一个 Deployment 类型的 Collector，再配合 OpenTelemetry Operator 完成自动注入，是最容易维护的路径。
选型时还需要区分追踪标准和实现。OpenTelemetry 是当前事实上的采集标准，它定义了 API、SDK 和 OTLP 协议。Jaeger 和 Zipkin 是早期的追踪系统，现在更多作为后端存储和 UI 使用。Tempo 的优势在于对象存储友好、成本低，适合大量 trace 数据长期保存。如果团队已经使用 Grafana 做指标和日志，Tempo 可以统一到同一个查询入口。
二、部署 OpenTelemetry Collector 并配置 OTLP 接收管道
先安装 OpenTelemetry Operator，它会管理 Collector 和自动注入资源。使用 Helm 安装比较方便：
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts helm install opentelemetry-operator open-telemetry/opentelemetry-operator
安装完成后，创建一个 Collector 配置。下面示例使用 OTLP 接收器接收来自应用 SDK 的追踪数据，通过批处理器合并 span，再导出到 Jaeger 的 OTLP 接口。注意 batch 处理器可以减少下游压力，memory_limiter 可以防止 Collector 在突发流量时 OOM。
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
name: otel-collector
namespace: observability
spec:
mode: deployment
config: |
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
memory_limiter:
check_interval: 1s
limit_mib: 512
batch:
send_batch_size: 512
timeout: 5s
exporters:
otlp/jaeger:
endpoint: jaeger-collector.observability.svc.cluster.local:4317
tls:
insecure: true
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, batch]
exporters: [otlp/jaeger]
这个 Collector 暴露了两个端口：4317 给 gRPC，4318 给 HTTP。应用侧的环境变量可以指向这两个端口中的任意一个。如果 Pod 和 Collector 在同一个命名空间，使用 otel-collector.observability.svc.cluster.local 即可。生产环境建议为 Collector 配置多个副本，并通过 Service 负载均衡。
如果暂时没有后端，可以先把 exporter 改为 logging，确认 span 能正常到达 Collector。调试通过后再切换到真实存储，避免一开始因为网络和认证问题掩盖应用埋点问题。
三、配置自动注入让应用无侵入地发送 span
手动修改每个服务代码去初始化 OpenTelemetry SDK 成本较高，而且不同语言的 API 有差异。OpenTelemetry Operator 提供 Instrumentation 资源，可以自动注入常见语言的 Agent。以 Java 服务为例，Operator 会向 Pod 注入 Sidecar 或环境变量，让 JVM 加载 OpenTelemetry Java Agent，自动采集 HTTP 调用、数据库查询和消息队列操作。
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: java-instrumentation
namespace: observability
spec:
propagators:
- tracecontext
- baggage
sampler:
type: parentbased_traceidratio
argument: "0.1"
java:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-java:latest
env:
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: http://otel-collector.observability.svc.cluster.local:4318
创建 Instrumentation 后，需要在目标 Deployment 的 Pod 模板里加上注解。Operator 会根据注解自动修改 Pod，不需要改容器镜像。下面是一个典型注解：
metadata:
annotations:
instrumentation.opentelemetry.io/inject-java: "true"
自动注入虽然方便，但会略微增加启动时间和内存占用。Java Agent 一般会带来 1% 到 5% 的 CPU 开销，具体取决于采样率和插件范围。Python 和 Node.js 的注入方式类似，只是注解名称和 Agent 镜像不同。对于 Go 这种编译型语言，自动注入能力有限，需要在代码中显式引入 OpenTelemetry SDK，手动创建 tracer 并在中间件里传递上下文。
还要注意上下文传播协议。跨服务传播时，HTTP 请求头中的 traceparent 和 tracestate 必须保持一致。老的 Zipkin B3 格式和 W3C tracecontext 格式并存时可能出现断开，建议在集群内统一使用 tracecontext 和 baggage，减少因为协议不兼容导致的链路缺失。
四、采样策略配置：平衡完整性与存储成本
如果所有请求都记录完整 trace，高并发下存储成本和网络开销会迅速上升。采样策略决定哪些请求被保留、哪些被丢弃。OpenTelemetry 支持头部采样和尾部采样。头部采样在 span 创建时就决定是否记录，实现简单、开销低，但可能漏掉偶发的慢请求。尾部采样在 Collector 端聚合完整调用链后，根据整个 trace 的耗时或错误状态决定是否导出，能保留更有价值的链路，但需要额外缓存和计算。
头部采样可以在 SDK 配置中设置 parentbased_traceidratio，例如 0.1 表示 10% 的请求会被采样。采样决策会通过 traceparent 传播到下游，保证整条链路一致。Collector 端也可以配置 probabilistic_sampler，对未带采样标记的 span 做二次处理。
processors:
probabilistic_sampler:
sampling_percentage: 10
尾部采样通常使用 Tail Sampling Processor。下面配置会优先保留错误请求和耗时超过 2 秒的 trace，其余按 10% 概率保留。
processors:
tail_sampling:
decision_wait: 10s
policies:
- name: errors
type: status_code
status_code:
status_codes: [ERROR]
- name: slow
type: latency
latency:
threshold_ms: 2000
- name: probability
type: probabilistic
probabilistic:
sampling_percentage: 10
尾部采样需要 Collector 有足够内存保存等待窗口内的 span，否则在高并发时会出现数据丢失或 OOM。可以先从头部采样开始，等流量稳定后再评估是否引入尾部采样。不同业务对完整性的要求不一样，支付链路建议全量采样，后台批处理任务可以只保留少量样本。
五、接入 Jaeger 或 Tempo 做查询和可视化
Collector 导出的数据需要一个可查询的后端。Jaeger 是最经典的方案，支持 OTLP 接收，查询界面直观。部署 Jaeger 时可以让 Collector 直连 jaeger-collector 的 4317 端口，或者通过 Jaeger Agent 转发。下面是一个精简的 Jaeger 部署，使用内存存储，适合开发环境验证。
apiVersion: apps/v1
kind: Deployment
metadata:
name: jaeger
namespace: observability
spec:
replicas: 1
selector:
matchLabels:
app: jaeger
template:
metadata:
labels:
app: jaeger
spec:
containers:
- name: jaeger
image: jaegertracing/all-in-one:latest
ports:
- containerPort: 16686
name: ui
- containerPort: 4317
name: otlp-grpc
- containerPort: 4318
name: otlp-http
生产环境如果将 Jaeger 的存储从内存换成 Elasticsearch 或 Cassandra，需要额外的存储配置和索引维护。Tempo 是另一个适合 Kubernetes 的选项，它把 trace 数据按块存储到对象存储，比如 S3 或 MinIO，查询时通过元数据定位块。Tempo 的资源消耗相对较低，适合需要长期保存但不常用全量查询的场景。
无论选择 Jaeger 还是 Tempo，都建议在 Grafana 中统一查询。Grafana 内置了 Jaeger 和 Tempo 数据源，可以根据 trace ID 直接跳转到链路视图。这样排障时可以从指标面板发现异常，再点击 trace ID 深入查看调用瀑布图，形成从监控到追踪的闭环。
六、常见配置错误与排查路径
追踪配置在最初落地时，最容易出现的问题是应用 span 没有到达 Collector。可以先检查 Pod 日志中是否有 OpenTelemetry 的启动信息，以及 OTEL_EXPORTER_OTLP_ENDPOINT 是否指向正确的 Service。其次，确认 Collector 的接收端口在 Service 中暴露，是否用错了 4317 和 4318。gRPC 和 HTTP 协议不匹配也是常见原因。
如果 span 到达了 Collector 但后端查询不到，优先查看 Collector 的导出日志，确认是否出现 401、超时或连接拒绝。接着检查服务名是否一致，service.name 在采集链路中非常重要。很多团队在自动注入时没有设置 OTEL_SERVICE_NAME，导致所有服务都显示同一个名字，链路图完全不可用。
性能问题也不能忽视。自动注入的 Agent 可能对短请求产生额外延迟，高流量下 Collector 单副本可能成为瓶颈。建议对 Collector 设置资源限制和 HPA，并用 memory_limiter 保护进程。监控 Collector 自身的 CPU、内存和导出队列，能有效避免追踪系统本身成为新的不稳定源。
Kubernetes分布式追踪OpenTelemetry修改时间：2026-09-28 11:04:20