OpenTelemetry-Go 贡献指南深度解读:从开发流程、函数式配置模式到接口演进与自可观测性设计
OpenTelemetry-Go 贡献指南深度解读:从开发流程、函数式配置模式到接口演进与自可观测性设计
本文以 CRI-O 仓库中 vendored 的 vendor/go.opentelemetry.io/otel/CONTRIBUTING.md 为主体,系统讲解 OpenTelemetry Go 官方实现(opentelemetry-go)的协作开发规范与核心设计模式:包括 make 驱动的构建/校验流程、config + Option 函数式配置模式、稳定接口的演进纪律、测试与依赖管理要求,以及 SDK 自可观测性与实验性功能的开发范式。CRI-O 通过 go.mod 依赖 go.opentelemetry.io/otel v1.46.0 及其 sdk、trace、metric、exporters/otlp/otlptrace/otlptracegrpc 等模块,本文末尾将结合 CRI-O 的 internal/opentelemetry/tracing_config.go 与 cmd/crio/main.go 印证这些模式在真实项目中的落地形态,读者读完后既能上手参与贡献,也能理解一个成熟遥测库内部的工程纪律。
一、这份指南管什么:面向谁、覆盖哪些主题
opentelemetry-go 是 OpenTelemetry 官方 Go 语言实现,提供 Trace、Metrics、Logs 三大信号的 API 与 SDK(信号状态见 vendor/go.opentelemetry.io/otel/README.md:Traces/Metrics 已稳定、Logs 为 Beta)。其贡献指南除介绍社区沟通渠道外,主体内容包含四大类技术规范:
- 开发与构建流程:
make目标体系、代码生成文件的管理、拼写检查等; - 设计原则:能力优先于结构合规,遵循语言习语;
- 代码风格与模式:
config + Option函数式选项、接口稳定性、内部包边界、context 取消语义、测试规范; - 可观测性(Observability)与实验性功能:SDK 自我观测的最佳实践,以及如何在稳定模块中渐进引入新特性。
二、开发与构建流程:make 目标体系
2.1 获取源码的两种方式
文档给出两种克隆方式:
go get -d go.opentelemetry.io/otel
(此命令可能打印 build constraints exclude all Go files 之类的警告,直接忽略即可。)该命令会把项目放到 ${GOPATH}/src/go.opentelemetry.io/otel。也可以直接用 git:
git clone https://github.com/open-telemetry/opentelemetry-go
注意:git clone 并不使用 go.opentelemetry.io/otel 这个名字——这个名字本质上是供 go get 理解的模块路径重定向,git 本身并不认识它。克隆后项目以 opentelemetry-go 为名出现在当前目录。
2.2 测试与预提交检查
- 运行测试请使用
make test而不是裸go test; - 仓库中检入了一批生成文件,为保证它们与源码同步,运行
make(或make precommit,precommit是默认目标); precommit目标还会修复代码格式并检查 go module 文件的状态;- 另有
codespell目标用于检查常见拼写错误,它默认不执行,可手动make codespell——该目标会在venv中创建虚拟环境并安装codespell; make verify-readmes用于校验各包 README 文件是否存在(详见后文文档规范)。
判断一切是否就绪的标准很朴素:运行完 make precommit 后执行 git status,若输出 nothing to commit, working tree clean,说明代码已格式化、生成文件已更新、模块状态正常。
三、Pull Request 协作流程
3.1 提交 PR 的操作序列
在 GitHub 上 fork 项目后,将 fork 添加为远端并开分支开发:
git remote add <YOUR_FORK> git@github.com:<YOUR_GITHUB_USERNAME>/opentelemetry-go
git checkout -b <YOUR_BRANCH_NAME>
# 编辑文件
# 更新 changelog
make precommit
git add -p
git commit
git push <YOUR_FORK> <YOUR_BRANCH_NAME>
随后向主仓库发起 PR,并把 PR 编号补进你在 CHANGELOG.md 中添加的条目。文档明确要求:
- 避免 rebase 与 force-push,重写历史会让代码评审难以追踪迭代;所有 PR 在合并到
main时都会被 squash 为单个提交; - 若 PR 尚不适合评审,在标题加
[WIP]、标记work-in-progress,或直接在 GitHub 上标记为 draft; - 确保 CLA 已签署、CI 保持绿色。
3.2 合并标准:何时算“可合并”
一个 PR 满足以下条件即视为 ready to merge:
- 收到 两个合格审批(qualified approvals)[^1];该要求不通过自动化强制执行,需由执行合并的 maintainer 人工校验:
- 至少一个合格审批须来自与作者不同公司的 Approver/Maintainer;
- 已经过充分讨论且达成共识的变更只需一个合格审批,讨论与结论需链接到 PR;
- 琐碎变更(错别字、非实质性外观修改、文档更正或更新、依赖升级等)[^2] 只需一个合格审批;
- 所有反馈均已解决:PR 评论与建议全部处理;状态为 “Request changes” 的 review 已被回应(可由提出反对的 reviewer 重新给出不同状态的 review,或在问题解决后由 Maintainer 驳回原 review);无法在作者与 reviewer 之间解决的评论,可在每周 SIG 会议上提交给社区 Approvers/Maintainers 仲裁;
- 实质性变更会清空既有 Approve 状态,除非审批者明确声明其审批跨变更持续有效;
- PR 分支与合并目标基线保持同步(建议配置允许 maintainer 直接更新分支以避免阻塞);
- PR 至少开放一个工作日供评审;琐碎变更无需等待一天,可由单个 Maintainer 批准后合并;
- 所有必需的 GitHub workflows 均已通过;
- 紧急修复可破例,但须在 Maintainer 之间积极沟通。
[^1]: 合格审批指来自 OpenTelemetry Go Approver 或 Maintainer 的 “Approve” 状态 review。 [^2]: 琐碎变更包括:错别字修正、非实质性外观修改、文档更正或更新、依赖更新等。
四、设计哲学:Focus on Capabilities, Not Structure Compliance
opentelemetry-go 与其他 OpenTelemetry 客户端一样遵循 OpenTelemetry 规范,文档特别建议通读规范中的 Library Guidelines(库开发指引)。核心立场是:
OpenTelemetry 是一个演进中的规范——需求与用例是清晰的,但满足这些用例的手段并不清晰。
因此贡献者应当交付符合规范的功能与行为,而接口与结构可以灵活。项目宁可让贡献遵循语言习语,也不强行贴合规范中的特定 API 名称或参数模式。对 Go 而言,这意味着:只要能满足规范能力,用 Go 社区惯用的写法去表达,好过逐字照搬规范里的结构。
五、Go 配置模式:config 结构体 + Option 接口 + With* 函数
这是指南中最具工程复用价值的部分。当一个复杂类型 T 的实例化函数需要支持可变量参数时,Go 强类型系统会限制函数设计的自由度。opentelemetry-go 落地了如下统一方案。
5.1 config 结构体
配置应放在名为 config 的 struct 中(若包内存在多个 config,则以该配置所作用的类型名作为前缀):
// config contains configuration options for a thing.
type config struct {
// options ...
}
config通常不需要在包外使用,应保持未导出;但如果预期用户会构建自定义选项,则config应导出,并在其文档中说明用户如何扩展配置;- 内部
config不得跨包共享——一个包的config不应被另一个包直接使用;唯一例外是 API 包:基础 API 的 config(如go.opentelemetry.io/otel/trace.TracerConfig、go.opentelemetry.io/otel/metric.InstrumentConfig)设计上就是要被 SDK 消费的,因此必须导出; - 导出
config时须维护前向与后向兼容:不应导出字段,而应通过方法访问; - 通常附带一个
newConfig函数(命名同规则),负责设置默认值、遍历应用所有选项:
// newConfig returns an appropriately configured config.
func newConfig(options ...Option) config {
// Set default values for config.
config := config{/* […] */}
for _, option := range options {
config = option.apply(config)
}
// Perform any validation here.
return config
}
若还需校验选项值,newConfig 可以返回 error,交由实例化函数处理或向用户传播。由于设计目标是不让用户直接操作 config,newConfig 同样应保持未导出。
5.2 Option 接口
为设置 config 中的选项值,使用对应的 Option 接口类型:
type Option interface {
apply(config) config
}
关键设计点:
apply方法保持未导出,确保不会被外部使用;同时接口因此被“封死”(sealed),用户难以自行实现该接口;apply应返回传入 config 的修改后副本,而非传指针——这样避免 config 被分配到堆上;- 接口的命名前缀与对应
config保持一致(如有)。
5.3 选项函数:With* / Without*
config 的每个可配置选项都必须配套:一个未导出的 Option 接口实现 + 一个导出的配置函数包装该实现。包装函数以 With* 为前缀(布尔选项的特殊情况用 Without*),签名如下:
func With*(…) Option { … }
布尔选项:区分“默认 false,With* 置 true”与“默认 true,Without* 置 false”两种形态。
type defaultFalseOption bool
func (o defaultFalseOption) apply(c config) config {
c.Bool = bool(o)
return c
}
// WithOption sets a T to have an option included.
func WithOption() Option {
return defaultFalseOption(true)
}
type defaultTrueOption bool
func (o defaultTrueOption) apply(c config) config {
c.Bool = bool(o)
return c
}
// WithoutOption sets a T to have Bool option excluded.
func WithoutOption() Option {
return defaultTrueOption(false)
}
声明类型选项:选项实现体是一个携带值字段的 struct。
type myTypeOption struct {
MyType MyType
}
func (o myTypeOption) apply(c config) config {
c.MyType = o.MyType
return c
}
// WithMyType sets T to have include MyType.
func WithMyType(t MyType) Option {
return myTypeOption{t}
}
函数式选项:利用具名函数类型 + 方法,代码最紧凑。
type optionFunc func(config) config
func (fn optionFunc) apply(c config) config {
return fn(c)
}
// WithMyType sets t as MyType.
func WithMyType(t MyType) Option {
return optionFunc(func(c config) config {
c.MyType = t
return c
})
}
5.4 实例化函数
使用该模式配置实例化函数 NewT:
func NewT(options ...Option) T {…}
必需的参数可以声明在可变参数 options 之前。
5.5 处理配置重叠(Dealing with Overlap)
当多个复杂 struct 共享部分配置又各有专属配置时,可抽取公共 config,用 Option 接口处理选项并集。文档给出了动物(Dog/Bird)示例:
// config holds options for all animals.
type config struct {
Weight float64
Color string
MaxAltitude float64
}
// DogOption apply Dog specific options.
type DogOption interface {
applyDog(config) config
}
// BirdOption apply Bird specific options.
type BirdOption interface {
applyBird(config) config
}
// Option apply options for all animals.
type Option interface {
BirdOption
DogOption
}
type weightOption float64
func (o weightOption) applyDog(c config) config {
c.Weight = float64(o)
return c
}
func (o weightOption) applyBird(c config) config {
c.Weight = float64(o)
return c
}
func WithWeight(w float64) Option { return weightOption(w) }
type furColorOption string
func (o furColorOption) applyDog(c config) config {
c.Color = string(o)
return c
}
func WithFurColor(c string) DogOption { return furColorOption(c) }
type maxAltitudeOption float64
func (o maxAltitudeOption) applyBird(c config) config {
c.MaxAltitude = float64(o)
return c
}
func WithMaxAltitude(a float64) BirdOption { return maxAltitudeOption(a) }
func NewDog(name string, o ...DogOption) Dog {…}
func NewBird(name string, o ...BirdOption) Bird {…}
公共选项(WithWeight)同时实现两个子接口的 apply;专有选项只实现各自接口,从而在“复用公共配置”与“隔离专有选项”之间取得平衡。
5.6 源码印证:trace/config.go 的真实实现
这套模式并非纸上谈兵——opentelemetry-go 自身就是它的实践者。看 vendor/go.opentelemetry.io/otel/trace/config.go:
// TracerConfig is a group of options for a Tracer.
type TracerConfig struct {
instrumentationVersion string
schemaURL string
attrs attribute.Set
}
// NewTracerConfig applies all the options to a returned TracerConfig.
func NewTracerConfig(options ...TracerOption) TracerConfig {
var config TracerConfig
for _, option := range options {
if _, ok := option.(experimentalOption); ok {
continue
}
config = option.apply(config)
}
return config
}
// TracerOption applies an option to a TracerConfig.
type TracerOption interface {
apply(TracerConfig) TracerConfig
}
可以清楚看到指南的落地形态:config 被命名为 TracerConfig(导出、字段私有、方法访问);Option 被命名为 TracerOption(apply 未导出,接口封死);newConfig 被命名为 NewTracerConfig。特别值得注意的是其中对 experimentalOption 的类型断言——它对应指南后文“实验性选项”一节,稳定 API 在应用选项前会跳过带 Experimental() 方法的实验选项,防止误用导致 panic。
5.7 跨项目印证:CRI-O 的配置与初始化
同样的函数式配置哲学也渗透到了 CRI-O 自身的配置层。CRI-O 的 OpenTelemetry 相关配置集中在 pkg/config/config.go 的 TracingConfig:
// TracingConfig specifies all necessary configuration for opentelemetry trace exports.
type TracingConfig struct {
// EnableTracing can be used to globally enable or disable tracing support
EnableTracing bool `toml:"enable_tracing"`
// TracingEndpoint is the address on which the grpc tracing collector server will listen.
TracingEndpoint string `toml:"tracing_endpoint"`
// TracingSamplingRatePerMillion is the number of samples to collect per million spans. Set to 1000000 to always sample.
// Defaults to 0.
TracingSamplingRatePerMillion int `toml:"tracing_sampling_rate_per_million"`
}
默认值在 pkg/config/config.go 中可见:TracingEndpoint 默认 127.0.0.1:4317、TracingSamplingRatePerMillion 默认 0、EnableTracing 默认 false。而真正初始化 TracerProvider 的逻辑在 internal/opentelemetry/tracing_config.go,它使用 OTLP/gRPC 导出器、resource.NewWithAttributes 构造资源属性(service.name=crio、hostname、PID)、按采样率选择 NeverSample 或 TraceIDRatioBased 采样器、BatchSpanProcessor 批量导出,并设置 TraceContext + Baggage 组合传播器——调用点位于 cmd/crio/main.go(config.EnableTracing 为真时调用 opentelemetry.InitTracing,将 otelgrpc.Option 注入 gRPC server 的 StatsHandler),并在优雅退出时调用 tp.Shutdown(ctx) 冲刷导出器。这是指南“Shutdown 应由 provider 的 Shutdown 方法处理”一条的工程实例。
六、接口设计、稳定性与演进
6.1 自文档化的参数命名
为便于他人理解代码,所有导出接口类型的方法参数都应在合适位置命名清晰,让方法签名“自解释”。
6.2 接口稳定性
凡在文档中包含以下警告的导出稳定接口,允许在 minor release 中追加新方法:
Warning: methods may be added to this interface in minor releases.
这类接口由 OpenTelemetry 规范定义,会随规范演进。除此之外,稳定接口一律禁止修改。
6.3 如何修改规范定义的接口
当 API 必须变更时:在 API 变更前一个 release 先更新 SDK,加入新方法,使旧 SDK 能在新 API 之下无缝工作。若应用混用了不兼容版本的 SDK 与新 API,编译时会直接失败(fail to compile),把问题暴露在编译期而非运行期。
6.4 为什么不能用 v2 API 演进接口
项目曾探索用 API 的 v2 版本来修改接口,结论是:无法引入一个能与 v1 API 无缝协作的 v2。典型问题场景是:库升级到了 v2 而应用仍停留在 v1,结果完全不产生任何遥测数据(静默失效)。细节记录在 opentelemetry-go issue #3920(“Use a V2 API to evolve interfaces”)。
6.5 如何修改其他(非规范)接口
若某接口需要新功能却不能改动它,必须通过追加一个额外接口来实现——可以是针对该功能的最小接口,也可以是原接口的超集。
最小接口示例:想给 Exporter 加 Close 方法,新增 Closer:
type Exporter interface {
Export()
}
type Closer interface {
Close()
}
调用方现在可以断言传入值是否同时满足新接口:
func caller(e Exporter) {
/* ... */
if c, ok := e.(Closer); ok {
c.Close()
}
/* ... */
}
超集类型示例:
type ClosingExporter struct {
Exporter
Close()
}
超集做法适合“行为必须与原类型耦合、以统一类型传给新函数”的场景;但因为耦合,它限制了新功能的适用范围——若其他接口也需要该功能,就必须为每个接口复制超集模式。因此优先采用定义特定功能的最小接口。
七、测试规范
- 每个功能都必须有测试覆盖;性能关键的功能还应配套 benchmark;
- 新增性能关键功能的 PR 应在描述中附
go test -bench输出; - 修改性能关键功能的 PR 应附
benchstat对比输出; - 允许使用
testify断言库(尽管 Go Test Comments 认为它不够地道); - 测试绝不能泄漏 goroutine;
- 用于验证无竞态条件的测试,名称中应包含
ConcurrentSafe字样;带此字样的顶层测试会在test-concurrent-safeCI 任务中被反复运行多次以提高发现并发问题的概率(子测试不受此规则约束,除非该术语出现在其根名称中)。
八、依赖管理与版本兼容
项目使用 Go Modules 管理依赖:所有模块以 go.mod 显式列出直接与间接依赖,保证依赖图清晰;go.sum 随仓库提交,用于校验下载模块的完整性、防篡改。
- 依赖更新由自动化工具(dependabot、renovatebot)管理,确保依赖保持最新安全补丁与特性并经过评审后才合并;
- 若要主动改动某个依赖,应通过 PR 更新
go.mod并附变更说明; - 依赖不按环境分区(development/staging/production 不做区分);只有发布模块中显式包含的依赖经过了与发布代码协同的测试验证,不承诺其他依赖的兼容性;
- 更详细的兼容性策略见仓库中的 vendor/go.opentelemetry.io/otel/VERSIONING.md。
九、文档与注释规范
- 每个(非 internal、非 test 的)包都必须使用 Go Doc Comments 进行文档化,最好放在
doc.go文件中; - 优先使用 Examples(可测试示例)代替 Go doc 注释里的代码片段;
- 本地搭建 Go 文档站点:
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite
go.opentelemetry.io/otel/metric被视为文档化的范例包;- README 要求:每个(非 internal、非 test、非文档目录的)包必须包含
README.md,至少含标题与 pkg.go.dev 徽章;README 不应重复 Go doc 注释;可用make verify-readmes校验。
十、Internal 包边界:单模块作用域
internal 包的使用应限定在单个模块内:子模块绝不应导入父模块的 internal 包——否则会形成模块耦合,用户只升级父模块不升级子模块时,一旦 internal API 变更就会升级失败(参见 issue #3548)。
两个已知例外:
go.opentelemetry.io/otel/internal/global:管理整个 opentelemetry-go 的全局状态,必须保持单一包以确保全局状态唯一;go.opentelemetry.io/otel/internal/baggage:提供放入context.Context中的值,需要被go.opentelemetry.io/otel/baggage与go.opentelemetry.io/otel/bridge/opentracing识别,同时保持私有。
若多个模块间存在重复代码,应把该代码做成 Go 模板放在 go.opentelemetry.io/otel/internal/shared,再用 gotmpl 渲染到目标位置(参考 PR #4404)。
十一、context 取消语义
OpenTelemetry API 实现必须忽略记录遥测值时传入 context 的取消状态(如启动 span、记录测量、发出日志):记录方法完成时不应返回描述“context 已取消”的错误,也不应中止任何工作。
两条边界:
- 若规范为该方法定义了超时机制,则可用 context 取消实现超时,但必须文档化该行为;否则超时由调用方处理,而非实现方;
- 遥测管道的停止由调用 provider 的
Shutdown方法负责,不应使用用户传入的 context; - 但在非直接记录的路径上(如导出遥测、强制 flush、关闭信号 provider),context 取消应当被尊重——所有代表用户 context 执行的工作都应可被取消。
十二、SDK 自可观测性(Observability)最佳实践
SDK 组件自身应被插桩,让运维人员能观测遥测管道本身的健康与性能,在问题影响业务应用前发现隐患。该能力目前为实验性。
12.1 环境变量激活
默认关闭,通过 OTEL_GO_X_OBSERVABILITY 环境变量启用,遵循 SDK 既有的实验特性模式。组件用统一模式检查:
import "go.opentelemetry.io/otel/*/internal/x"
if x.Observability.Enabled() {
// Initialize observability metrics
}
该模式的实际实现可参考 vendor/go.opentelemetry.io/otel/sdk/internal/x/features.go——Observability 是一个功能开关(feature flag),环境变量值大小写不敏感地等于 "true"(如 "True"、"TRUE")即启用;同一文件中还定义了 OTEL_GO_X_RESOURCE、OTEL_GO_X_PER_SERIES_START_TIMESTAMPS 等同类实验开关。
12.2 封装(Encapsulation)
插桩代码应封装在独立 struct(如 instrumentation)中,不要混入被插桩组件:
type SDKComponent struct {
inst *instrumentation
}
type instrumentation struct {
inflight otelconv.SDKComponentInflight
exported otelconv.SDKComponentExported
}
避免把指标字段直接散落在 SDKComponent 字段中(文档明确标注 ❌ Avoid this pattern)。插桩代码不应臃肿化被插桩代码,应放在独立文件,若复杂或可复用则放独立包。
12.3 初始化
初始化应显式、无副作用、局部于相关组件,避免依赖全局或隐式副作用。把初始化封装进构造函数,明确所有权与作用域:
func NewSDKComponent(config Config) (*SDKComponent, error) {
inst, err := newInstrumentation()
if err != nil {
return nil, err
}
return &SDKComponent{inst: inst}, nil
}
func newInstrumentation() (*instrumentation, error) {
if !x.Observability.Enabled() {
return nil, nil
}
meter := otel.GetMeterProvider().Meter(
"<component-package-name>",
metric.WithInstrumentationVersion(sdk.Version()),
metric.WithSchemaURL(semconv.SchemaURL),
)
inst := &instrumentation{}
var err, e error
inst.inflight, e = otelconv.NewSDKComponentInflight(meter)
err = errors.Join(err, e)
inst.exported, e = otelconv.NewSDKComponentExported(meter)
err = errors.Join(err, e)
return inst, err
}
(文档同时展示了 ❌ 反例:在 initObservability 之类的方法里隐式初始化、依赖方法调用时机。)
12.4 性能:禁用时零开销
可观测性关闭或 instrument 未启用时,应几乎没有开销——把昂贵的属性构造放在 Enabled 检查之后:
func (e *Exporter) ExportSpans(ctx context.Context, spans []trace.ReadOnlySpan) error {
if e.inst != nil && e.inst.Enabled(ctx) {
attrs := expensiveOperation()
e.inst.recordSpanInflight(ctx, int64(len(spans)), attrs...)
}
// Export spans...
}
(❌ 反例:无条件先执行 expensiveOperation() 再在内部方法里检查 nil/Enabled。)
启用后,插桩代码路径还应优化分配与计算开销,指南给出三种具体手段:
① 用 sync.Pool 池化属性切片与选项,降低动态属性测量调用中的分配:
var (
attrPool = sync.Pool{
New: func() any {
// Pre-allocate common capacity
knownCap := 8 // Adjust based on expected usage
s := make([]attribute.KeyValue, 0, knownCap)
// Return a pointer to avoid extra allocation on Put().
return &s
},
}
addOptPool = &sync.Pool{
New: func() any {
const n = 1 // WithAttributeSet
o := make([]metric.AddOption, 0, n)
// Return a pointer to avoid extra allocation on Put().
return &o
},
}
)
func (i *instrumentation) record(ctx context.Context, value int64, baseAttrs ...attribute.KeyValue) {
if !i.counter.Enabled(ctx) {
return
}
attrs := attrPool.Get().(*[]attribute.KeyValue)
defer func() {
clear(*attrs) // Clear references to strings/etc to let GC collect them.
*attrs = (*attrs)[:0] // Reset.
attrPool.Put(attrs)
}()
*attrs = append(*attrs, baseAttrs...)
*attrs = append(*attrs, semconv.OTelComponentName("exporter-1"))
addOpt := addOptPool.Get().(*[]metric.AddOption)
defer func() {
clear(*addOpt)
*addOpt = (*addOpt)[:0]
addOptPool.Put(addOpt)
}()
set := attribute.NewSet(*attrs...)
*addOpt = append(*addOpt, metric.WithAttributeSet(set))
i.counter.Add(ctx, value, *addOpt...)
}
池化在“池中对象数量多、体积足够大、且被反复使用”时收益最大,能摊薄分配与同步成本;池的作用域应尽可能宽以最大化效率,同时保证正确性。
② 缓存常用属性集:编译期可知的静态属性集可预计算并缓存:
type spanLiveSetKey struct {
sampled bool
}
var spanLiveSetCache = map[spanLiveSetKey]attribute.Set{
{true}: attribute.NewSet(
otelconv.SDKSpanLive{}.AttrSpanSamplingResult(
otelconv.SpanSamplingResultRecordAndSample,
),
),
{false}: attribute.NewSet(
otelconv.SDKSpanLive{}.AttrSpanSamplingResult(
otelconv.SpanSamplingResultRecordOnly,
),
),
}
func spanLiveSet(sampled bool) attribute.Set {
key := spanLiveSetKey{sampled: sampled}
return spanLiveSetCache[key]
}
③ 基准测试:引入或重构插桩时必须提供 benchmark,展示启用/禁用两种场景下的 allocs/op、B/op、ns/op:
func BenchmarkExportSpans(b *testing.B) {
scenarios := []struct {
name string
obsEnabled bool
}{
{"ObsDisabled", false},
{"ObsEnabled", true},
}
for _, scenario := range scenarios {
b.Run(scenario.name, func(b *testing.B) {
b.Setenv(
"OTEL_GO_X_OBSERVABILITY",
strconv.FormatBool(scenario.obsEnabled),
)
exporter := NewExporter()
spans := generateTestSpans(100)
b.ResetTimer()
b.ReportAllocs()
for i := 0; i < b.N; i++ {
_ = exporter.ExportSpans(context.Background(), spans)
}
})
}
}
12.5 错误处理与健壮性
错误应尽量回报给调用者,部分失败应尽可能优雅处理:
func newInstrumentation() (*instrumentation, error) {
if !x.Observability.Enabled() {
return nil, nil
}
m := otel.GetMeterProvider().Meter(/* initialize meter */)
counter, err := otelconv.NewSDKComponentCounter(m)
// Use the partially initialized counter if available.
i := &instrumentation{counter: counter}
// Return any error to the caller.
return i, err
}
(❌ 反例:把错误丢给 otel.Handle(err),或在计数器已部分初始化时返回 nil。)只有被插桩组件确实无法把错误报告给用户时,才允许交给 otel.Handle。
12.6 上下文传播
可观测性测量必须拿到正确的 context(尤其对 trace exemplars 与分布式上下文而言):
func (e *Exporter) ExportSpans(ctx context.Context, spans []trace.ReadOnlySpan) error {
// Use the provided context for observability measurements
if e.inst.Enabled(ctx) {
e.inst.recordSpanExportStarted(ctx, len(spans))
}
err := e.doExport(ctx, spans)
if e.inst.Enabled(ctx) {
if err != nil {
e.inst.recordSpanExportFailed(ctx, len(spans), err)
} else {
e.inst.recordSpanExportSucceeded(ctx, len(spans))
}
}
return err
}
(❌ 反例:用 context.Background() 记录测量,切断传播链。)
12.7 语义约定合规与组件标识
所有自观测指标应遵循 OpenTelemetry 的 SDK metrics 语义约定,并优先使用语义约定便捷包 otelconv。组件类型与命名遵循约定:
- 若组件不属于语义约定中的知名类型,用包路径作用域类型作为稳定标识,如
"go.opentelemetry.io/otel/sdk/trace.Span"(❌ 不要用"trace-span"这类随意命名); - 组件名应是该组件实例的稳定唯一标识,必要时用全局计数器保证唯一:
// Unique 0-based ID counter for component instances.
var componentIDCounter atomic.Int64
// nextID returns the next unique ID for a component.
func nextID() int64 {
return componentIDCounter.Add(1) - 1
}
// componentName returns a unique name for the component instance.
func componentName() attribute.KeyValue {
id := nextID()
name := fmt.Sprintf("%s/%d", componentType, id)
return semconv.OTelComponentName(name)
}
组件 ID 需可在测试中重置以保证确定性:若测试与被测组件在不同包(<component package>_test 包名),应使用生成的 counter internal 包管理计数器。
12.8 自观测测试
使用确定性测试与隔离状态:
func TestObservability(t *testing.T) {
// Restore state after test to ensure this does not affect other tests.
prev := otel.GetMeterProvider()
t.Cleanup(func() { otel.SetMeterProvider(prev) })
// Isolate the meter provider for deterministic testing
reader := metric.NewManualReader()
meterProvider := metric.NewMeterProvider(metric.WithReader(reader))
otel.SetMeterProvider(meterProvider)
// Use t.Setenv to ensure environment variable is restored after test.
t.Setenv("OTEL_GO_X_OBSERVABILITY", "true")
// Reset component ID counter to ensure deterministic component names.
componentIDCounter.Store(0)
/* ... test code ... */
}
测试顺序不应影响结果;任何全局状态(如组件 ID 计数器)都应在测试间重置。
十三、实验性功能:如何在稳定模块中渐进开发
为支持规范中仍在演进的特性,项目采用以下模式在不向稳定模块新增公共产物的前提下落地:
| 场景 | 实现方式 |
|---|---|
| 无 API 变更的行为变化(如 exemplar 采集、标识符自动生成) | 置于 /internal/x 包,通过 OTEL_GO_X_ 前缀环境变量启用;特性必须在 /internal/x 包的 README.md 中说明 |
| 需要 SDK 接口新方法 | 在实验模块(如 go.opentelemetry.io/otel/sdk/x)定义新接口;SDK 用类型断言(不导入不稳定包)检查类型是否实现;SDK 不得依赖实验模块 |
| 新 struct / 函数 / 接口 | 放入实验模块(如 go.opentelemetry.io/otel/sdk/x) |
| 新信号(如稳定前的 Logs)与组件(如 bridge) | 托管在新的不稳定模块(如 go.opentelemetry.io/otel/log),包名用稳定后的最终名(不带 /x),以 v0.x.y 版本发布表明未稳定 |
| API/SDK 函数的实验性选项 | 在实验模块实现;返回类型必须嵌入稳定选项类型并带 Experimental() 方法防止 API panic;SDK 用类型断言识别 |
实验性 Options 示例:
type myOption struct {
// Embed the stable option type.
metric.InstrumentOption
value string
}
// Experimental prevents the API from panicking when the option is used.
func (o myOption) Experimental() {}
// The SDK can use type assertions to use this function.
func (o myOption) Value() string { return o.value }
func WithMyOption(value string) metric.InstrumentOption {
return myOption{value: value}
}
不支持的实验形式(当前稳定接口上不允许):API 接口上的实验方法、API 或 SDK 导出结构体上的实验字段。这些场景必要时可用 fork 或长期分支做原型。
回顾 vendor/go.opentelemetry.io/otel/trace/config.go 的 NewTracerConfig,其中对 experimentalOption 的 ok 断言正是本节的运行时落地:稳定 API 在应用选项时静默跳过实验选项,避免不兼容行为。
十四、审批与维护角色机制
项目采用 Approver / Maintainer / Triager 的角色分层(社区通用 membership 机制):PR 合并至少需要一个来自不同公司的合格审批,冲突可在每周 SIG 会议上仲裁,紧急修复可在 Maintainer 间沟通后破例合并。这部分属于社区治理范畴,技术贡献者主要需要记住两点:合格审批的标准与 [WIP]/draft 标记 的协作礼仪(详见第三节)。
结语
这份贡献指南的价值早已超出“如何提 PR”本身:config + Option 函数式选项、封死的 Option 接口、稳定接口的最小增量演进、ConcurrentSafe 测试命名、OTEL_GO_X_ 实验功能门控,共同构成了一套可供任何 Go 库复制的工程范式。CRI-O 仓库既是这套规范的消费者(go.mod 依赖 otel v1.46.0,internal/opentelemetry/tracing_config.go 实际使用其 TracerProvider、OTLP 导出器与传播器),也是函数式配置哲学的实践者(pkg/config/config.go 的 TracingConfig 与 TOML 映射)。如果你计划向 opentelemetry-go 提交代码,或正在设计一个需要长期保持 API 稳定的 Go 库,这份指南就是最直接的参考蓝本——完整原文与配套开发工具(Makefile、CI 配置)都在仓库的 vendor/go.opentelemetry.io/otel 目录下可查。