使用 OpenTelemetry Collector Builder 定制 Jaeger 发行版components/ 公共 API 与 ocb 装配实战【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaegerJaeger V2 已全面基于 OpenTelemetry Collector 构建而components/目录正是面向外部开发者开放的一组公共 API用于通过 ocbOpenTelemetry Collector Builder自由拼装属于自己的 Jaeger 发行版。本文将围绕 components/README.md 展开深入解读目录布局、双重派发模式与第三方组件别名机制并结合 cmd/jaeger/builder.yaml 与 cmd/jaeger/internal/components.go 的源码证据给出从零编写 builder.yaml 到产出可运行二进制的完整实战方案。components/ 目录的定位自定义发行版的公共 APIJaeger 的“定制发行版”custom distribution机制由来已久其设计决策记录在 docs/adr/011-custom-distributions.md 中。简单来说Jaeger 希望开发者不必 fork 整个仓库、不必改动 Jaeger 核心代码就能通过一份清单文件把需要的组件receiver、processor、exporter、extension、connector、telemetry组装成一个全新的、可独立发布的二进制。components/目录就是这个机制对外暴露的唯一公共面。正如其 README 开头所写该目录提供的是构建自定义 Jaeger 发行版的公共 API核心工具是 ocbOpenTelemetry Collector Builder。ocb 读取一份builder.yaml清单自动生成并编译一个仅包含清单中所列组件的 Collector 二进制——Jaeger V2 的默认发行版正是用同一套流程产出的。与这一目标相对应components/目录内部刻意做了职责切分顶层包extension/、exporter/、processor/、telemetry/Jaeger 专属组件即只存在于 Jaeger 生态、由 Jaeger 自己维护实现的组件ext/第三方 OTel Collector 组件来自 otel-contrib 与 collector core仓库内只保留一行别名式的转发声明cmd/jaeger/components/位于cmd/jaeger子树内的桥接层负责突破 Gointernal包访问限制详见下文双重派发一节。目录布局解读两层结构各司其职顶层包Jaeger 专属组件与双重派发模式顶层包包括components/extension/、components/exporter/、components/processor/、components/telemetry/容纳的是 Jaeger 自研组件例如extension/jaegerstorage接入 Jaeger 存储后端Cassandra、Elasticsearch、Badger 等的扩展extension/jaegerquery提供 Jaeger Query 服务的扩展extension/remotesampling远程采样策略管理扩展extension/expvar暴露 Goexpvar指标extension/remotestorage远程存储服务扩展exporter/storageexporter通用的写入 Jaeger v1 spanstore.SpanWriter导出器processor/adaptivesampling自适应采样处理器telemetryJaeger 的遥测工厂。这些组件之所以需要一套特殊的双重派发double-dispatch结构根因是Go 语言的internal包访问限制只有位于cmd/jaeger/子树内的代码才能导入cmd/jaeger/internal/而公共的components/目录在该子树之外无法直接引用内部实现。为此仓库在cmd/jaeger/components/下放置了一层桥接包每个包只有一个小小的factory.go例如 cmd/jaeger/components/extension/jaegerstorage/factory.gopackage jaegerstorage import impl github.com/jaegertracing/jaeger/cmd/jaeger/internal/extension/jaegerstorage var NewFactory impl.NewFactory而公共门面facade再对这一桥接层做一次别名转发例如 components/extension/jaegerstorage/factory.gopackage jaegerstorage import impl github.com/jaegertracing/jaeger/cmd/jaeger/components/extension/jaegerstorage var NewFactory impl.NewFactory这样便形成了一条完整的调用链公共门面 → 桥接层 → 内部实现。外部使用者只依赖components/下的公共包内部实现细节则始终被internal规则保护。桥接层的设计说明完整记录在 cmd/jaeger/components/README.md 中。ext/第三方组件的一行别名与 Jaeger 专属组件不同来自 otel-contrib 与 collector core 的第三方组件完全绕开双重派发通过components/ext/直接转发上游工厂。这些包同样是一行别名例如 components/ext/extension/healthcheckv2extension/factory.gopackage healthcheckv2extension import impl github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckv2extension var NewFactory impl.NewFactory这种做法带来的关键收益是版本一致性builder.yaml里所有第三方组件都可以通过同一个gomod条目github.com/jaegertracing/jaeger被引用而无需逐个锁定上游组件的版本。各第三方组件的真实版本由 Jaeger 自己的go.mod传递解析从而保证整个发行版内组件的版本互相兼容、同步升级。用 ocb 构建发行版builder.yaml 的写法最小示例公共 API 的使用方式在自定义发行版的builder.yaml中只需按 ocb 的清单格式引用上述公共包即可。以下示例摘自 components/README.mdextensions: - gomod: github.com/jaegertracing/jaeger v2.19.0 import: github.com/jaegertracing/jaeger/components/extension/jaegerstorage - gomod: github.com/jaegertracing/jaeger v2.19.0 import: github.com/jaegertracing/jaeger/components/ext/extension/healthcheckv2extension两个字段的含义gomodocb 生成 go.mod 时使用的模块标识与版本。所有组件统一指向github.com/jaegertracing/jaeger及其某个发布版本如v2.19.0第三方组件的实际版本由此传递解析import该组件的 Go 导入路径即上文components/下对应包的路径。完整参考清单cmd/jaeger/builder.yaml 逐节解析cmd/jaeger/builder.yaml 是官方提供的完整参考清单它精确复刻了 Jaeger 默认生产发行版的组件集合同时充当文档与 CI 校验产物。其头部注释明确说明清单中的组件列表与标准二进制使用的internal.Components()完全一致而像storagecleaner这类仅用于测试的组件则两者都不包含由 cmd/jaeger/internal/integration/jaeger-e2e 单独注册。清单的顶层结构如下区块说明组件数量dist发行版自身的模块名、二进制名、输出路径1telemetry遥测工厂1extensions扩展含认证、健康检查、存储、采样等10receivers接收器OTLP、Jaeger、Kafka、Zipkin 等5exporters导出器调试、OTLP、Kafka、Prometheus、存储等7processors处理器批处理、内存限制、尾采样、自适应采样等6connectors连接器forward、spanmetrics2replaces仓库内构建时的本地替换指令1各区块的完整内容已按官方清单整理dist: module: github.com/jaegertracing/jaeger/cmd/jaeger/ocb-build name: jaeger description: Jaeger - distributed tracing platform output_path: ./cmd/jaeger/_build telemetry: gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/telemetry extensions: - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/extension/healthcheckv2extension - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/extension/pprofextension - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/extension/zpagesextension - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/extension/basicauthextension - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/extension/sigv4authextension - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/extension/jaegerquery - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/extension/jaegerstorage - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/extension/remotesampling - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/extension/expvar - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/extension/remotestorage receivers: - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/receiver/otlpreceiver - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/receiver/nopreceiver - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/receiver/jaegerreceiver - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/receiver/kafkareceiver - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/receiver/zipkinreceiver exporters: - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/exporter/debugexporter - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/exporter/otlpexporter - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/exporter/otlphttpexporter - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/exporter/nopexporter - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/exporter/storageexporter - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/exporter/kafkaexporter - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/exporter/prometheusexporter processors: - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/processor/batchprocessor - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/processor/memorylimiterprocessor - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/processor/tailsamplingprocessor - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/processor/attributesprocessor - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/processor/filterprocessor - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/processor/adaptivesampling connectors: - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/connector/forwardconnector - gomod: github.com/jaegertracing/jaeger v0.0.0 import: github.com/jaegertracing/jaeger/components/ext/connector/spanmetricsconnector replaces: - github.com/jaegertracing/jaeger v0.0.0 ../../../注意清单头部注释中的两个关键约定仓库内构建所有组件使用github.com/jaegertracing/jaeger v0.0.0作为gomod配合replaces指令指向本地源码这是为了在仓库内直接编译外部使用外部用户应把v0.0.0替换为真实发布版本例如v2.19.0并删除replaces指令让依赖从上游模块解析。源码级装配原理从清单到可运行二进制builder.yaml描述的组件集合与标准二进制实际注册的组件严格一一对应这一对应关系在 cmd/jaeger/internal/components.go 的Components()函数中得到印证。该函数通过defaultBuilders().build()依次构造五类工厂映射Extensions标准部分healthcheckv2、pprof、zpages与add-onsbasicauth、sigv4auth、jaegerquery、jaegerstorage、remotesampling、expvar、remotestorageReceivers标准部分otlp、nop与 add-onsjaeger、kafka、zipkinExporters标准部分debug、otlp、otlphttp、nop与 add-onsstorageexporter——注释明确标注为通用的 Jaeger v1 spanstore.SpanWriter 导出器、kafka、prometheus并保留了一行被注释掉的elasticsearch.NewFactory()说明该组件当前未纳入默认发行版Processors标准部分batch、memorylimiter、tailsampling、attributes、filter与 add-onsadaptivesamplingConnectors标准部分forward与 add-onsspanmetrics。所有工厂对象均来自components/公共包import语句直接引用了github.com/jaegertracing/jaeger/components/...这正验证了 README 所述——公共目录是唯一被内外共同消费的组件来源。ocb 生成的发行版在运行时按同样的工厂映射装配组件只是入口从internal.Components()换成了清单驱动的代码生成。构建命令与跨平台编译参考清单的头部注释给出了完整的构建方式。在仓库内执行ocb --config cmd/jaeger/builder.yamlocb 会根据dist.output_path./cmd/jaeger/_build生成编译产物。跨平台编译通过 Go 标准的环境变量完成GOOSlinux GOARCHarm64 ocb --config cmd/jaeger/builder.yamlocb 生成的二进制即为一个独立的 Jaeger 发行版之后用 Jaeger V2 的配置文件例如 cmd/jaeger/config.yaml即可启动。仓库还提供了 cmd/jaeger/config-ocb-smoketest.yaml用于对 ocb 产物做冒烟测试可视为清单与配置联动的官方验证示例。定制实战如何添加自定义组件ocb 清单的价值正在于增删组件、重塑发行版。官方推荐的做法是复制 cmd/jaeger/builder.yaml在相应区块末尾追加条目extensions、receivers、exporters、processors、connectors 各有独立区块然后运行 ocb 构建。对于想深入了解自定义组件长什么样的读者仓库内自带一个真实范例components/extension/queryinterceptorexample/含 factory.go、config.go、extension.go 及配套的 config-query-interceptor.yaml 与集成测试演示如何编写一个拦截 Jaeger Query 请求的自定义扩展是学习如何为自定义发行版编写 Jaeger 专属组件的最佳入门素材。在动手定制时还需要留意以下事实均可在清单注释与源码中验证若引入的是 Jaeger 自研组件必须遵循components/下的双重派发模式确保内部实现不被internal规则阻断若引入的是上游 OTel 第三方组件应参照components/ext/的别名写法统一通过github.com/jaegertracing/jaeger这一个gomod条目引用保持版本一致性测试专用组件如storagecleaner既不在builder.yaml也不在internal.Components()中而是由 cmd/jaeger/internal/integration/jaeger-e2e 按需注册因此生产发行版不应包含此类组件。综上components/目录 ocb 的组合构成了 Jaeger 自定义发行版的完整工作流公共 API 提供稳定的组件契约ext/别名保证上游组件版本随 Jaeger 整体对齐builder.yaml清单则让开发者用最少的配置组合出自己的分发二进制。无论是裁剪默认发行版、加入私有组件还是构建面向特定存储与网络环境的专用版本这套机制都能在不修改 Jaeger 核心的前提下完成。【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考