企业官网建设流程全解析

• 数据工程
• 后端
• 云原生
• 任务调度
• 微服务

本篇指南围绕 Pachyderm 仓库中etc/deploy/tracing/目录下的部署资源与 README，完整介绍如何在 Kubernetes 集群中运行 Jaeger all-in-one，并通过环境变量让 pachd、pachctl 及 Go 客户端上报和传播 OpenTracing 链路，帮助你定位慢调用、诊断慢集群。读完本文，你将掌握 Jaeger 清单的定制要点、端口转发与访问方法，以及 Pachyderm 底层追踪初始化、采样与拦截器的实现原理。

一、目录概览：一套开箱即用的 Jaeger 部署资源

仓库中etc/deploy/tracing/目录包含三个文件：

• README.md：说明本目录用途——包含一个在 Kubernetes 中运行 Jaeger 的 manifest；Pachyderm 可以向 Jaeger 上报并传播 OpenTracing traces，用于诊断慢调用或慢集群。
• jaeger-all-in-one.yaml：Kubernetes 资源清单，定义一个 Jaeger Deployment 与两个 Service。
• start_port_forward.sh：一键重建端口转发的辅助脚本。

原 README 指引读者前往doc/deployment/tracing.md获取更多信息，但该文档并不存在于当前仓库中；本文即基于实际 manifest、脚本与源码，完整展开该主题。

二、清单解析：jaeger-all-in-one.yaml 的定制要点

该清单复制自 jaegertracing/jaeger-kubernetes 的 all-in-one 模板（以 2022-12-08 的 master 分支头部为准），并针对 Pachyderm 的使用方式做了一系列删改，了解这些改动有助于理解"为什么端口是这样配置的"。

2.1 对上游模板的主要改动

• apiVersion 升级为apps/v1：Deployment 由上游的extensions/v1beta1改为apps/v1，以兼容现代 Kubernetes 版本。
• 移除 jaeger-agent 及其端口：jaeger-agent 负责接收 trace 再转发给 collector，而 Pachyderm 客户端直接把 trace 发给 collector，因此 agent 无用，与之关联的 5775、5778、6831、6832 端口全部从容器中移除。
• 补上 collector 端口导出：原清单未导出jaeger-collector-tchannel（14267）与jaeger-collector-http（14268）端口，不导出会导致服务无法工作（原作者认为是上游清单的 bug）。
• 移除 jaeger-collector-zipkin 服务：Zipkin 属兼容特性，pachd/pachctl 中没有任何既有 Zipkin 客户端需要支持，故移除。
• 容器版本固定在 1.39.0：镜像固定为jaegertracing/all-in-one:1.39.0，保证可复现。

清单头部注释还提示了两个可选的进一步清理项：移除 collector 服务中的 Zipkin 端口，以及移除容器内COLLECTOR_ZIPKIN_HTTP_PORT环境变量与 9411 端口。

2.2 Deployment 关键配置

jaegerDeployment（apps/v1）的关键字段：

• replicas: 1，strategy.type: Recreate——all-in-one 模式单实例即可。
• 容器镜像jaegertracing/all-in-one:1.39.0。
• 容器端口：16686（Jaeger UI）、9411（Zipkin HTTP 收集端口，兼容用）、14267（TChannel 收集端口）、14268（HTTP 收集端口）。
• readinessProbe 对14269端口执行 HTTP GET/。
• 注解prometheus.io/scrape: "true"、prometheus.io/port: "16686"，便于 Prometheus 抓取指标。
• 环境变量COLLECTOR_ZIPKIN_HTTP_PORT=9411。

2.3 两个 Service 的职责

Pachyderm 侧实际使用的是 HTTP 收集端口14268，对应 tracing.go 中的CollectorEndpoint配置；TChannel 与 Zipkin 端口保留但并非必须。

三、一键端口转发：start_port_forward.sh 实战

minikube 或 kind 等本地集群 中 LoadBalancer 往往无法直接分配外部 IP，脚本通过kubectl port-forward打通访问路径：

#!/bin/bash # Re-establish port-forward to jaeger jaeger_pod="$(kubectl get po -l app=jaeger -o jsonpath='{.items[].metadata.name}')" nohup kubectl port-forward "po/${jaeger_pod}" 16686 & # UI port nohup kubectl port-forward "po/${jaeger_pod}" 14268 & # Collector port nohup kubectl port-forward "po/etcd-0" 2379 & # etcd port-forward cat <<EOF ##################### # Connect pachctl to Jaeger with: export JAEGER_ENDPOINT=localhost:14268 ##################### EOF

要点说明：

• 脚本按app=jaeger标签动态获取 Pod 名称，不依赖手工填 Pod 名。
• 同时转发三个端口：16686（Jaeger UI）、14268（HTTP collector）、2379（etcd，便于本地调试）。
• 脚本末尾输出的JAEGER_ENDPOINT=localhost:14268正是下文要讲的 Pachyderm 追踪开关的核心环境变量。

四、让 Pachyderm 上报 trace：环境变量与源码实现

4.1 两个关键环境变量

Pachyderm 通过 src/internal/tracing/tracing.go 接入 Jaeger，核心机制是环境变量驱动：

• JAEGER_ENDPOINT=<host>:<port>：Jaeger collector 的 HTTP 收集端点地址（如localhost:14268），必须设置。
• PACH_TRACE={true,false}：设置后，Pachyderm 会为发出的 RPC 附加 Jaeger trace；JAEGER_ENDPOINT必须已指定。注意：对每个调用都开启追踪会拖慢调用速度，并让 Jaeger 中的有用 trace 更难筛选，因此并非每个调用都适合开启。

pachctl 的启动横幅也直接说明了这一用法，见 src/server/cmd/pachctl/cmd/cmd.go：

- PACH_TRACE={true,false} | (Opt) Attach Jaeger trace to outgoing RPCs; JAEGER_ENDPOINT must be specified. - JAEGER_ENDPOINT=<host>:<port> | Jaeger server to connect to.

4.2 InstallJaegerTracerFromEnv：追踪器初始化

InstallJaegerTracerFromEnv() 负责安装 Jaeger 客户端为 OpenTracing 全局 tracer，核心逻辑：

1. 用sync.Once保证只初始化一次。
2. 读取JAEGER_ENDPOINT；若未设置，则回退读取JAEGER_COLLECTOR_SERVICE_HOST与JAEGER_COLLECTOR_SERVICE_PORT_JAEGER_COLLECTOR_HTTP——这两个变量正是上面清单中jaeger-collectorService 注入 Pod 的 DNS 名与端口，意味着部署清单后无需手工配置端点。
3. 规范化端点为http://<host>:<port>/api/traces形式。
4. 构建 Jaeger 配置：服务名固定为pachd（JaegerServiceName），采样器为const+Param: 1（全采样），Reporter 设置LogSpans: true、BufferFlushInterval: 1s、CollectorEndpoint指向规范化后的端点。
5. 设置全局 tracer，并输出jaeger setup ok日志。

在用户机器上（pachctl）日志走 NullLogger，在服务端（pachd/worker）走 StdLogger。

调用位置：

• src/internal/pachd/setup.go：pachd 启动时调用，若返回非空端点表示已建立追踪连接。
• src/server/cmd/pachctl/main.go：pachctl 启动时调用，退出前调用CloseAndReportTraces()冲刷未上报的 trace。
• src/server/cmd/worker/main.go：worker 启动时调用。

4.3 采样控制：PACH_TRACE 如何生效

采样并非简单的全采样/全不采样，而是通过 addTraceIfTracingEnabled 这个 SpanInclusionFunc 控制：

• 若PACH_TRACE已设置，则总是上报 trace；若此时尚未建立 Jaeger 连接，会记录一条错误日志提示"PACH_TRACE 已设置但未连接 Jaeger"。
• 若未设置，则仅传播已存在的 trace（父 span 有效时继续上报子 span），不会主动发起新 trace。
• 对非 Jaeger 的 span context（如外部注入的 Zipkin trace）不处理。

也就是说：设置了PACH_TRACE后，从 pachctl 发出的每个 RPC 都会成为独立 trace 的根；不设置时，trace 只在已有链路上延续。这解释了文档中"追踪会拖慢调用"的提醒——PACH_TRACE是全链路打点。

4.4 gRPC 拦截器：trace 的传播通道

tracing.go 基于otgrpc（opentracing-contrib/go-grpc）为 gRPC 提供四类拦截器：

• UnaryClientInterceptor/StreamClientInterceptor：客户端侧，对非流式/流式 RPC 附加与传播 span。
• UnaryServerInterceptor/StreamServerInterceptor：服务端侧，接收并延续客户端传入的 span。

客户端侧拦截器被注册进 Pachyderm 客户端，见 src/client/client.go 与 src/internal/client/client.go。由此，pachctl → pachd、以及各服务间的 RPC 调用链可以跨进程形成完整 trace。

4.5 手动打点辅助函数

除自动拦截器外，tracing.go 还提供手工埋点工具：

• TagAnySpan(spanBox, kvs...)：向 span（或从 context 提取的 span）追加任意键值标签。
• AddSpanToAnyExisting(ctx, operation, kvs...)：若 context 中已有 span，则生成其子 span 并返回新 context。
• FinishAnySpan(span, kvs...)：为 span 打标签并结束，与AddSpanToAnyExisting配对使用。
• CloseAndReportTraces()：关闭全局 tracer，触发 Jaeger 客户端把未上报的 trace 发送给 collector，pachctl 退出时调用。

五、端到端启用步骤

1. 部署 Jaeger：kubectl apply -f etc/deploy/tracing/jaeger-all-in-one.yaml，等待 Pod 就绪。
2. 打通网络（本地集群）：执行etc/deploy/tracing/start_port_forward.sh，或手动kubectl port-forward转发 16686 与 14268。
3. 配置端点：在运行 pachctl 的终端export JAEGER_ENDPOINT=localhost:14268；pachd 若部署在同一集群，可直接依赖JAEGER_COLLECTOR_SERVICE_HOST自动发现 collector。
4. 开启追踪：export PACH_TRACE=true，随后执行 pachctl 命令。
5. 观察链路：浏览器访问 Jaeger UI（端口转发下为http://localhost:16686），按服务名pachd检索 trace，定位慢调用。
6. （可选）关闭追踪：unsetPACH_TRACE，即可恢复"仅传播既有 trace"的模式，降低性能开销。

六、适用前提与注意事项

• 本清单面向 Jaeger all-in-one 单实例部署（replicas: 1、Recreate策略），适合开发与诊断场景；生产环境如需高可用，应改用 Jaeger 分布式部署形态。
• 镜像固定为jaegertracing/all-in-one:1.39.0，如需升级请同步核对端口与 API 兼容性。
• PACH_TRACE会显著增加打点量，建议仅在诊断慢调用时临时开启，避免长期全量采样淹没关键链路。
• 若PACH_TRACE已设置但未连接 Jaeger，pachd/pachctl 会输出明确错误日志，便于快速排查环境变量配置问题。

• 数据工程
• 后端
• 云原生
• 任务调度
• 微服务