Jaeger V2 快速上手指南：基于 OpenTelemetry Collector 的分布式追踪平台部署与源码架构解析

Jaeger V2 快速上手指南：基于 OpenTelemetry Collector 的分布式追踪平台部署与源码架构解析

【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger

Jaeger V2（本仓库 cmd/jaeger 目录下的全新主程序）彻底重构为基于 OpenTelemetry Collector 的单一后端二进制，集采集、存储、查询、UI 于一体，并通过 OCB（OpenTelemetry Collector Builder）实现组件化定制。本文以官方快速上手流程为主线，先带你用docker compose在几分钟内跑起 Jaeger V2 与 HotROD 演示应用，再深入main.go、internal/command.go、all-in-one.yaml等源码与配置，剖析其默认端口、内嵌配置机制与组件注册表，读完即可独立完成部署、调试与自定义构建。

背景：Jaeger V2 为何基于 OpenTelemetry Collector

cmd/jaeger/README.md开宗明义："Jaeger V2 based on OpenTelemetry collector"。这意味着 Jaeger 的后端不再维护一套独立的 Collector 实现，而是直接复用 OTel Collector 的运行时：配置解析（confmap）、管线（pipeline）编排、组件工厂（factory）体系、遥测（telemetry）初始化全部来自go.opentelemetry.org/collector。Jaeger 自身则以"扩展（extension）/ 接收器（receiver）/ 导出器（exporter）/ 处理器（processor）/ 连接器（connector）"的形式注入 OTel Collector，形成一个开箱即用的 all-in-one 发行版。

从仓库入口文件 cmd/jaeger/main.go 可以看到最直接的证据：

func main() { factories, err := jaegercli.Components() if err != nil { log.Fatal(err) } if err := jaegercli.NewCommand(factories).Execute(); err != nil { log.Fatal(err) } }

程序先通过jaegercli.Components()组装默认组件工厂集合，再由jaegercli.NewCommand(factories)创建基于 cobra 的根命令并执行——这个命令本质上就是otelcol.NewCommand(settings)的封装（见 cmd/jaeger/internal/command.go），同时附加了version、docs、mappings等 Jaeger 专属子命令。

快速上手：用 docker compose 启动 Jaeger V2 与 HotROD

README 提供的快速体验路径只需一个docker-compose.yml文件。该文件已随仓库提供：examples/hotrod/docker-compose.yml，其中定义了jaeger与hotrod两个服务：

services: jaeger: image: ${REGISTRY:-}jaegertracing/jaeger:${JAEGER_VERSION:-latest} ports: - "16686:16686" # Jaeger UI - "16687:16687" - "4317:4317" # OTLP gRPC - "4318:4318" # OTLP HTTP environment: - LOG_LEVEL=debug networks: - jaeger-example hotrod: image: ${REGISTRY:-}jaegertracing/example-hotrod:${HOTROD_VERSION:-latest} ports: - "8080:8080" - "8083:8083" command: ["all"] environment: - OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4318 networks: - jaeger-example depends_on: - jaeger

标准启动步骤

1. 获取 compose 文件：从仓库直接引用即可，无需额外下载：

   # 方式一：直接在仓库内查看 examples/hotrod/docker-compose.yml # 方式二：等价于文档中的 curl 下载步骤，仅需保证文件与仓库版本一致

2. （可选）固定镜像版本：默认情况下docker compose使用latest标签。第一次拉取时没有问题，但镜像进入本地 registry 后latest不会再更新，可能长期运行过期（甚至不兼容）的 Jaeger 与 HotROD 版本。建议通过环境变量JAEGER_VERSION与HOTROD_VERSION显式固定版本，例如2.0.0与1.63.0。

3. 启动后端与演示应用：

   JAEGER_VERSION=2.0.0 HOTROD_VERSION=1.63.0 docker compose -f docker-compose.yml up

4. 访问服务：

   • Jaeger UI：http://localhost:16686
   • HotROD 演示应用：http://localhost:8080

5. 停止并清理：

   docker compose -f docker-compose.yml down

关于版本固定的一句话忠告

compose 文件通过${JAEGER_VERSION:-latest}、${HOTROD_VERSION:-latest}支持环境变量注入（examples/hotrod/docker-compose.yml）。在第一次实验时使用latest完全没问题，但若要长期运行或复现问题，务必按上文固定具体版本号，避免latest标签不更新导致的"陈旧镜像"陷阱。

为什么可以"零配置"启动：内嵌 all-in-one 配置机制

你可能会好奇：上面的 compose 文件里并没有给 Jaeger 挂载任何配置文件，它是怎么知道监听哪些端口、把数据写到哪里的？答案在 cmd/jaeger/internal/command.go 的//go:embed all-in-one.yaml与checkConfigAndRun逻辑中：

//go:embed all-in-one.yaml var yamlAllInOne embed.FS

由于 OTel Collector 原生要求显式提供--config，Jaeger 拦截了官方的RunE实现（代码注释也说明这是针对 OTel Collector 尚无可用的钩子而做的 workaround）：当命令行参数中没有出现任何--config标志时，自动读取内嵌的 cmd/jaeger/internal/all-in-one.yaml，并将其作为yaml:协议的配置注入，随后打印日志提示你"正在使用默认 All-in-One 配置与内存存储"。

这带来两个直接好处：

• 零配置可用：docker run jaegertracing/jaeger:latest即可得到一个完整可用的追踪平台；
• 可渐进式接管：一旦你传入自己的--config，内嵌配置即被替换，行为完全由你的配置文件决定。

默认 all-in-one 配置与端口全景

内嵌的 cmd/jaeger/internal/all-in-one.yaml 是理解 Jaeger V2 默认行为的最佳入口。它声明了以下服务扩展与管线：

service: extensions: [jaeger_storage, jaeger_query, remote_sampling, healthcheckv2, expvar, zpages] pipelines: traces: receivers: [otlp, jaeger, zipkin] processors: [batch] exporters: [jaeger_storage_exporter]

管线含义清晰：同时接收 OTLP、原生 Jaeger 协议与 Zipkin 三种格式的追踪数据，经过batch批处理处理器后，由jaeger_storage_exporter写入存储（默认some_storage对应的memory后端，max_traces: 100000）。

各组件监听的端口汇总如下（均可用环境变量JAEGER_LISTEN_HOST覆盖默认的localhost，Dockerfile 中则固定为0.0.0.0，见 cmd/jaeger/Dockerfile）：

其中remote_sampling默认采用文件采样策略，default_sampling_probability: 1、reload_interval: 1s；配置里也预留了adaptive自适应采样策略的注释示例（对应 components/processor/adaptivesampling）。jaeger_query还默认启用了内嵌的 MCP AI 工具端点（mcp: {}），用于在查询端口提供/api/ai/mcp/服务。

组件注册表：Jaeger V2 默认发行版包含什么

如果你想知道这个"开箱即用"发行版到底打包了哪些组件，直接看 cmd/jaeger/internal/components.go 的build()方法。它把所有 Jaeger 组件按 OTel Collector 的五类工厂组织起来：

• Extensions：标准项healthcheckv2、pprof、zpages；Jaeger 附加项basicauthextension、sigv4authextension、jaegerquery、jaegerstorage、remotesampling、expvar、remotestorage；
• Receivers：otlp、nop，以及 Jaeger 附加的jaeger、kafka、zipkin；
• Exporters：debug、otlp、otlphttp、nop，加上storageexporter（通用 Jaeger v1 spanstore.SpanWriter 导出器）、kafka、prometheus；
• Processors：batch、memorylimiter、tailsampling、attributes、filter，以及 Jaeger 的adaptivesampling；
• Connectors：forward、spanmetrics。

这些组件的实现分散在仓库 components 目录下（每个组件均含factory.go与package_test.go），是研究某一具体能力（如 Kafka 接收、尾采样、SPM 服务性能监控）的入口。

进阶：用 OCB 构建你自己的 Jaeger 发行版

jaegercli包的设计目标之一就是"可复用"：它显式暴露Components()与NewCommand(factories)，以便自定义 OCB 发行版保留内嵌 all-in-one 默认配置与 Jaeger 专属子命令（见 cmd/jaeger/jaegercli/command.go 的包注释）。

仓库提供了参考清单 cmd/jaeger/builder.yaml，它逐条复刻了默认发行版的组件集，既是文档也是 CI 校验产物。使用方式：

ocb --config cmd/jaeger/builder.yaml

如需自定义：拷贝该文件，在对应分区追加组件条目即可；跨平台编译通过GOOS/GOARCH环境变量完成，例如GOOS=linux GOARCH=arm64 ocb --config cmd/jaeger/builder.yaml。注意builder.yaml使用github.com/jaegertracing/jaeger v0.0.0加replaces指令以支持仓库内构建，外部使用者应替换为真实发布版本（如v2.19.0）并移除replaces。

从演示走向生产：显式配置文件示例

当你不满足于内存存储，仓库 cmd/jaeger/config.yaml 给出了更完整的生产级配置参考：存储可配置traces与traces_archive双后端、UI 通过config_file指定config-ui.json、查询扩展可启用otlp_proxy（把 UI 同源的 OTLP/HTTP 数据转发到本地 4318）、max_clock_skew_adjust控制时钟偏移校正（默认0s表示关闭），以及adaptive_sampling处理器的接入示例。将其与内嵌all-in-one.yaml对比阅读，即可系统掌握 Jaeger V2 从默认到定制的能力边界。

延伸阅读

• 演示应用细节与单独运行方式（含 Kubernetes 部署、源码运行）：examples/hotrod/README.md
• 默认发行版组件工厂实现：cmd/jaeger/internal/components.go
• OCB 构建清单：cmd/jaeger/builder.yaml
• 容器镜像端口与调试镜像（Delve）说明：cmd/jaeger/Dockerfile
• 仓库根目录总览：README.md

【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger