简介

Prometheus 3.0 之前的版本要求指标和标签名称遵守严格的字符要求。 在 Prometheus 3.0 中,所有 UTF-8 字符串都是有效的名称,但是需要对生态系统的其他部分进行一些手动更改,以引入任何带有 UTF-8 字符的名称。

在某些情况下,用户可能希望强制使用旧版字符集,可能是为了与较旧的系统或尚不支持 UTF-8 的系统兼容。

本文档将指导您了解 UTF-8 过渡的详细信息。

Go 检测

目前,由官方 Prometheus client_golang 库创建的指标默认会拒绝 UTF-8 名称。必须更改默认验证方案以允许使用 UTF-8。在通用库的未来版本中,将不再需要设置此值。

import "github.com/prometheus/common/model"

func init() {
    model.NameValidationScheme = model.UTF8Validation
}

如果用户想要强制使用旧版字符集,则可以将验证方案设置为 LegacyValidation

必须在实例化指标之前完成验证方案的设置,并且可以根据需要即时设置。

使用其他语言进行检测

其他客户端库可能具有类似的设置验证方案的要求。 请查看您正在使用的库的文档。

配置抓取期间的名称验证

默认情况下,Prometheus 3.0 接受所有 UTF-8 字符串作为有效的指标和标签名称。可以覆盖抓取目标的此行为,并拒绝不符合旧版字符集的名称。

可以在 Prometheus YAML 文件中全局设置此选项

global:
  metric_name_validation_scheme: legacy

或在每个抓取配置的基础上进行设置

scrape_configs:
  - job_name: prometheus
    metric_name_validation_scheme: legacy

抓取配置设置会覆盖全局设置。

抓取内容协商以进行 UTF-8 转义

在抓取时,抓取系统**必须**在 Accept 标头中传递 escaping=allow-utf-8,以便提供 UTF-8 名称。 如果被抓取的系统没有看到此标头,它将使用下划线替换自动将 UTF-8 名称转换为旧版兼容的名称。

如果需要,抓取系统还可以通过将 escaping 标头设置为不同的值来请求特定的转义方法。

  • underscores:默认值:将旧版无效字符转换为下划线。
  • dots:类似于 UnderscoreEscaping,不同之处在于点被转换为 _dot_,而预先存在的下划线被转换为 __。这允许对也包含点的简单指标名称进行往返处理。
  • values:此模式在名称前添加 U__,并将所有无效字符替换为 Unicode 值,并用下划线包围。单个下划线替换为双下划线。此模式允许使用旧系统完全往返 UTF-8 名称。

远程写入 2.0

远程写入 2.0 在 Prometheus 3.0 中自动接受所有 UTF-8 名称。无法使用远程写入 2.0 强制执行旧版字符集验证。

OTLP 指标

Prometheus 3.0 中的 OTLP 接收器默认仍然会将所有名称规范化为 Prometheus 格式。 您可以在 Prometheus 配置的 otlp 部分中按如下所示更改此设置

otlp:
  # Ingest OTLP data keeping UTF-8 characters in metric/label names.
  translation_strategy: NoUTF8EscapingWithSuffixes

有关更多详细信息,请参见OpenTelemetry 指南

查询

查询具有 UTF-8 名称的指标在 PromQL 中需要稍微不同的语法。

经典查询语法仍适用于旧版兼容的名称

my_metric{}

但是 UTF-8 名称必须用引号引起来**并**移入花括号

{"my.metric"}

如果标签名称包含旧版不兼容的字符,则也必须用引号引起来

{"metric.name", "my.label.name"="bar"}

指标名称可以出现在花括号内的任何位置,但是样式首选它作为第一项。

该文档是开源的。请通过提交问题或拉取请求来帮助改进它。