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 Metrics，V1/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），本文聚焦 Elasticsearch（OpenSearch 对照表见 opensearch-metrics.md，内容与 ES 完全一致）。这些表格并非手写维护，而是由 scripts/utils/metrics-md.py 从指标定义中自动生成的：脚本中的generate_combined_markdown_table负责产出"Combined Metrics"小节，generate_spans_markdown_table负责产出"Equivalent Metrics"小节，确保对照关系与源码始终同步。
组合指标（Combined Metrics）：V1 与 V2 完全一致
ES 写入相关的 10 个指标在 v1、v2 中名称与参数（标签）完全相同，均为N/A（即无附加标签，只有指标名本身）。这意味着基于这些指标构建的写入监控面板、告警规则在迁移后无需任何修改即可继续工作。
| V1 Metric | V1 Parameters | V2 Metric | V2 Parameters |
|---|---|---|---|
| jaeger_bulk_index_attempts_total | N/A | jaeger_bulk_index_attempts_total | N/A |
| jaeger_bulk_index_errors_total | N/A | jaeger_bulk_index_errors_total | N/A |
| jaeger_bulk_index_inserts_total | N/A | jaeger_bulk_index_inserts_total | N/A |
| jaeger_bulk_index_latency_err | N/A | jaeger_bulk_index_latency_err | N/A |
| jaeger_bulk_index_latency_ok | N/A | jaeger_bulk_index_latency_ok | N/A |
| jaeger_index_create_attempts_total | N/A | jaeger_index_create_attempts_total | N/A |
| jaeger_index_create_errors_total | N/A | jaeger_index_create_errors_total | N/A |
| jaeger_index_create_inserts_total | N/A | jaeger_index_create_inserts_total | N/A |
| jaeger_index_create_latency_err | N/A | jaeger_index_create_latency_err | N/A |
| jaeger_index_create_latency_ok | N/A | jaeger_index_create_latency_ok | N/A |
指标族的统一命名模型
这 10 个指标属于两个命名族：bulk_index（批量写入）与index_create（索引创建）。每个族内都遵循固定的"attempts / inserts / errors / latency-ok / latency-err"五件套结构，其底层定义位于 internal/storage/v1/api/spanstore/spanstoremetrics/write_metrics.go：
type 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 Metric | V1 Parameters | V2 Metric | V2 Parameters |
|---|---|---|---|
| jaeger_collector_spans_rejected_total | debug, format, svc, transport | receiver_refused_spans | receiver, service_instance_id, service_name, service_version, transport |
| jaeger_build_info | build_date, revision, version | target_info | service_instance_id, service_name, service_version |
拒绝 span 计数：jaeger_collector_spans_rejected_total → receiver_refused_spans
v1 中拒绝 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_version：OTel 资源属性，标识上报实例；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_info
v1 的jaeger_build_info携带build_date（构建日期）、revision（Git 提交）、version（版本号）三个标签，用于在 Prometheus 中标识运行中的二进制版本。
v2 中该信息通过 OTel 资源属性导出为target_info，标签仅保留服务身份三要素service_instance_id、service_name、service_version。迁移后查询运行版本时，不再直接看到version/revision标签，而需要通过service_name+service_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），仅供参考
