OTLP Prometheus Translator 使用指南：Go 中 OTLP 指标与 Prometheus 命名互转的完整实践

OTLP Prometheus Translator 使用指南Go 中 OTLP 指标与 Prometheus 命名互转的完整实践【免费下载链接】substrateAgent Substrate: the core system项目地址: https://gitcode.com/GitHub_Trending/substrate7/substrate导读本文围绕本仓库Agent Substrate中 vendored 的github.com/prometheus/otlptranslator库展开系统讲解如何将 OpenTelemetry ProtocolOTLP指标名、标签名与单位转换为 Prometheus 兼容格式。读完本文你将掌握MetricNamer、LabelNamer、UnitNamer三个核心构建器的用法、四种翻译策略的取舍以及_total/_ratio/单位后缀的生成规则能够直接在自己的 OTLP → Prometheus 采集链路中落地使用。该库位于 vendor/github.com/prometheus/otlptranslator是 Prometheus 与 OpenTelemetry 生态共用的内部库README 明确说明其对外部使用不作稳定性承诺遵循 OpenTelemetry 官方的 Prometheus 兼容规范。本仓库将其作为第三方依赖 vendored 引入用于指标命名转换场景仓库观测链路相关文档可见 docs/metrics/registry/substrate.yaml 与 docs/observability.md。为什么需要 OTLP → Prometheus 名称翻译OTLP 指标与 Prometheus 的命名规范存在根本差异OTLP 指标名使用点号分隔如http.server.request.duration并附带独立单位字段如sPrometheus 传统命名只允许[a-zA-Z0-9:_]字符且要求将基础单位直接嵌入指标名如http_server_request_duration_secondsOTLP 标签名允许.、、$等字符而 Prometheus 标签名只允许[a-zA-Z0-9_]。otlptranslator正是为了解决这套命名差异而生的纯 Go 库核心能力如下对应 README Features指标名与标签翻译将 OTLP 指标名、属性名转换为 Prometheus 兼容格式单位处理将 OTLP 单位UCUM 表示法翻译为 Prometheus 单位约定类型感知后缀按指标类型可选追加_total、_ratio命名空间支持可配置前缀UTF-8 支持可选择传统 Prometheus 兼容命名[a-zA-Z0-9:_]或原样透传翻译策略配置用一组标准字符串选择翻译策略。安装库使用标准 Go 模块方式引入go get github.com/prometheus/otlptranslator本仓库通过 Go modules 的 vendor 机制将其固定在 vendor/github.com/prometheus/otlptranslator 目录仓库go.mod声明依赖包源码共 9 个 Go 文件metric_namer.go、label_namer.go、unit_namer.go、strategy.go、metric_type.go、constants.go、strconv.go以及包文档 doc.go。快速开始README 提供了开箱即用的最小示例完整继承如下package main import ( fmt github.com/prometheus/otlptranslator ) func main() { // Create a metric namer using traditional Prometheus name translation, with suffixes added and UTF-8 disallowed. strategy : otlptranslator.UnderscoreEscapingWithSuffixes namer : otlptranslator.NewMetricNamer(myapp, strategy) // Translate OTLP metric to Prometheus format metric : otlptranslator.Metric{ Name: http.server.request.duration, Unit: s, Type: otlptranslator.MetricTypeHistogram, } fmt.Println(namer.Build(metric)) // Output: myapp_http_server_request_duration_seconds // Translate label names labelNamer : otlptranslator.LabelNamer{UTF8Allowed: false} fmt.Println(labelNamer.Build(http.method)) // Output: http_method }这段代码揭示了库的两个核心入口NewMetricNamer(namespace, strategy)工厂函数根据 strategy.go 中定义的策略自动推导WithMetricSuffixes与UTF8Allowed两个布尔字段WithMetricSuffixes: strategy.ShouldAddSuffixes()、UTF8Allowed: !strategy.ShouldEscape()LabelNamer{UTF8Allowed: false}标签翻译器仅需一个字段。Metric结构体见 metric_namer.go携带指标三要素Name、Unit、Type其中Type使用 metric_type.go 中的MetricType枚举取值包括枚举值含义MetricTypeUnknown未知类型MetricTypeNonMonotonicCounter非单调递增计数器delta 计数器MetricTypeMonotonicCounter单调递增计数器cumulative 计数器MetricTypeGauge仪表指标MetricTypeHistogram直方图MetricTypeExponentialHistogram指数直方图MetricTypeSummary摘要指标翻译策略四种标准选项strategy.go 通过TranslationStrategyOption字符串类型提供了四种标准策略策略常量转义ShouldEscape追加后缀ShouldAddSuffixes适用场景UnderscoreEscapingWithSuffixestruetrue默认推荐完整 Prometheus 风格兼容非法字符转下划线并追加单位/类型后缀UnderscoreEscapingWithoutSuffixestruefalse仅转义非法字符不追加任何后缀NoUTF8EscapingWithSuffixesfalsetrue保留原名但按规则追加单位与类型后缀NoTranslationfalsefalse实验性完全不做翻译直接使用 OTLP 原生名称关于NoTranslation的警告该策略存在显著已知风险README 与源码注释均有明确说明——在纯 YAML 场景告警、规则、仪表盘、自动扩缩容配置中使用 PromQL 时体验受损可能引发序列碰撞series collision轻则产生 OOOOut Of Order错误重则产生静默损坏的时间序列。例如可能同时摄入单位为seconds的foo.bar序列与单位为milliseconds的foo.bar序列造成数据语义混乱。因此NoTranslation目前不应在生产系统使用。注意 README 配置示例中的写法为otlpTranslator.NoTranslation这是文档笔误正确常量名为otlptranslator.NoTranslation。MetricNamer指标名翻译深度解析MetricNamermetric_namer.go是核心构建器字段如下type MetricNamer struct { Namespace string // 命名空间前缀 WithMetricSuffixes bool // 是否追加单位/类型后缀 UTF8Allowed bool // 是否允许 UTF-8false 时执行传统转义 }Build(metric)的行为按配置分三条路径见 metric_namer.goUTF8Allowed true原样返回仅要求合法 UTF-8UTF8Allowed false且WithMetricSuffixes true走normalizeName完整规范化UTF8Allowed false且WithMetricSuffixes false仅做非法字符转义与数字开头前缀处理。指标名转义规则合法指标名字符为[a-zA-Z0-9:]isValidCompliantMetricChar见 metric_namer.go。完整规范化时指标名会先按非法字符切分为 token再以_连接——该过程同时会把连续多个下划线折叠为单个下划线这是 OTel → Prometheus 规范的明确要求。若规范化结果以数字开头则自动加_前缀。类型感知后缀_total 与 _ratioMetricTypeMonotonicCounter追加_total如requests.count→requests_count_total先移除名称中已存在的totaltoken 再统一追加避免total_total重复单位1且MetricTypeGauge追加_ratio如cpu.utilization→cpu_utilization_ratio。源码注释指出部分 OTel receiver 错误地使用单位1表示对象计数器因此_ratio仅对 Gauge 追加——从数学角度计数器不应是比率。单位后缀单位后缀由unitMap与perUnitMap两张映射表驱动完整定义见 metric_namer.go主单位映射unitMapOTLP 单位Prometheus 单位类别d/h/min/s/ms/us/nsdays / hours / minutes / seconds / milliseconds / microseconds / nanoseconds时间By/KiBy/MiBy/GiBy/TiBybytes / kibibytes / mebibytes / gibibytes / tibibytes二进制字节KBy/MBy/GBy/TBykilobytes / megabytes / gigabytes / terabytes十进制字节m/V/A/J/W/gmeters / volts / amperes / joules / watts / gramsSI 单位Cel/Hzcelsius / hertz其他1空字符串无量纲特殊%percent特殊per 单位映射perUnitMap用于分母s→second、m→minute、h→hour、d→day、w→week、mo→month、y→year注意此处为单数形式与主单位的复数形式区分。addUnitTokensmetric_namer.go负责把单位后缀追加进 token 列表并做了防重复处理若 token 中已存在相同单位词则不再追加per_单独出现时整体移除。完整示例继承 READMEnamer : otlptranslator.MetricNamer{WithMetricSuffixes: true, UTF8Allowed: false} // Counter gets _total suffix counter : otlptranslator.Metric{ Name: requests.count, Unit: 1, Type: otlptranslator.MetricTypeMonotonicCounter, } fmt.Println(namer.Build(counter)) // requests_count_total // Gauge with unit conversion gauge : otlptranslator.Metric{ Name: memory.usage, Unit: By, Type: otlptranslator.MetricTypeGauge, } fmt.Println(namer.Build(gauge)) // memory_usage_bytes // Dimensionless gauge gets _ratio suffix ratio : otlptranslator.Metric{ Name: cpu.utilization, Unit: 1, Type: otlptranslator.MetricTypeGauge, } fmt.Println(namer.Build(ratio)) // cpu_utilization_ratio错误处理buildCompliantMetricName内建了防御性校验metric_namer.go规范化结果为空时返回错误normalization for metric %q resulted in empty name规范化结果全部为下划线时返回错误normalization for metric %q resulted in invalid name %q并清空结果。因此在生产代码中应始终检查Build返回的error。LabelNamer标签名翻译深度解析LabelNamerlabel_namer.go字段如下type LabelNamer struct { UTF8Allowed bool // Deprecated: 未来版本将移除。开启后对以 _ 开头非 __的标签前置 key UnderscoreLabelSanitization bool // 保留连续多个下划线违反 OTel→Prometheus 规范仅为兼容旧系统而存在 PreserveMultipleUnderscores bool }翻译规则Build见 label_namer.go非法字符替换为下划线合法标签字符仅[a-zA-Z0-9]见 strconv.go数字开头前置key_如123invalid→key_123invalid保留__双下划线保留标签以__开头且以__结尾的标签视为保留标签如__name__整体保留原样isReservedLabel见 strconv.goUTF8Allowed true时原样返回但纯下划线标签会被拒绝。默认行为下多个连续下划线会被折叠为单个sanitizeLabelName与collapseMultipleUnderscores见 strconv.go。README 示例注意_private一条的说明见下文labelNamer : otlptranslator.LabelNamer{UTF8Allowed: false} labelNamer.Build(http.method) // http_method labelNamer.Build(123invalid) // key_123invalid labelNamer.Build(_private) // key_private需开启 UnderscoreLabelSanitization labelNamer.Build(__reserved__) // __reserved__ (preserved) labelNamer.Build(labelwith$symbols) // label_with_symbols重要勘误以源码为准README 中_private→key_private的输出与当前源码默认配置不符。从 label_namer.go 的实现看key_前缀仅在两种情况下追加标签以数字开头无条件或开启了已废弃的UnderscoreLabelSanitization且标签以单下划线开头。因此默认配置下_private会原样保留为_private要得到key_private需显式设置UnderscoreLabelSanitization: true。由于该选项已标记 Deprecated建议新代码避免依赖此行为。UnitNamer单位翻译深度解析UnitNamerunit_namer.go仅有一个字段UTF8AllowedBuild流程unit_namer.go按/拆分主单位与 per 单位buildUnitSuffixesunit_namer.go依次查unitMap与perUnitMap查不到则原样保留unitMapGetOrDefault/perUnitMapGetOrDefaultper 单位统一加per_前缀组合后清理首尾下划线。README 示例unitNamer : otlptranslator.UnitNamer{UTF8Allowed: false} unitNamer.Build(s) // seconds unitNamer.Build(By) // bytes unitNamer.Build(requests/s) // requests_per_second unitNamer.Build(1) // (dimensionless)注意含{}的单位如{requests}会被跳过处理避免把语义化注释当成字面单位cleanUpUnitunit_namer.go还会在转义后折叠连续下划线并去除前导_确保输出符合model.LabelNameRE。配置选项综合示例README 给出了三种典型配置组合完整继承如下// Prometheus-compliant mode - supports [a-zA-Z0-9:_] compliantNamer : otlptranslator.MetricNamer{UTF8Allowed: false, WithMetricSuffixes: true} // Transparent pass-through mode, aka NoTranslation utf8Namer : otlptranslator.MetricNamer{UTF8Allowed: true, WithMetricSuffixes: false} utf8Namer otlptranslator.NewMetricNamer(, otlptranslator.NoTranslation) // With namespace and suffixes productionNamer : otlptranslator.MetricNamer{ Namespace: myservice, WithMetricSuffixes: true, UTF8Allowed: false, }三种模式的工程定位Prometheus 兼容模式推荐UTF8Allowed: false, WithMetricSuffixes: true与UnderscoreEscapingWithSuffixes策略等价用于标准的 Prometheus 远程写入/抓取链路透传模式与NoTranslation策略等价保留 OTLP 原生名称仅限实验场景生产模式加命名空间前缀防止多服务指标名冲突是服务端聚合场景的常用做法。命名空间的处理在 metric_namer.go 中实现完整规范化时 namespace 直接作为首个 token 前置简单转义模式下 namespace 同样会先做字符清洗再以_拼接。规格细节Exemplar、Scope 与 Target Info 常量constants.go 定义了与 OTel → Prometheus 兼容规范直接相关的保留标签常量在实现完整翻译链路时非常有用常量值用途ExemplarTraceIDKeytrace_idPrometheus exemplar 中存储 trace ID 的键ExemplarSpanIDKeyspan_idPrometheus exemplar 中存储 span ID 的键ScopeNameLabelKeyotel_scope_name标识产生指标的 OTel instrumentation scope 名称ScopeVersionLabelKeyotel_scope_version标识 scope 版本TargetInfoMetricNametarget_info用 Prometheus 格式保留 resource 属性的指标名源自 OpenMetrics 的 target metadata 机制这些常量解释了为什么__reserved__这类双下划线标签必须保留Prometheus 与 OpenMetrics 生态正是通过__前缀标签传递 trace/scope/target 元信息的。源码映射速查需求查阅文件指标名构建与规范化metric_namer.go标签名清洗与保留标签逻辑label_namer.go、strconv.go单位拆分与映射unit_namer.go四种翻译策略定义strategy.go指标类型枚举metric_type.goExemplar/Scope/Target 常量constants.go使用建议与边界说明默认选UnderscoreEscapingWithSuffixes这是 OTLP → Prometheus 的默认翻译选项能保证指标名落入[a-zA-Z0-9:_]合法字符集单位语义通过后缀显式保留单位后缀避免重复库内置了 token 去重已含单位词则不再追加可安全处理requests_total之类名称警惕NoTranslation实验性选项存在序列碰撞与 PromQL 体验问题生产环境禁用注意构建错误空名称、纯下划线名称、纯下划线标签都会返回 error务必检查返回值库的稳定性声明该库定位为 Prometheus 与 OpenTelemetry 的内部共享库README 明确说明对外部使用不提供稳定性保证升级依赖时需关注 API 变动如UnderscoreLabelSanitization已标记废弃待移除。结语otlptranslator以三个轻量构建器MetricNamer、LabelNamer、UnitNamer覆盖了 OTLP 指标进入 Prometheus 世界前的全部命名转换需求字符转义、单位翻译、类型后缀、命名空间与翻译策略代码量精简但边界处理严谨保留标签、token 去重、空名防御。对于任何需要打通 OTel 采集与 Prometheus 存储的 Go 项目这套 API 都是开箱即用的可靠选择。【免费下载链接】substrateAgent Substrate: the core system项目地址: https://gitcode.com/GitHub_Trending/substrate7/substrate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考