Moby 仓库中的 OpenTelemetry-Go（v1.46.0）：信号体系、导出器与 Docker 引擎可观测性落地

本篇文章以 vendor/go.opentelemetry.io/otel/README.md 为骨架——它是随 Moby 项目一起 vendor 进来的 OpenTelemetry 官方 Go 实现（版本 1.46.0）的项目说明文档。Moby 并不是简单把该库"放进来"，而是将 OTel 的 Traces 信号深度集成进 dockerd 守护进程：从 daemon/internal/otelutil/provider.go 的 TracerProvider 初始化，到 contrib/otel 一键可跑的 Collector + Jaeger + Aspire 观测栈，都建立在这份 README 描述的 API 与导出器体系之上。读完本文，你将掌握 OTel 三大信号的成熟度现状、Go 版本兼容策略、OTLP 等导出器的选型，以及如何在本地跑起一套真实观察 dockerd 调用链的可观测性环境。

一、文档定位：随库携带的官方 README

vendor/go.opentelemetry.io/otel/README.md 是 OpenTelemetry 项目面向 Go 语言的官方实现说明文档。它并不是 Moby 自研的可观测性设计文档，而是上游项目（OpenTelemetry-Go）的"门面"，因此承担着两类任务：

1. 向使用者说明 OTel-Go 的定位：OpenTelemetry-Go is the Go implementation of OpenTelemetry，提供一组 API 直接测量软件的性能与行为，并把数据发送给可观测性平台；
2. 声明项目状态、兼容性、上手路径与导出器选型等元信息。

在同一仓库的 go.mod 中可以看到 Moby 对这套库的实际依赖锁定：

go.opentelemetry.io/otel v1.46.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.46.0
go.opentelemetry.io/otel/sdk v1.46.0
go.opentelemetry.io/otel/trace v1.46.0

并间接依赖 metric v1.46.0、log v0.22.0、otlpmetricgrpc/otlpmetrichttp v1.46.0 等模块；而库自身的版本字符串同样定义在 vendor/go.opentelemetry.io/otel/version.go（Version() 返回 1.46.0）。这意味着本文下面描述的三信号状态、导出器能力，都对应 v1.46.0 这一具体版本。

二、信号状态：Traces 与 Metrics 稳定，Logs 处于 Beta

README 的第一张核心表是 Project Status（项目状态），它直接告诉使用者"哪些信号可以放心用于生产"：

Signal	Status
Traces	Stable（稳定）
Metrics	Stable（稳定）
Logs	Beta（测试阶段）

这张表的工程含义非常关键：

• Stable 意味着语义约定（semantic conventions）与 API 签名已经冻结，升级主版本前不会出现破坏性变更，用户可以基于它构建长期依赖；上游仓库的进度与里程碑由项目 boards 和 milestones 持续跟踪。
• Logs 仍处于 Beta，代表日志信号的 API 仍在演进。在 Moby 仓库的 vendor 目录中也可以观察到这一信号差异：log 与 sdk/log 两个包均为 v0.22.0（见 go.mod），采用 0.x 版本号本身即是"未稳定"的信号。
• 项目的版本化信息与稳定性保证细节记录在配套的 VERSIONING.md 文档中（即 README 中 [versioning documentation](https://gitcode.com/GitHub_Trending/mo/moby/blob/252bd664babaa81e2c579352e78a09bab0160f4f/vendor/go.opentelemetry.io/otel/VERSIONING.md?utm_source=gitcode_repo_files) 的相对链接，指向 vendor 目录下的同一文件）。

从源码结构看，三大信号分别对应仓库根目录下的 trace、metric 与 log 三个公开包，并由 sdk 提供面向实现方的 SDK 层。

三、Go 版本兼容性策略与支持矩阵

README 明确声明 OpenTelemetry-Go 与 当前受支持的 Go 版本保持兼容，其策略原话如下：

Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release.

即：每个 Go 主版本会一直支持到出现两个更新主版本为止。对上游已停止支持的 Go 版本，otlp 团队按两步节奏收尾：

1. 先发布一个 minor 版本以支持新发布的 Go；
2. 再在下一个 minor 版本中移除对最老（已归档）Go 版本的兼容性测试——从那时起，库可能使用仅当前受支持 Go 版本才有的特性。

README 同时给出了该版本受支持环境矩阵（按 Ubuntu / macOS / Windows × Go 1.27/1.26/1.25 × 架构），这是判断"能否安全引入该版本库"的第一手依据：

OS	Go Version	Architecture
Ubuntu	1.27	amd64
Ubuntu	1.26	amd64
Ubuntu	1.25	amd64
Ubuntu	1.27	386
Ubuntu	1.26	386
Ubuntu	1.25	386
Ubuntu	1.27	arm64
Ubuntu	1.26	arm64
Ubuntu	1.25	arm64
macOS	1.27	amd64
macOS	1.26	amd64
macOS	1.25	amd64
macOS	1.27	arm64
macOS	1.26	arm64
macOS	1.25	arm64
Windows	1.27	amd64
Windows	1.26	amd64
Windows	1.25	amd64
Windows	1.27	386
Windows	1.26	386
Windows	1.25	386

README 特别注明：项目"在其他系统上大概率可用，但目前不提供兼容性保证"。对依赖方（例如 Moby 这样的下游厂商）而言，这意味着引入前应核对自身构建环境是否落在上表范围内。

四、上手流程：插桩（Instrumentation）与导出（Export）两步走

README 用两句话概括了 OTel 的设计目标：provide a single set of APIs to capture distributed traces and metrics from your application and send them to an observability platform——即一套 API 同时采集分布式链路与指标并外送。对 Go 应用而言，落地分为两步：先插桩、再导出。

4.1 Instrumentation：插桩的两种方式

要让应用开始产出链路与指标事件，第一步是插桩，官方推荐两条路径：

• 使用现成的插桩库（instrumentation library）：这是最省力的方式。官方维护的一系列插桩库位于 opentelemetry-go-contrib 仓库的 instrumentation 目录下，覆盖主流 HTTP 框架、数据库客户端等场景（README 以外部链接给出地址，此处不再赘述）；
• 直接用 go.opentelemetry.io/otel 包构建自定义插桩：当插桩库覆盖不到、或需要扩展其上报的遥测内容时，直接调用 OTel-Go 的核心 API。README 还建议参考官方 examples 了解实际用法。

4.2 Moby 中的真实插桩案例

Moby 守护进程正是"直接使用 otel 包手工插桩"的典型范例。在 daemon/start.go 中，容器启动路径被包装成一个命名 span：

ctx, span := otel.Tracer("").Start(ctx, "daemon.containerStart", trace.WithAttributes(append(
    // ... 一组 attribute
)...))
// ...
otelutil.RecordStatus(span, retErr)

从源码结构看，这类插桩遍布引擎各关键路径：daemon/internal/libcontainerd（容器生命周期）、daemon/logger/loggerutils/logfile.go（日志落盘）、daemon/libnetwork（网络子系统的 endpoint、sandbox、resolver、overlay/ipvlan/macvlan 驱动），以及 daemon/server/server.go 与 daemon/command/daemon.go（启动与命令入口）等，合计几十处文件均引用了 go.opentelemetry.io/otel。换言之，每次 docker start、网络接入、日志读写都会在 OTel 语义下产出结构化 trace。

4.3 Export：把遥测数据送出去

插桩只负责"采集"，真正要被人观测到，还需要一条**导出管线（export pipeline）**把遥测送到可观测性平台。README 给出的结论是：OpenTelemetry 项目官方支持的所有导出器都集中在项目的 exporters 目录中，其能力矩阵如下：

Exporter	Logs	Metrics	Traces
OTLP	✓	✓	✓
Prometheus		✓
stdout	✓	✓	✓
Zipkin			✓

按上文"相对链接以仓库根为起点"的约定，上表中的目录对应仓库内路径为：vendor/go.opentelemetry.io/otel/exporters/otlp、vendor/go.opentelemetry.io/otel/exporters/prometheus、vendor/go.opentelemetry.io/otel/exporters/stdout、vendor/go.opentelemetry.io/otel/exporters/zipkin。读表要点：

• OTLP 是唯一同时支持 Logs、Metrics、Traces 三信号的导出器，也是默认推荐选项；
• Prometheus 只用于暴露 Metrics（由其拉取模型决定），Zipkin 只消费 Traces。

需要特别说明的是：上表是上游 OTel 项目的官方导出器全景，而 Moby 仓库的 vendor 快照出于依赖裁剪，实际只 vendor 了 exporters/otlp 一个目录。结合 go.mod，Moby 直接依赖的正是 otlptrace/otlptracehttp（HTTP 协议），并通过间接依赖引入 otlpmetricgrpc、otlpmetrichttp、otlptracegrpc——其中 HTTP 变体被 dockerd 的配置路径实际使用。

五、在 Moby 仓库中的深度落地：provider 初始化与一键体验栈

把 README 的"API + SDK + Exporter"理论落到 Moby 工程里，可以看到一条清晰的实现链。

5.1 TracerProvider 的装配

daemon/internal/otelutil/provider.go 中的 NewTracerProvider 展示了典型的三段式装配：

exp, err := detect.NewSpanExporter(ctx)          // 1. 探测并创建 span 导出器
if err != nil {
    log.G(ctx).WithError(err).Warn("Failed to initialize tracing, skipping")
    if allowNoop {
        return noop.NewTracerProvider(), noopShutdown  // 失败时优雅降级为 no-op
    }
}
if allowNoop && detect.IsNoneSpanExporter(exp) {       // 2. 未配置 OTel 时降级
    log.G(ctx).Info("OTEL tracing is not configured, using no-op tracer provider")
    return noop.NewTracerProvider(), noopShutdown
}
tp := sdktrace.NewTracerProvider(                     // 3. 组装 SDK TracerProvider
    sdktrace.WithResource(resource.Default()),
    sdktrace.WithSyncer(detect.Recorder),
    sdktrace.WithBatcher(exp),
    sdktrace.WithSpanProcessor(baggagecopy.NewSpanProcessor(func(member baggage.Member) bool { return true })),
)
return tp, tp.Shutdown

这段代码与 README 的关键概念一一呼应：trace.TracerProvider 是 SDK 门面（对应 go.opentelemetry.io/otel/trace 包），WithResource(resource.Default()) 注入资源信息（来自 sdk/resource），WithBatcher(exp) 让 span 以批量方式交给导出器——没有配置 OTel 时引擎并不会崩溃，而是通过 noop 实现透明降级，保证 dockerd 无观测配置时零额外开销。同目录下还提供了 RecordStatus（见 daemon/internal/otelutil/status.go）与 baggage 处理（daemon/internal/otelutil/baggage.go）等辅助件。

5.2 如何决定是否开启：OTLP 端点环境变量

README 面向的是一般 Go 应用，而 Moby 通过约定一个环境变量来决定"导出到哪"。根据 contrib/otel/README.md 的说明，本地试验流程的第一步就是：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

再以携带该环境变量的方式启动 dockerd——引擎探测到端点后即会初始化真实导出管线；配合 allowNoop 逻辑，未设置该变量时引擎自动走 no-op 路径，这就是 5.1 中 IsNoneSpanExporter 判断的实际用途。

5.3 一键拉起 Jaeger + Aspire 的观测后端

contrib 目录为验证 Moby 的 OTel 功能提供了最小可运行观测栈（详见 contrib/otel）：

• Jaeger（jaegertracing/all-in-one）与 Aspire Dashboard（mcr.microsoft.com/dotnet/nightly/aspire-dashboard）两个可视化容器，分别暴露 16686 与 18888 端口；
• OpenTelemetry Collector（otel/opentelemetry-collector-contrib）作为中转，暴露默认 OTLP HTTP 端口 4318，其行为由 contrib/otel/otelcol.yaml 定义：

# moby currently uses http
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls::insecure: true
  otlp/aspire:
    endpoint: aspire-dashboard:18889
    tls::insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/jaeger, otlp/aspire]

配置文件中的注释 moby currently uses http 与 5.2 节 http://localhost:4318 的端点前后一致，印证了 Moby 当前采用 OTLP/HTTP 上报、再由 Collector 扇出到 Jaeger 与 Aspire 两条 trace 后端的链路。contrib/otel/compose.yaml 还通过 develop.watch 实现了对 otelcol.yaml 的热同步重启，方便边改配置边观察。

完整验证步骤（摘录自 contrib/otel/README.md，细节随你的构建方式略有差异）：

1. 导出 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 并确保 dockerd 继承该变量；
2. 启动待观测的 Moby 引擎；
3. 在 contrib/otel 目录执行 docker compose up -d 启动观测栈；
4. 用 Docker CLI 向引擎发起若干请求以产生链路；
5. 打开 Jaeger（http://localhost:16686）或 Aspire Dashboard（http://localhost:18888/traces）；
6. 在 Jaeger 左上角服务下拉框中选中 dockerd 即可查看引擎自身产生的 trace；
7. 收尾时在 contrib/otel 目录执行 docker compose down，并 unset OTEL_EXPORTER_OTLP_ENDPOINT 还原环境。

六、版本演进与参与上游

作为随库文档，README 还把读者引向两份仓库内可继续深挖的文件：

• VERSIONING.md：详细定义版本化策略与各信号/包在 minor、patch 层面的稳定性承诺；
• CONTRIBUTING.md：上游贡献指南（文档同时提及 triager Emeritus 角色 Alex Kats 等人事安排，属于社区治理信息）。

对 Moby 这样的下游而言，这两份文件是评估"何时可以升级依赖"的权威依据：只有了解 OTel-Go 的兼容性窗口（第三节）与稳定性分级（第二节），才能在引擎这样长期运行的守护进程中安全地引入新版本库。

结语

透过 vendor/go.opentelemetry.io/otel/README.md 这扇窗，我们既看到了 OpenTelemetry-Go v1.46.0 的完整面貌——Traces/Metrics 稳定、Logs Beta 的信号分级，严格的 Go 版本兼容策略，以及 OTLP / Prometheus / stdout / Zipkin 的导出器能力矩阵；也看到了它如何在 Moby 中真实落地：otelutil.NewTracerProvider 完成 SDK 装配与 no-op 降级、daemon.containerStart 等 span 遍布引擎关键路径、contrib/otel 提供从 OTEL_EXPORTER_OTLP_ENDPOINT 到 Jaeger/Aspire 的完整本地观测体验。若你想亲自验证，按第五节步骤跑起观测栈、在 Jaeger 中看到 dockerd 服务的那一刻，这套"插桩—导出—可视化"链路便有了最直观的注脚。