
后端可观测性链路追踪【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址https://gitcode.com/GitHub_Trending/tempo1/tempo点击查看免费下载本指南以 Grafana Tempo 仓库中 vendor 的go.opentelemetry.io/otel/exporters/jaegerv1.17.0 模块文档为骨架系统讲解这一已被官方标记废弃的 Jaeger 导出器的安装方式、两类 Endpoint 配置、环境变量优先级规则、底层数据转换与上传机制并给出它在本项目Tempo中的真实调用证据与迁移建议。读完本文你将掌握该导出器从配置到源码实现的全貌并能在仍使用它的遗留系统中准确排障。重要声明该模块已废弃Deprecated。OpenTelemetry 官方自 2023 年 7 月起停止对 Jaeger Exporter 的支持Jaeger 官方也转而推荐直接使用 OTLP 上报。本文基于仓库当前 vendor 的代码v1.17.0如实讲解其设计与用法适用于仍依赖此模块的遗留环境新项目应直接使用 OTLP 导出器otlptracehttp或otlptracegrpc。模块概览与废弃背景vendor/go.opentelemetry.io/otel/exporters/jaeger/README.md是该模块的官方说明文档。它实现的是 OpenTelemetry 规范中 Jaeger span exporter 的定义一个实现了sdktrace.SpanExporter接口见 jaeger.go的组件负责把 OpenTelemetry SDK 采集到的 Span 批量转换并发送到 Jaeger 的 agent 或 collector。模块的核心设计可以用一张流程图概括OpenTelemetry SDK (TracerProvider) │ 采集 ReadOnlySpan ▼ jaeger.Exporter (jaeger.go) │ spanToThrift() 转换 jaegerBatchList() 按 Resource 分组 ▼ batchUploader 接口uploader.go ├── agentUploader → UDP / compact thrift 协议 → Jaeger Agent └── collectorUploader → HTTP POST / binary thrift 协议 → Jaeger Collector该模块在当前仓库的 vendor 目录中为v1.17.0见 vendor/modules.txt模块内还自带了 Apache Thrift 库的 vendored 副本v0.14.1与internal/gen-go下由 Thrift IDL 生成的agent、jaeger、zipkincore三类代码整个模块不依赖外部 Thrift 运行时这正是其低依赖特性的体现。需要特别指出的是废弃并非 Tempo 独有的决定。Grafana Tempo 在 v2.8 版本的发行说明中明确记录Removed the OpenTelemetry Jaeger exporter, which has been deprecated.见 docs/sources/tempo/release-notes/version-2/v2-8.md。也就是说即便是曾经在自身上报链路中使用过它的项目详见下文也已在新版本中将其移除。安装与基本使用在项目还是用该模块的时期安装方式为go get -u go.opentelemetry.io/otel/exporters/jaeger仓库中它作为间接依赖被 vendor 进项目通过modules.txt中的## explicit标记可以确认依赖图。官方文档给出的最小使用模式是用New()构造函数传入一个EndpointOption得到*jaeger.Exporter再把它挂到sdktrace.NewTracerProvider的WithBatcher上。这一模式在 dskit 的 Jaeger 集成代码中有完整体现var ep jaegerotel.EndpointOption if cfg.agentHostPort ! { ep jaegerotel.WithAgentEndpoint( jaegerotel.WithAgentHost(cfg.agentHost), jaegerotel.WithAgentPort(cfg.agentPort)) } else { ep jaegerotel.WithCollectorEndpoint( jaegerotel.WithEndpoint(cfg.jaegerEndpoint)) } exp, err : jaegerotel.New(ep)New()见 jaeger.go会依据传入的EndpointOption创建对应的 uploader并尝试从默认 Resource 中取出service.name作为兜底的服务名——如果取不到会直接返回错误。Exporter暴露三个核心方法ExportSpans(ctx, spans)把一批sdktrace.ReadOnlySpan转换后批量上传期间会监听 ctx 取消与自身 stopChjaeger.goShutdown(ctx)通过sync.Once关闭 stopCh 并释放底层连接jaeger.goMarshalLog()供日志系统序列化标识类型为jaeger。两种端点Endpoint配置方式文档明确导出器支持两条上报通路分别对应WithAgentEndpoint与WithCollectorEndpoint两个选项。Agent 端点UDP compact thriftWithAgentEndpoint见 uploader.go用于把 span 发送到本机/就近的 Jaeger Agent走UDP 协议 jaeger.thrift的 compact 序列化。默认地址为localhost:6831且默认开启自动重连解析AttemptReconnecting: true即 agent 的域名解析结果变化时会自动重新拨号。可用的子选项包括选项作用WithAgentHost(host)覆盖 agent 主机名WithAgentPort(port)覆盖 agent 端口WithLogger/WithLogr设置 agent 客户端日志二者互相覆盖WithDisableAttemptReconnecting()关闭重连解析能力WithAttemptReconnectingInterval(d)重连解析间隔默认 30sWithMaxPacketSize(size)最大 UDP 包大小底层agentClientUDP见 agent.go的实现细节值得一提它定义了与 jaeger-agent 侧同步的udpPacketMaxLength 65000与emitBatchOverhead 70两个常量发送前先序列化 span 计算字节大小把 batch 拆分成能塞进单个 UDP 数据报的多个小块EmitBatch方法agent.go单个 span 超过上限会被丢弃并报错span too large to send。UDP 通路天然是尽力而为的网络抖动时可能丢包这是选择该路径时必须接受的权衡。Collector 端点HTTP binary thriftWithCollectorEndpoint见 uploader.go把 span 直接 POST 到 Jaeger Collector 的 HTTP 接口走jaeger.thriftover HTTPbinary thrift 序列化默认端点为http://localhost:14268/api/traces。可用子选项选项作用WithEndpoint(url)覆盖 collector 完整 URLWithUsername(u)/WithPassword(p)对 collector 启用 Basic 认证WithHTTPClient(client)注入自定义*http.Client从 collectorUploader.upload 可以看到其实现serialize()用 binary thrift 协议把 batch 写入内存缓冲然后POST到 endpoint若同时配置了用户名和密码则通过req.SetBasicAuth附加认证头Content-Type固定为application/x-thrift响应状态码不在 2xx 区间会返回failed to upload traces; HTTP status code: %d错误。两种方式对比如下维度Agent 端点Collector 端点传输协议UDPHTTP POST序列化compact thriftbinary thrift默认地址localhost:6831http://localhost:14268/api/traces可靠性尽力而为可能丢包依赖 HTTP 响应确认适用场景就近部署 agent 的高吞吐场景直连 collector、跨网络上报环境变量配置与优先级规则除选项对象外文档给出 5 个可用于覆盖默认配置的环境变量且选项的优先级高于环境变量环境变量对应选项默认值OTEL_EXPORTER_JAEGER_AGENT_HOSTWithAgentHostlocalhostOTEL_EXPORTER_JAEGER_AGENT_PORTWithAgentPort6831OTEL_EXPORTER_JAEGER_ENDPOINTWithEndpointhttp://localhost:14268/api/tracesOTEL_EXPORTER_JAEGER_USERWithUsername无默认OTEL_EXPORTER_JAEGER_PASSWORDWithPassword无默认这些变量名在 env.go 中以常量形式定义。优先级链条从源码可以确认uploader.go显式传入的选项 环境变量envOr 读取 硬编码默认值envOrenv.go的实现也印证了这一点os.Getenv返回非空字符串才生效否则回落默认值。注意OTEL_EXPORTER_JAEGER_USER/PASSWORD只有在两个同时非空时才会触发 Basic 认证uploader.go。数据转换原理从 OpenTelemetry Span 到 Jaeger 模型导出器最核心的转换逻辑集中在spanToThriftjaeger.go它把一个ReadOnlySpan翻译成 Jaeger 的gen.SpanThrift 结构。关键映射如下ID 与时间128 位 TraceID 与 64 位 SpanID 均按大端序拆成TraceIdHigh/Low、SpanId父 SpanID 写入ParentSpanId时间戳统一转换为微秒UnixNano() / 1000Duration为结束减开始属性 → TagskeyValueToTagjaeger.go按类型映射——STRING→VStr、BOOL→VBool、INT64→VLong、FLOAT64→VDouble而各种 Slice 类型BOOLSLICE 等会被json.Marshal成字符串后作为VStr标签这是容易忽略的细节SpanKind 与 Status非internal的 SpanKind 写入span.kind标签codes.Ok写otel.status_codeOKcodes.Error额外写布尔标签errortrue状态描述写入otel.status_descriptionInstrumentationScope库名与版本分别写入otel.library.name、otel.library.version标签Events → Logs事件名event标签连同属性与丢弃属性计数otel.event.dropped_attributes_count组合成 Jaeger Log时间戳同样转微秒Links → ReferencesSpan Link 全部映射为FOLLOWS_FROM类型的SpanRef。分组成批由jaegerBatchListjaeger.go完成它按Resource 的等价性Equivalent()对 span 分组每组生成一个gen.Batchprocess函数jaeger.go把 Resource 中的service.name提取为Process.ServiceName不再作为普通 tag其余 Resource 属性转为Process.Tags若 span 的 Resource 没有 service.name 则回落到默认资源中的服务名。这一按服务聚合 逐包发送的设计保证了同一次ExportSpans调用里不同服务的数据也能正确归类。在 Grafana Tempo 项目中的实际使用与迁移虽然 exporter 本身来自上游 OTel 仓库但它在当前 Tempo 仓库中留下了真实的集成痕迹可作为理解其用法的活标本dskit 的 Jaeger 兼容层vendor/github.com/grafana/dskit/tracing/otel_jaeger.go 提供了一个与 Jaeger 客户端旧环境变量体系兼容的初始化层模块顶部以//nolint:staticcheck显式抑制了对废弃模块的静态检查告警。它支持JAEGER_AGENT_HOST、JAEGER_ENDPOINT、JAEGER_SAMPLER_MANAGER_HOST_PORT等传统变量otel_jaeger.go并内置了JaegerDebuggingPropagator与JaegerDebuggingSamplerotel_jaeger.go可识别Jaeger-Debug-Id头并强制对带调试 ID 的请求全量采样Tempo 的入口封装pkg/tracing/tracing.go 中的InstallOTelOrJaegerFromEnv委托给 dskit 的NewOTelOrJaegerFromEnv见 otel_jaeger.go该函数按顺序探测JAEGER_*环境变量 →OTEL_TRACES_EXPORTER/OTEL_EXPORTER_OTLP_*→ 无则关闭 tracing实现了老 Jaeger 环境变量向新 OTel 体系的平滑过渡版本演进Tempo 侧对 Jaeger 协议的接收仍然支持例如 v2.8 发行说明 记录了 jaeger receiver 指标维度名的变化但自身上报侧的 OTel Jaeger exporter 已在 v2.8 中移除v2.8 发行说明与上游废弃节奏保持一致。对仍在用本模块的读者迁移到 OTLP 的路径是官方文档明确推荐的将WithAgentEndpoint/WithCollectorEndpoint替换为go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpcgRPC或otlptracehttpHTTP并把环境变量替换为OTEL_EXPORTER_OTLP_ENDPOINT等当前仓库的 dskit 兼容层otel_jaeger.go已经演示了这类探测逻辑可以作为迁移实现的参考。小结otel/exporters/jaeger是一个设计精简、协议细节完整的 span 导出器通过WithAgentEndpointUDP compact thrift与WithCollectorEndpointHTTP binary thrift两条路径覆盖了 Jaeger 最经典的两种接入方式以选项 环境变量 默认值的三级优先级实现灵活配置并在spanToThrift中完成了 OTel 模型到 Jaeger Thrift 模型的逐字段映射。受上游 2023 年 7 月停止支持的影响该模块与 Tempo 的集成已被移除本文内容适用于仍运行旧版本Tempo v2.8 之前或自行引入该模块的环境新环境请遵循上游建议直接使用 OTLP 导出器。赞分享后端可观测性链路追踪【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址https://gitcode.com/GitHub_Trending/tempo1/tempo点击查看免费下载相关推荐OpenTelemetry Go Jaeger Exporter 实战在 BuildKit 中的配置、原理与迁移指南OpenTelemetry Go Jaeger Exporter 实战在 BuildKit 中的配置、原理与迁移指南 BuildKit 的 vendored构建工具云原生后端OpenTelemetry 与 Jaeger 数据模型转换全解Grafana Tempo 中 jaeger translator 的字段映射规则与实现原理OpenTelemetry 与 Jaeger 数据模型转换全解Grafana Tempo 中 jaeger translator 的字段映射规则与实现原理 本后端可观测性链路追踪Grafana Tempo 中的 Jaeger Receiver多协议追踪数据接入与配置实战Grafana Tempo 中的 Jaeger Receiver多协议追踪数据接入与配置实战 Jaeger Receiver 是 OpenTelemetry后端可观测性链路追踪创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考