Prometheus 3.0 之前的版本要求指标和标签名称遵守严格的字符要求。 在 Prometheus 3.0 中,所有 UTF-8 字符串都是有效的名称,但是需要对生态系统的其他部分进行一些手动更改,以引入任何带有 UTF-8 字符的名称。
在某些情况下,用户可能希望强制使用旧版字符集,可能是为了与较旧的系统或尚不支持 UTF-8 的系统兼容。
本文档将指导您了解 UTF-8 过渡的详细信息。
目前,由官方 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
抓取配置设置会覆盖全局设置。
在抓取时,抓取系统**必须**在 Accept 标头中传递 escaping=allow-utf-8
,以便提供 UTF-8 名称。 如果被抓取的系统没有看到此标头,它将使用下划线替换自动将 UTF-8 名称转换为旧版兼容的名称。
如果需要,抓取系统还可以通过将 escaping
标头设置为不同的值来请求特定的转义方法。
underscores
:默认值:将旧版无效字符转换为下划线。dots
:类似于 UnderscoreEscaping,不同之处在于点被转换为 _dot_
,而预先存在的下划线被转换为 __
。这允许对也包含点的简单指标名称进行往返处理。values
:此模式在名称前添加 U__
,并将所有无效字符替换为 Unicode 值,并用下划线包围。单个下划线替换为双下划线。此模式允许使用旧系统完全往返 UTF-8 名称。远程写入 2.0 在 Prometheus 3.0 中自动接受所有 UTF-8 名称。无法使用远程写入 2.0 强制执行旧版字符集验证。
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"}
指标名称可以出现在花括号内的任何位置,但是样式首选它作为第一项。
该文档是开源的。请通过提交问题或拉取请求来帮助改进它。