otel-go

Go 中的 OpenTelemetry

Go 服务中 OpenTelemetry 机制的入口。请根据 任务加载下方的参考资料；每份资料都可独立使用。

参考资料

文件	适用场景
references/declarative-setup.md	通过 otelconf 和 YAML 配置 SDK：提供程序、传播器、关闭操作、环境变量替换。
references/api.md	查找导入路径、全局 API 访问方式、追踪器／计量器／日志记录器的用法、属性、传播机制、日志桥接（zap、slog）。
references/instrumentation-libraries.md	选择或接入 contrib 库（otelhttp、otelgrpc、数据库、AWS、消息队列、传播器、资源检测器），以及编写遵循 semconv 的手动埋点。
references/performance.md	调优采样、批处理器、指标读取器、导出器压缩／重试、属性分配、日志 Enabled() 短路处理、优雅关闭。
references/breaking-changes.md	审查现有代码中的弃用调用、重命名的语义约定，以及近期 SDK／contrib 版本中移除的 API。
references/compile-time-instrumentation.md	使用 otelc 进行零代码编译时埋点：使用模式（otelc go build、工具依赖、toolexec 替代方案）、子命令、支持的库、规则来源／优先级，以及通过 otel.instrumentation.go 固定版本。

进行升级审查时，最后务必采用安全的本地验证流程（go mod tidy -diff、 go build ./... 和 go test ./...）。针对可随时丢弃的本地接收器测试导出器 URL 或重试配置的变更，绝不要使用部署端点。

模块版本管理——添加依赖前请先阅读

opentelemetry-go 分为独立管理版本的模块组。它们不会共用同一个版本号。误以为它们共用版本号，是导致构建失败和版本频繁变动的最常见原因：

模块组	示例模块	版本系列
稳定版（追踪、指标、日志 API／SDK）	go.opentelemetry.io/otel、otel/sdk、otel/trace、otel/metric、otel/log、otel/sdk/log、OTLP 追踪／指标导出器	v1.x（例如 v1.47.0；日志 API／SDK 于 v1.47.0 加入）
日志导出器和测试辅助工具	otel/exporters/otlp/otlplog/otlploghttp、.../otlploggrpc、otel/exporters/stdout/stdoutlog、otel/log/logtest、otel/sdk/log/logtest	v0.x（独立的较低版本系列，例如 v0.23.0）
Contrib 埋点	contrib/instrumentation/net/http/otelhttp、.../otelgrpc	v0.x（独立版本系列，例如 v0.72.0）
Contrib 日志桥接	contrib/bridges/otelslog、otelzap、otellogrus、otellogr	v0.x

注意陷阱： 将每个模块都固定到核心版本（例如 go get go.opentelemetry.io/otel/exporters/otlp/otlplog/[email protected]） 会失败——日志导出器、日志测试辅助工具和桥接模块都没有 v1.x 标签。手动挑选并反复猜测各个 @vX 版本，正是应该避免的版本折腾。

请改为这样做——为每个模块添加 @latest，让 Go 解析兼容的版本组合：

go get go.opentelemetry.io/otel@latest go.opentelemetry.io/otel/sdk@latest
# logs (API/SDK are v1.x; log exporters stay on a v0.x line — do NOT force the core version):
go get go.opentelemetry.io/otel/log@latest go.opentelemetry.io/otel/sdk/log@latest \
       go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp@latest
# contrib (instrumentation and bridges each resolve to their own v0.x line):
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@latest \
       go.opentelemetry.io/contrib/bridges/otelslog@latest
go mod tidy && go build ./...

如果需要精确版本，请从各模块组自己的源获取其标签 （见下文）——绝不要根据另一组的版本推断某一组的版本。

事实来源

如需了解 YAML 架构详情，请获取 otel-declarative-config 技能中列出的上游来源。 如需了解 Go 特定信息：

信息	获取方式
最新的 go.opentelemetry.io/otel 核心版本	gh api repos/open-telemetry/opentelemetry-go/releases/latest -q '.tag_name'
最新的 go.opentelemetry.io/contrib 版本	gh api repos/open-telemetry/opentelemetry-go-contrib/releases/latest -q '.tag_name'
最新的 otelconf 模块标签	使用下表下方按版本排序的标签命令
最新的 Go semconv 包	在选定核心版本的 CHANGELOG 中搜索 Add the go.opentelemetry.io/otel/semconv/；不要根据上游语义约定版本推断包的可用性。离线时：otel v1.47.0 中的 semconv/v1.43.0，已于 2026-10-25 验证（记录：otel-semantic-conventions 技能的 references/sdk-semconv-packages.md）。
otel-go CHANGELOG	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go/main/CHANGELOG.md
otel-go-contrib CHANGELOG	WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go-contrib/main/CHANGELOG.md

gh api repos/open-telemetry/opentelemetry-go-contrib/git/matching-refs/tags/otelconf -q '.[].ref' | sort -V | tail -1

交叉引用

• 架构级信息：otel-declarative-config 技能（与语言无关的 YAML 架构来源）。
• 跨语言 SDK 版本选择：otel-sdk-versions 技能。
• 语义约定查询：otel-semantic-conventions 技能。