Prometheus 中的 UTF-8 | Prometheus - Prometheus 监控系统

在 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"}

指标名称可以出现在大括号内的任何位置，但样式上建议将其作为第一个术语。

本文档是开源的。请提交 issue 或 pull request 以帮助改进它。