opentelemetrySDK源码解析

opentelemetry-go/├── otel.go / version.go        # 全局 API 入口(Tracer/Meter/版本)├── trace/                      # 【API 层】链路接口定义│   ├── trace.go                #   Tracer/TracerProvider/Span 接口 + SpanContext│   ├── noop.go                 #   空实现(未注入 SDK 时用)│   ├── nonrecording.go         #   不记录的 Span(采样 Drop 时返回它)│   └── config.go               #   SpanConfig(WithAttributes 等选项)├── metric/                     # 【API 层】指标接口├── logs/  (log/)               # 【API 层】日志接口(较新)├── baggage/  propagation/      # Baggage 与传播器(W3C 实现)├── codes/  attribute/  semconv/# 枚举、属性类型、语义约定常量├── sdk/│   ├── trace/                  # 【SDK 层】★ 核心,本章主角│   ├── metric/                 # 【SDK 层】指标实现(聚合、Reader、视图)│   ├── log/                    # 【SDK 层】日志实现│   └── resource/               # Resource 检测与合并├── exporters/│   ├── otlp/otlptrace/         # OTLP 链路导出(gRPC/HTTP 两种 client)│   ├── stdout/                 # 打到控制台(调试用)│   └── ...├── internal/global/            # ★ 全局实例与"委托"机制(理解 API/SDK 解耦的关键)└── example/                    # 官方示例,读源码起步点

1. 解析 SpanConfig(kind、属性、links、时间戳)2. 生成新的 span id + 继承/生成 trace id   └─ id_generator.go(默认随机;可自定义雪花等单调 id)3. 执行采样决策 sampler.ShouldSample(SamplingParams)   ├─ Decision == Drop   │    → 返回 nonRecordingSpan(接口满足、啥也不记,业务代码无感)   └─ Decision == RecordAndSample → 继续创建真实 span4. 组装 span:属性、links、parent(来自 ctx 里的 SpanContext)5. 构造新 ctx = context.WithValue(ctx, currentSpanKey, span)6. 逐个调用 spanProcessor.OnStart(span)   ← 注意:OnStart 是同步的7. 返回 (ctx, span)

1. ended 原子标记(cas),防止重复 End → 重复 End 是 no-op2. 若 SetStatus 为 Error 且没有 exception 事件,部分版本会补记3. 截断超限数据:属性/事件/links 按 SpanLimits 裁剪(超出计数进 dropped_*_count)4. 逐个调用 spanProcessor.OnEnd(span) ← BatchSpanProcessor 从这里接手5. End 之后 SetAttributes 等方法全部变 no-op

业务 goroutine                          后台 goroutine─────────────                          ──────────────span.End()  → bsp.OnEnd(span)      → queue 满了吗?         ├─ 满:dropped++(丢弃,默认非阻塞)         └─ 未满:入队(batch 累积)                                          loop:                                            每 BatchTimeout(5s) 或攒够                                            MaxExportBatchSize(512) →                                            exportSpans(batch)                                              → exporter.ExportSpans(ctx, batch)                                              → 失败:按重试策略重试/丢弃计数Shutdown() → 停止 ticker、关闭队列、drain 剩余、最后一次 export

sdktrace.WithBatcher(exp,	sdktrace.WithMaxQueueSize(10000),	sdktrace.WithBatchTimeout(2*time.Second),	sdktrace.WithMaxExportBatchSize(1000),)

// TraceIDRatioBased:按 trace_id 前若干 bit 与阈值比较// 同一 trace_id 永远得到同一决策(确定性,这是不产生"半截链路"的根本)func(ts TraceIDRatioBased) ShouldSample(p SamplingParams) SamplingResult {	// x = traceID 的前 64bit / 2^64 → [0,1)	// x < ratio → RecordAndSample,否则 Drop}// ParentBased:看父的采样位func(ps ParentBased) ShouldSample(p SamplingParams) SamplingResult {	if 父存在 {		父 sampled → root(默认 AlwaysOn)……即"跟随父"		父未采    → remoteNotSampled/localNotSampled(默认 AlwaysOff)	}	// 无父 → root sampler}

otlptrace/├── otlptrace.go          # Client 接口 + NewExportStream 组合入口├── otlptracegrpc/        # gRPC 传输实现│   ├── options.go        #   WithEndpoint / WithTLSCredentials / WithHeaders...│   ├── client.go         #   启动 gRPC 连接、Export 调用│   └── internal.go       #   reattempt 调度(导出失败的重试节奏)├── otlptracehttp/        # HTTP/protobuf 传输实现(结构对称)└── internal/             # proto 转换:SDK 的 ReadOnlySpan → pb.Span    └── otlp/transform/   # ★ 属性/SpanContext 转 protobuf 的地方

sdktrace.WithSpanLimits(sdktrace.SpanLimits{	AttributeCountLimit:         128, // 单 Span 属性上限,默认 128	EventCountLimit:             256,	LinkCountLimit:              128,	AttributeValueLengthLimit:   -1,  // 无限制;可设字节数})

// transport.go / client.goclient := &http.Client{Transport: otelhttp.NewTransport(http.DefaultTransport)}

1. 从 req.Context() 取当前 SpanContext2. 创建 CLIENT Span(name = 请求方法+URL 路径模板)3. Inject(ctx, req.Header)         ← 03 章 4.3 手写的那行4. 真正发起 http.DefaultTransport.RoundTrip5. defer:按响应状态码设置 Span 状态、记录语义约定属性、End()

// handler.go / server.gohttp.Handle("/api", otelhttp.NewHandler(h, "api"))