OpenTelemetry实战指南——Kubernetes环境下的链路追踪自动化部署

1. 为什么要在Kubernetes里搞自动化链路追踪？

如果你在维护一个稍微有点规模的Kubernetes应用，肯定遇到过这种头疼事：用户反馈页面加载慢，或者某个功能报错。你第一反应是去查日志，结果发现十几个微服务互相调用，日志散落在各个Pod里，像一团乱麻，根本理不清到底是谁拖慢了整个请求，或者错误是在哪个环节产生的。这时候，你就需要“链路追踪”这个神器了。

简单来说，链路追踪就像给一次完整的用户请求（比如“下单”）装上了GPS。它能记录这个请求经过了哪些服务（比如网关->用户服务->订单服务->库存服务），在每个服务里停留了多久，调用了什么数据库或API，以及每一步是成功还是失败。有了这张清晰的“调用地图”，排查性能瓶颈和定位故障就变成了“按图索骥”，效率提升不是一点半点。

传统上，要给应用加上链路追踪，你得在代码里手动埋点，也就是引入SDK，在关键位置写上一堆打点代码。这对于新项目还好，如果是已有的大量存量服务，改造起来简直就是一场噩梦，费时费力，还容易出错。

好在，我们现在有了OpenTelemetry（简称OTel）和它的Kubernetes Operator。这套组合拳能实现链路追踪的自动化部署与注入，真正做到“开箱即用”。你不需要修改一行业务代码，只需要在Kubernetes里声明一下规则，Operator就会自动给指定的Pod注入追踪探针（Agent或SDK），自动收集数据并发送到你指定的后端（比如Jaeger或Tempo）。这对于追求快速落地、统一技术栈和降低运维成本的DevOps团队来说，吸引力太大了。

我自己的团队在去年全面接入了这套方案，把十几个微服务的追踪接入时间从“人周”级别压缩到了“人天”级别。接下来，我就把踩过的坑和总结的最佳实践，手把手分享给你。

2. 核心武器：OpenTelemetry Operator 与自动注入

2.1 OpenTelemetry Operator 是个啥？

你可以把OpenTelemetry Operator想象成Kubernetes集群里的一个“超级管家”，专门负责管理可观测性相关的资源。它基于Kubernetes的Operator模式，通过自定义资源定义（CRD）来扩展Kubernetes API，让我们能用声明式的方式（也就是写YAML文件）来管理追踪数据的收集、处理和导出。

它核心管理三种CRD：

1. OpenTelemetryCollector： 定义数据收集器。它是个“中转站”和“处理器”，负责从应用接收数据，进行批处理、过滤、转换，然后导出到Jaeger、Tempo等后端存储。
2. Instrumentation： 这是实现自动注入的关键。它定义了一套规则，告诉Operator：哪些Pod需要被自动注入OpenTelemetry SDK，以及注入时使用什么配置（比如采样率、资源属性）。
3. OpenTelemetryTargetAllocator： 用于更高级的部署场景，比如在Collector水平扩展时，动态分配接收目标，这里我们先不展开。

自动注入是Operator最香的功能。它的工作原理和Istio的Sidecar注入很像。当你在命名空间或Pod上打上一个特定的标签（比如instrumentation.opentelemetry.io/inject-sdk: “true”），并且该命名空间存在一个有效的Instrumentation资源时，Operator的Webhook就会在Pod创建时，动态地修改Pod的定义，把OpenTelemetry的SDK（以InitContainer或环境变量的方式）或者一个独立的Agent Sidecar容器注入进去。

这样做的好处显而易见：

• 零代码侵入： 应用开发者完全无感，不需要学习SDK API，也不需要改代码。
• 统一配置与管理： 所有微服务的采样率、上报地址等配置在集群层面统一管理，一键更改，全局生效。
• 安全合规： 注入过程在集群内完成，数据流不经过外网，符合内部安全规范。
• 灵活切换： 今天用Jaeger，明天想换Tempo？只需要修改Collector的导出配置和Instrumentation的环境变量，无需重启应用（部分情况需滚动更新）。

2.2 一步步部署OpenTelemetry Operator

理论说再多不如动手做一遍。我们先在Kubernetes集群里把Operator装起来。这里假设你有一个正在运行的Kubernetes集群（可以是Minikube、Kind，或者云上的托管集群），并且已经配置好了kubectl。

首先，我们用官方提供的Manifest文件来安装。这是最直接的方式。

# 安装 OpenTelemetry Operator 的 CRD 和 Operator 本身 kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

执行完这条命令，你会看到一系列资源被创建。稍等片刻，检查一下Operator的Pod是否运行正常：

kubectl get pods -n opentelemetry-operator-system

你应该能看到一个名为opentelemetry-operator-controller-manager-xxx的Pod状态是Running。这就说明Operator已经就位了。

接下来，我们需要部署一个OpenTelemetry Collector。Collector是数据管道的中枢，我们先部署一个最简单的版本，让它能把收到的数据打印到标准输出（方便调试）。

创建一个YAML文件，比如叫basic-collector.yaml：

apiVersion: opentelemetry.io/v1beta1 kind: OpenTelemetryCollector metadata: name: simplest-collector namespace: default # 放在default命名空间，方便测试 spec: config: | receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: {} # 使用批处理器，提升传输效率 exporters: debug: # 使用debug导出器，所有数据打印到Collector自己的日志里 verbosity: detailed service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [debug]

应用这个配置：

kubectl apply -f basic-collector.yaml

然后查看Collector的Pod和日志：

kubectl get pod -l app.kubernetes.io/name=simplest-collector kubectl logs -f <collector-pod-name>

如果看到日志里没有报错，并且有类似“Exporting…”的调试信息，说明Collector已经启动成功，正在监听4317（gRPC）和4318（HTTP）端口，等待数据到来。

3. 实战：让一个应用自动上报追踪数据

Operator和Collector都准备好了，现在我们来“盘活”一个应用。我们用一个经典的演示应用——Jaeger团队提供的HotROD（Rides on Demand）。它本身内置了OpenTelemetry SDK，非常适合做演示。

3.1 创建 Instrumentation 资源

自动注入的“开关”和“规则”就在Instrumentation资源里。我们来创建一个：

# instrumentation.yaml apiVersion: opentelemetry.io/v1beta1 kind: Instrumentation metadata: name: my-instrumentation namespace: default # 注意：这个资源需要和应用在同一个命名空间 spec: exporter: endpoint: http://simplest-collector-collector.default.svc:4318 # 指向我们刚部署的Collector服务 sampler: type: parentbased_traceidratio argument: “1.0” # 采样率100%，生产环境建议调低，如0.1 propagators: - tracecontext - baggage

应用它：

kubectl apply -f instrumentation.yaml

这个配置做了几件事：

1. 告诉被注入的SDK，把数据发送到http://simplest-collector-collector.default.svc:4318这个地址（这是Kubernetes Service的DNS名称）。
2. 设置采样策略为parentbased_traceidratio，采样率1.0（全采样）。生产环境为了控制数据量和成本，通常会设置为0.1（10%）或更低。
3. 配置了传播器，确保TraceID能在服务间正确传递。

3.2 部署应用并触发自动注入

现在部署HotROD应用。关键点在于，我们需要在Pod的模板上加上一个特殊的注解（annotation），来“申请”注入。

# hotrod-demo.yaml apiVersion: apps/v1 kind: Deployment metadata: name: hotrod namespace: default spec: replicas: 1 selector: matchLabels: app: hotrod template: metadata: labels: app: hotrod annotations: # 这是触发自动注入的“魔法注解” instrumentation.opentelemetry.io/inject-sdk: “true” # 可选：指定使用哪个Instrumentation资源，默认用同命名空间下名为 “default” 的，或者第一个。 # instrumentation.opentelemetry.io/instrumentation-name: “my-instrumentation” spec: containers: - name: app image: jaegertracing/example-hotrod:latest ports: - containerPort: 8080 env: # 注意：我们不再需要手动设置 OTEL_EXPORTER_OTLP_ENDPOINT 了！ # Instrumentation 资源会自动注入这个环境变量。 - name: OTEL_SERVICE_NAME value: “hotrod-demo” # 设置服务名，这个很重要，用于在追踪后端标识服务 - name: OTEL_RESOURCE_ATTRIBUTES value: “deployment.environment=development” # 添加一些资源属性 --- apiVersion: v1 kind: Service metadata: name: hotrod-service spec: selector: app: hotrod ports: - protocol: TCP port: 80 targetPort: 8080

应用这个Deployment：

kubectl apply -f hotrod-demo.yaml

现在，神奇的事情发生了。Operator的准入Webhook拦截了这个Pod的创建请求，发现它有instrumentation.opentelemetry.io/inject-sdk: “true”注解，于是自动执行了注入。

我们来验证一下。先查看Pod的详情：

kubectl describe pod <hotrod-pod-name>

在输出的环境变量部分，你应该能看到Operator自动注入了一大堆OTEL_开头的变量，其中就包括OTEL_EXPORTER_OTLP_ENDPOINT=http://simplest-collector-collector.default.svc:4318。同时，Pod里也会被加入一个opentelemetry-auto-instrumentation的InitContainer，用于准备SDK所需的Java Agent等文件（对于Java应用）。

3.3 生成流量并查看追踪数据

给应用暴露个端口，方便我们访问：

kubectl port-forward svc/hotrod-service 8080:80

打开浏览器，访问http://localhost:8080，你会看到HotROD的界面。点击几个按钮，比如“Dispatch”几次，模拟用户下单。这些操作会在后台触发一系列微服务调用。

现在，去查看我们之前部署的那个simplest-collector的日志：

kubectl logs -f deployment/simplest-collector-collector

你会看到刷出来很多结构化的JSON日志，里面包含了详细的Trace和Span信息！这说明从应用到Collector的整个数据通路已经打通了。数据成功被Collector接收，并通过debug导出器打印了出来。

4. 集成实战：将数据导出到Jaeger

调试用的debug导出器不能用于生产。我们需要一个真正的链路追踪后端来存储和可视化数据。Jaeger是一个久经考验的选择，它原生支持OTLP协议，与OpenTelemetry集成非常顺畅。

4.1 部署生产可用的Jaeger

在生产环境，我们通常不会用All-in-One镜像，而是采用分布式部署，将数据持久化到Elasticsearch等存储中。这里为了演示完整流程，我们先用Helm部署一个带Elasticsearch存储的Jaeger。

首先，添加Jaeger的Helm仓库并拉取Chart：

helm repo add jaegertracing https://jaegertracing.github.io/helm-charts helm repo update helm pull jaegertracing/jaeger --untar cd jaeger

我们需要修改values.yaml来配置存储。假设你已经有一个运行在elk命名空间下的Elasticsearch服务（如何部署ES不是本文重点）。关键配置如下：

# 在 values.yaml 中修改或添加以下部分 provisionDataStore: cassandra: false elasticsearch: false # 我们不使用Chart内嵌的ES，用外部的 collector: service: otlp: grpc: port: 4317 # 确保OTLP gRPC端口开放 http: port: 4318 # 确保OTLP HTTP端口开放 storage: type: elasticsearch elasticsearch: scheme: https host: elasticsearch-es-http.elk.svc.cluster.local # 你的ES服务地址 port: 9200 user: “elastic” # 你的ES用户名 passwordSecret: “elasticsearch-password” # 引用存有密码的Secret tls: enabled: true caSecret: “elasticsearch-ca-cert” # 引用存有CA证书的Secret

你需要提前创建好包含密码和CA证书的Secret：

kubectl create secret generic elasticsearch-password -n opentelemetry --from-literal=password=YourStrongPasswordHere kubectl create secret generic elasticsearch-ca-cert -n opentelemetry --from-file=ca.crt=./path/to/ca.crt

然后安装Jaeger：

helm install jaeger -n opentelemetry . -f values.yaml

安装完成后，检查Pod和服务：

kubectl get pods -n opentelemetry -l app.kubernetes.io/instance=jaeger kubectl get svc -n opentelemetry jaeger-collector

确保jaeger-collector服务有4317和4318端口。

4.2 改造Collector，对接Jaeger

现在，我们需要修改之前的OpenTelemetry Collector配置，让它把数据从debug导出到jaeger。

更新Collector的YAML文件（或者新建一个）：

# jaeger-collector.yaml apiVersion: opentelemetry.io/v1beta1 kind: OpenTelemetryCollector metadata: name: production-collector namespace: opentelemetry spec: replicas: 2 # 生产环境建议至少2个副本保证高可用 config: | receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: {} memory_limiter: # 添加内存限制器，防止OOM check_interval: 1s limit_mib: 512 spike_limit_mib: 256 exporters: logging: # 保留一个logging导出器，用于关键错误日志 loglevel: warn otlp/jaeger: endpoint: “jaeger-collector.opentelemetry.svc.cluster.local:4317” tls: insecure: true # 如果集群内部通信是安全的，可以设为false并配置证书 service: telemetry: logs: level: “info” pipelines: traces: receivers: [otlp] processors: [memory_limiter, batch] exporters: [otlp/jaeger, logging]

应用新的Collector配置：

kubectl apply -f jaeger-collector.yaml

重要一步：更新Instrumentation资源，将SDK的上报地址指向新的Collector。

# instrumentation-update.yaml apiVersion: opentelemetry.io/v1beta1 kind: Instrumentation metadata: name: my-instrumentation namespace: default spec: exporter: endpoint: http://production-collector-collector.opentelemetry.svc.cluster.local:4318 # 指向新的Collector sampler: type: parentbased_traceidratio argument: “0.5” # 生产环境采样率设为50% propagators: - tracecontext - baggage

应用更新：

kubectl apply -f instrumentation-update.yaml

更新后，HotROD的Deployment需要滚动更新一次才能获取到新的环境变量。最简单的方法是删除Pod让其重建：

kubectl rollout restart deployment/hotrod -n default

4.3 在Jaeger UI中查看成果

现在，所有组件都已就绪。再次访问HotROD应用并生成一些流量。

通过端口转发访问Jaeger Query的UI：

kubectl port-forward svc/jaeger-query -n opentelemetry 16686:16686

打开浏览器，访问http://localhost:16686。在Service下拉框里，你应该能看到hotrod-demo这个服务。选择它，点击“Find Traces”，就能看到刚才产生的所有追踪链路了。点击任意一条Trace，可以清晰地看到完整的调用链、每个Span的耗时和详情。至此，基于OpenTelemetry Operator的自动化链路追踪与Jaeger的集成已经全部完成。

5. 另一种选择：与Grafana Tempo集成

除了Jaeger，Grafana Tempo是另一个非常流行的、云原生的分布式追踪后端。它的特点是成本极低，直接使用对象存储（如S3、MinIO）来存储追踪数据，并且与Grafana、Prometheus、Loki的集成度极高，适合已经在使用Grafana技术栈的团队。

5.1 部署Tempo

同样，我们使用Helm来部署Tempo。这里我们采用单机模式（tempochart），适合测试和中小规模环境。

helm repo add grafana https://grafana.github.io/helm-charts helm repo update helm pull grafana/tempo --untar cd tempo

修改values.yaml，配置使用MinIO作为对象存储（假设你已有MinIO）：

tempo: storage: trace: backend: s3 s3: bucket: “tempo-traces” # 在MinIO中预先创建好的桶 endpoint: minio.minio.svc.cluster.local:9000 # MinIO服务地址 access_key: “your-access-key” secret_key: “your-secret-key” insecure: true # 如果是HTTP，设为true

安装Tempo：

helm install tempo -n opentelemetry . -f values.yaml

检查Tempo服务，确认其OTLP端口（4317, 4318）已开放。

5.2 配置Collector将数据导出到Tempo

这一步和配置Jaeger非常类似，只需要修改Collector的导出器部分。

# tempo-collector.yaml apiVersion: opentelemetry.io/v1beta1 kind: OpenTelemetryCollector metadata: name: production-collector-tempo namespace: opentelemetry spec: config: | receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: {} exporters: otlp/tempo: endpoint: “tempo.opentelemetry.svc.cluster.local:4317” tls: insecure: true service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlp/tempo]

然后，同样地，更新Instrumentation资源中的exporter.endpoint，指向这个新的Collector，并重启应用Pod。

5.3 在Grafana中探索追踪数据

Tempo本身不提供独立的UI，它的数据需要通过Grafana来查询和展示。这恰恰是它的优势所在。

1. 在Grafana中添加Tempo数据源： 在Grafana界面中，进入Configuration -> Data Sources -> Add data source，选择“Tempo”。URL填写Tempo Query的集群内服务地址，例如http://tempo-query.opentelemetry.svc.cluster.local:3100。
2. 通过TraceID查询： 最常见的方式是，当你查看应用日志或Prometheus指标发现一个可疑的TraceID时，可以直接在Grafana的Explore页面选择Tempo数据源，输入TraceID进行查询。
3. 与Loki日志联动： 如果你的应用日志也通过Loki收集，并且日志中打印了TraceID，那么在Loki中查看某条日志时，可以直接点击TraceID旁边的链接，一键跳转到Tempo查看完整的调用链。这种“日志到追踪”的无缝跳转，排查效率极高。
4. 与Prometheus指标联动： Tempo可以配置metrics_generator，从追踪数据中生成RED（Rate, Error, Duration）指标，并写入Prometheus。这样，你可以在Grafana仪表盘中，看到一个服务的请求量、错误率、延迟指标突然异常时，直接下钻到具体的追踪样本进行分析，实现了“指标到追踪”的闭环。

这种深度集成的体验，让Tempo在统一的观测性平台中扮演了非常核心的角色。选择Jaeger还是Tempo，取决于你的技术栈偏好和运维成本考量。Jaeger部署相对传统，功能独立且强大；Tempo则更云原生，与Grafana生态绑定深，长期存储成本低。两者通过OpenTelemetry Collector都能完美接入。