Prometheus 中的 UTF-8
简介
3.0 版本之前的 Prometheus 要求指标和标签名称遵循严格的字符集要求。在 Prometheus 3.0 中，所有 UTF-8 字符串都是有效的名称，但为了在生态系统的其他部分引入包含任何 UTF-8 字符的名称，需要进行一些手动更改。
也可能存在用户希望强制执行旧版字符集的情况，例如为了与不支持 UTF-8 的旧版 Prometheus 或其他抓取器兼容。
本文档将指导您完成 UTF-8 迁移的详细信息。
Go 仪器化
目前，由官方 Prometheus client_golang 库 创建的指标默认接受 UTF-8 名称。
以前，文档建议用户覆盖 model.NameValidationScheme 的值，默认选择旧版验证。此布尔值现已弃用，应始终设置为 UTF8Validation。如果需要，旧版验证强制执行应由各个实现调用相应的验证 API 来完成，不再是库功能。
其他语言的仪器化
其他客户端库可能尚未支持 UTF-8，可能需要特殊处理或配置。请查看您正在使用的库的文档。
配置抓取过程中的名称验证
默认情况下，Prometheus 3.0 接受所有 UTF-8 字符串作为有效的指标和标签名称。您可以为抓取的 targets 覆盖此行为，并拒绝不符合旧版字符集的名称。
此选项可以在 Prometheus YAML 文件中全局设置
global:
metric_name_validation_scheme: legacy或按抓取配置设置
scrape_configs:
- job_name: prometheus
metric_name_validation_scheme: legacy抓取配置设置会覆盖全局设置。如果设置了抓取配置验证但未设置转义方案，则转义方案将从验证方案推断。这使得用户可以在抓取配置中仅设置 metric_name_validation_scheme，而不必同时指定 metric_name_escaping_scheme。
UTF-8 转义的抓取内容协商
在抓取时，抓取系统 **必须** 在 Accept 头部传递 escaping=allow-utf-8 才能提供 UTF-8 名称。如果抓取 target 未看到此头部，它将自动将 UTF-8 名称转换为兼容旧版的下划线替换。
Prometheus 和兼容的抓取系统也可以通过将 escaping 头部设置为不同的值来请求特定的转义方法（如果需要）。
underscores：默认：将旧版无效字符转换为下划线。dots：与 UnderscoreEscaping 类似，只是点被转换为_dot_，而已存在的下划线被转换为__。这允许简单包含点的指标名称进行往返。values：此模式在名称前添加U__，并将所有无效字符替换为 Unicode 值，并用下划线括起来。单个下划线被替换为双下划线。此模式允许与旧版 Prometheus 进行完整的 UTF-8 名称往返。
宣布内容协商中的 UTF-8 支持表明 Prometheus 能够 接收 UTF-8 字符，但并不要求指标名称包含以前不支持的字符。同样，表示支持 UTF-8 的 Accept 头部也不要求指标生产者在其端禁用名称转换。具体名称转换策略的选择由指标生产者决定。要求是，当 Prometheus 请求 allow-utf-8 以外的转义方案时，生产者必须按照请求的方式转换名称。
远程写入 2.0
Remote Write 2.0 在 Prometheus 3.0 中自动接受所有 UTF-8 名称。无法使用 Remote Write 2.0 强制执行旧版字符集验证。
OTLP 指标
Prometheus 3.0 中的 OTLP 接收器默认仍将所有名称规范化为 Prometheus 格式。您可以在 Prometheus 配置的 otlp 部分进行更改，如下所示：
otlp:
# Ingest OTLP data keeping UTF-8 characters in metric/label names.
translation_strategy: NoTranslation
请注意，在不附加类型和单位后缀的情况下，如果存在两个名称相同但类型或单位不同的指标，这些指标在 Prometheus 中将发生冲突。一旦 Prometheus 对类型和单位元数据具有原生支持，此问题将消失。
有关更多详细信息，请参阅 OpenTelemetry 指南。
查询
在 PromQL 中查询具有 UTF-8 名称的指标需要稍微不同的语法。
经典查询语法仍然适用于兼容旧版的名称
my_metric{}
但 UTF-8 名称必须加引号并移到花括号内
{"my.metric"}
如果标签名称包含旧版不兼容的字符，也必须加引号
{"metric.name", "my.label.name"="bar"}
指标名称可以出现在花括号内的任何位置，但风格上建议将其作为第一个术语。