otel-go

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTelemetry in Go

Go 语言中的 OpenTelemetry

Entry point for OpenTelemetry mechanics in Go services. Load a reference below based on the task; each reference is self-contained.

这是 Go 服务中 OpenTelemetry 相关机制的入口文档。根据任务需求加载下方的参考文档；每个参考文档都是独立完整的。

References

参考文档

File	Use when
`references/declarative-setup.md`	Configuring the SDK via `otelconf` and YAML: providers, propagators, shutdown, env-var substitution.
`references/api.md`	Looking up import paths, global API access, tracer/meter/logger usage, attributes, propagation, log bridges (zap, slog).
`references/instrumentation-libraries.md`	Picking or wiring contrib libraries (otelhttp, otelgrpc, database, AWS, message queues, propagators, resource detectors), and writing manual instrumentation that follows semconv.
`references/performance.md`	Tuning sampling, batch processor, metric reader, exporter compression/retry, attribute allocation, log `Enabled()` short-circuiting, graceful shutdown.
`references/breaking-changes.md`	Auditing existing code for deprecated calls, renamed semantic conventions, and removed APIs across recent SDK / contrib releases.
`references/compile-time-instrumentation.md`	Zero-code, compile-time instrumentation with `otelc` : usage modes ( `otelc go build` , tool dependency, toolexec drop-in), subcommands, supported libraries, rule sources/precedence, and pinning via `otel.instrumentation.go` .

For upgrade reviews, always finish with a safe local verification path (

go mod tidy -diff

go build ./...

, and

go test ./...

). Test exporter URL or retry changes against a disposable local receiver, never a deployment endpoint.

文件	使用场景
`references/declarative-setup.md`	通过 `otelconf` 和 YAML 配置 SDK：包括 providers、propagators、关闭操作、环境变量替换。
`references/api.md`	查询导入路径、全局 API 访问、tracer/meter/logger 使用、属性、传播、日志桥接（zap、slog）。
`references/instrumentation-libraries.md`	选择或对接社区贡献库（otelhttp、otelgrpc、数据库、AWS、消息队列、propagators、资源探测器），以及编写符合 semconv 的手动 instrumentation。
`references/performance.md`	调优采样、批处理处理器、指标读取器、导出器压缩/重试、属性分配、日志 `Enabled()` 短路优化、优雅关闭。
`references/breaking-changes.md`	检查现有代码中已废弃的调用、重命名的语义约定以及近期 SDK/社区贡献版本中移除的 API。
`references/compile-time-instrumentation.md`	使用 `otelc` 实现零代码编译期 instrumentation：使用模式（ `otelc go build` 、工具依赖、toolexec 替代）、子命令、支持的库、规则来源/优先级，以及通过 `otel.instrumentation.go` 固定版本。

对于升级评审，务必完成安全的本地验证流程（

go mod tidy -diff

、

go build ./...

和

go test ./...

）。针对导出器 URL 或重试变更，应在一次性本地接收器上测试，切勿直接使用部署端点。

Module versioning — read before adding dependencies

模块版本控制 —— 添加依赖前必读

opentelemetry-go is split into independently versioned module groups. They do NOT share one version number. Assuming they do is the most common cause of broken builds and version churn:

Module group	Example modules	Version line
Stable signals (traces, metrics)	`go.opentelemetry.io/otel` , `otel/sdk` , `otel/trace` , `otel/metric` , OTLP trace/metric exporters	v1.x (e.g. v1.45.0)
Logs	`otel/log` , `otel/sdk/log` , `otel/exporters/otlp/otlplog/otlploghttp`	v0.x (separate, lower line)
Contrib instrumentation	`contrib/instrumentation/net/http/otelhttp` , `.../otelgrpc`	v0.x (separate line, e.g. v0.70.0)
Contrib log bridges	`contrib/bridges/otelslog` , `otelzap` , `otellogrus` , `otellogr`	v0.x

The trap: pinning every module to the core version (e.g.

go get go.opentelemetry.io/otel/log@v1.45.0

) fails — log and bridge modules have no v1.x tag. Hand-picking and re-guessing each

@vX

is the churn to avoid.

Do this instead — add each module with

@latest

and let Go resolve a compatible set:

bash

go get go.opentelemetry.io/otel@latest go.opentelemetry.io/otel/sdk@latest

opentelemetry-go 被划分为独立版本控制的模块组。它们并不共享同一个版本号。假设它们版本一致是导致构建失败和版本混乱的最常见原因：

模块组	示例模块	版本系列
稳定信号（追踪、指标）	`go.opentelemetry.io/otel` , `otel/sdk` , `otel/trace` , `otel/metric` , OTLP trace/metric exporters	v1.x (e.g. v1.45.0)
日志	`otel/log` , `otel/sdk/log` , `otel/exporters/otlp/otlplog/otlploghttp`	v0.x（独立的低版本系列）
社区贡献 instrumentation	`contrib/instrumentation/net/http/otelhttp` , `.../otelgrpc`	v0.x（独立版本系列，例如 v0.70.0）
社区贡献日志桥接	`contrib/bridges/otelslog` , `otelzap` , `otellogrus` , `otellogr`	v0.x

常见陷阱： 将每个模块固定为核心版本（例如

go get go.opentelemetry.io/otel/log@v1.45.0

）会失败——日志和桥接模块没有 v1.x 标签。手动挑选并反复猜测每个

@vX

版本会导致不必要的版本混乱。

正确做法 —— 使用

@latest

添加每个模块，让 Go 自动解析兼容版本集：

bash

go get go.opentelemetry.io/otel@latest go.opentelemetry.io/otel/sdk@latest

logs (separate v0.x line — do NOT force the core version):

日志（独立的 v0.x 系列——请勿强制使用核心版本）：

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):

社区贡献库（instrumentation 和桥接各自解析到对应的 v0.x 系列）：

go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@latest
go.opentelemetry.io/contrib/bridges/otelslog@latest go mod tidy && go build ./...


If exact versions are required, fetch each module group's tag from its own source
(see below) — never infer one group's version from another's.

go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@latest
go.opentelemetry.io/contrib/bridges/otelslog@latest go mod tidy && go build ./...


如果需要精确版本，请从每个模块组的官方源获取标签（见下文）——切勿从一个模块组的版本推断另一个模块组的版本。

Sources of Truth

权威信息来源

For YAML schema details, fetch the upstream sources listed in the

otel-declarative-config

skill. For Go-specific facts:

Fact	Fetch
Latest `go.opentelemetry.io/otel` core release	`gh api repos/open-telemetry/opentelemetry-go/releases/latest -q '.tag_name'`
Latest `go.opentelemetry.io/contrib` release	`gh api repos/open-telemetry/opentelemetry-go-contrib/releases/latest -q '.tag_name'`
Latest `otelconf` module tag	`gh api repos/open-telemetry/opentelemetry-go-contrib/git/matching-refs/tags/otelconf -q '.[-1].ref'`
Latest semconv package version	`gh api repos/open-telemetry/semantic-conventions/releases/latest -q '.tag_name'`
`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`

如需了解 YAML Schema 细节，请参考

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` 模块最新标签	`gh api repos/open-telemetry/opentelemetry-go-contrib/git/matching-refs/tags/otelconf -q '.[-1].ref'`
semconv 包最新版本	`gh api repos/open-telemetry/semantic-conventions/releases/latest -q '.tag_name'`
`otel-go` 更新日志	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go/main/CHANGELOG.md`
`otel-go-contrib` 更新日志	`WebFetch https://raw.githubusercontent.com/open-telemetry/opentelemetry-go-contrib/main/CHANGELOG.md`

Cross-References

交叉引用

Schema-level facts:
```
otel-declarative-config
```
skill (language-agnostic YAML schema sources).
SDK version selection across languages:
```
otel-sdk-versions
```
skill.
Semantic conventions lookup:
```
otel-semantic-conventions
```
skill.

Schema 层面信息：
```
otel-declarative-config
```
技能（语言无关的 YAML Schema 源）。
多语言 SDK 版本选择：
```
otel-sdk-versions
```
技能。
语义约定查询：
```
otel-semantic-conventions
```
技能。