Jaeger Elasticsearch 指标迁移对照指南V1 到 V2 的 Metric 命名与标签映射【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger本文档是 Jaeger v1 → v2 迁移系列中的 Elasticsearch 指标篇完整罗列了 Elasticsearch 存储后端在迁移前后的指标名与标签labels对照关系涵盖组合指标Combined MetricsV1/V2 名称完全一致与等价指标Equivalent Metrics名称与标签均发生变更两类并给出对应源码依据帮助监控团队在升级过程中无痛切换告警规则与 Grafana 面板。本指南以仓库内 cmd/jaeger/docs/migration/elasticsearch-metrics.md 为核心骨架结合 Elasticsearch 存储实现源码与指标生成脚本展开讲解。读者读完可掌握哪些 ES 指标在 v2 中保持不变、哪些指标被重命名并扩展了标签、以及如何在迁移后继续用统一指标名构建监控面板。为什么需要指标迁移对照表Jaeger v2 基于 OpenTelemetry Collector 重写了整体架构数据写入、接收与构建信息的埋点方式也随之变化写入路径从 v1 的internal/storage/v1演进为 v2 的internal/storage/v2但 Elasticsearch 批量写入核心仍然复用统一的写入指标模型接收路径改为标准 OTLP receiver拒绝 span 的计数指标从 Jaeger 自定义命名切换为 OTel 语义约定的receiver_refused_spans构建信息改为遵循 OpenTelemetry 资源语义的target_info标签结构也向 OTel 资源属性靠拢。仓库在 cmd/jaeger/docs/migration/ 下按存储后端分别维护了迁移对照表all-in-one-metrics.md、badger-metrics.md、cassandra-metrics.md、elasticsearch-metrics.md、opensearch-metrics.md本文聚焦 ElasticsearchOpenSearch 对照表见 opensearch-metrics.md内容与 ES 完全一致。这些表格并非手写维护而是由 scripts/utils/metrics-md.py 从指标定义中自动生成的脚本中的generate_combined_markdown_table负责产出Combined Metrics小节generate_spans_markdown_table负责产出Equivalent Metrics小节确保对照关系与源码始终同步。组合指标Combined MetricsV1 与 V2 完全一致ES 写入相关的 10 个指标在 v1、v2 中名称与参数标签完全相同均为N/A即无附加标签只有指标名本身。这意味着基于这些指标构建的写入监控面板、告警规则在迁移后无需任何修改即可继续工作。V1 MetricV1 ParametersV2 MetricV2 Parametersjaeger_bulk_index_attempts_totalN/Ajaeger_bulk_index_attempts_totalN/Ajaeger_bulk_index_errors_totalN/Ajaeger_bulk_index_errors_totalN/Ajaeger_bulk_index_inserts_totalN/Ajaeger_bulk_index_inserts_totalN/Ajaeger_bulk_index_latency_errN/Ajaeger_bulk_index_latency_errN/Ajaeger_bulk_index_latency_okN/Ajaeger_bulk_index_latency_okN/Ajaeger_index_create_attempts_totalN/Ajaeger_index_create_attempts_totalN/Ajaeger_index_create_errors_totalN/Ajaeger_index_create_errors_totalN/Ajaeger_index_create_inserts_totalN/Ajaeger_index_create_inserts_totalN/Ajaeger_index_create_latency_errN/Ajaeger_index_create_latency_errN/Ajaeger_index_create_latency_okN/Ajaeger_index_create_latency_okN/A指标族的统一命名模型这 10 个指标属于两个命名族bulk_index批量写入与index_create索引创建。每个族内都遵循固定的attempts / inserts / errors / latency-ok / latency-err五件套结构其底层定义位于 internal/storage/v1/api/spanstore/spanstoremetrics/write_metrics.gotype WriteMetrics struct { Attempts metrics.Counter metric:attempts Inserts metrics.Counter metric:inserts Errors metrics.Counter metric:errors LatencyOk metrics.Timer metric:latency-ok LatencyErr metrics.Timer metric:latency-err }其语义通过 Emit 方法 一次性确定func (t *WriteMetrics) Emit(err error, latency time.Duration) { t.Attempts.Inc(1) if err ! nil { t.LatencyErr.Record(latency) t.Errors.Inc(1) } else { t.LatencyOk.Record(latency) t.Inserts.Inc(1) } }即每次操作先递增attempts成功则记录latency-ok并递增inserts失败则记录latency-err并递增errors。因此监控时通常以errors / attempts计算失败率用latency-ok与latency-err分别观察正常与异常路径的耗时分布。bulk_index批量写入指标bulk_index族由 BulkIndexer 在写入_bulk时埋点。在 v2 的统一 ES 客户端实现 internal/storage/elasticsearch/esclient/bulk.go 中func NewBulkIndexer(client *Client, cfg BulkIndexerConfig, metricsFactory metrics.Factory, logger *zap.Logger) (*BulkIndexer, error) { b : BulkIndexer{ metrics: spanstoremetrics.NewWriter(metricsFactory, bulk_index), ... } }spanstoremetrics.NewWriter(metricsFactory, bulk_index)会将上述五件套指标统一放入bulk_index命名空间最终输出为jaeger_bulk_index_attempts_total、jaeger_bulk_index_errors_total、jaeger_bulk_index_inserts_total、jaeger_bulk_index_latency_err、jaeger_bulk_index_latency_ok。同步写入路径 internal/storage/elasticsearch/esclient/sync_bulk.go 使用相同的bulk_index命名空间因此无论采用异步批量还是同步批量指标口径完全一致。单元测试对指标行为做了精确断言见 internal/storage/elasticsearch/esclient/bulk_test.go成功场景bulk_index.inserts 1、bulk_index.errors 0只出现latency-ok计时器失败场景bulk_index.inserts 0、bulk_index.errors 1只出现latency-err计时器入队失败场景队列已满bulk_index.attempts 1、bulk_index.errors 1见 TestBulkIndexerEnqueueError。这从测试层面印证了表格中V1/V2 指标名与参数一致的结论——同一套写入指标模型在迁移前后被完整保留。index_create索引创建指标index_create族对应 Elasticsearch 索引初始化/创建如按天/按小时滚动索引的预创建操作同样沿用NewWriter(metricsFactory, index_create)的五件套模型。在迁移对照表中该族 5 个指标的 V1/V2 名称与参数也保持完全一致N/A因此索引创建相关的告警如jaeger_index_create_errors_total持续增长可以直接沿用。等价指标Equivalent Metrics名称与标签均发生变更以下 2 个指标在 v1 与 v2 中名称不同、标签集合也不同迁移时必须同步更新告警表达式与面板查询V1 MetricV1 ParametersV2 MetricV2 Parametersjaeger_collector_spans_rejected_totaldebug, format, svc, transportreceiver_refused_spansreceiver, service_instance_id, service_name, service_version, transportjaeger_build_infobuild_date, revision, versiontarget_infoservice_instance_id, service_name, service_version拒绝 span 计数jaeger_collector_spans_rejected_total → receiver_refused_spansv1 中拒绝 span 的计数由 Collector 自定义埋点jaeger_collector_spans_rejected_total上报携带标签debug调试开关、format数据格式如 jaeger/otlp、svc服务名、transport传输协议。v2 中 Jaeger 以标准 OTel Collector 组件形态运行该指标由接收器按 OpenTelemetry 语义约定上报为receiver_refused_spans标签集变为receiver接收器名称如 otlp、jaeger 等service_instance_id/service_name/service_versionOTel 资源属性标识上报实例transport传输协议标签名保留含义与 v1 一致。这一命名在 Jaeger 的监控资产中已被采用例如 monitoring/jaeger-mixin/dashboard-for-grafana.json 与生成代码 monitoring/jaeger-mixin/generate/main.go 中均使用receiver_refused_spans构建接收拒绝率的监控表达式。迁移后若需按服务维度拆分告警应改用service_name而非 v1 的svc。构建信息jaeger_build_info → target_infov1 的jaeger_build_info携带build_date构建日期、revisionGit 提交、version版本号三个标签用于在 Prometheus 中标识运行中的二进制版本。v2 中该信息通过 OTel 资源属性导出为target_info标签仅保留服务身份三要素service_instance_id、service_name、service_version。迁移后查询运行版本时不再直接看到version/revision标签而需要通过service_nameservice_version组合定位实例若面板依赖jaeger_build_info{version...}做版本告警或展示需改写为对target_info的查询。迁移落地建议写入与索引类指标零改动jaeger_bulk_index_*与jaeger_index_create_*共 10 个指标直接沿用现有面板与告警无需修改可结合errors/attempts比率与latency-err观察写入健康度。接收拒绝类指标改写将jaeger_collector_spans_rejected_total相关查询/告警替换为receiver_refused_spans并按需在标签receiver、service_name、transport上做分组与过滤。版本信息类指标改写将jaeger_build_info相关查询替换为target_info注意标签从version/revision变为service_version/service_name的差异。保持文档同步若后续指标定义发生变更可通过 scripts/utils/metrics-md.py 重新生成 elasticsearch-metrics.md 对照表确保监控团队始终拿到与源码一致的迁移依据。小结Elasticsearch 后端的指标迁移可以概括为写入路径不变、接收与元信息标准化bulk_index与index_create两个指标族的 10 个指标在 v1/v2 中名称与标签完全一致迁移成本为零而receiver_refused_spans、target_info两个 OTel 标准化指标的引入则要求监控侧同步更新查询与告警。结合 bulk.go、write_metrics.go 与 bulk_test.go 中的实现与测试可以确认这套对照关系与运行时代码保持一致可放心作为迁移核对清单使用。【免费下载链接】jaegerCNCF Jaeger, a Distributed Tracing Platform项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考