UTF-8 指标和标签名称转义方案
摘要
本文档规定了 Prometheus 在为包含传统字符集（a-zA-Z0-9_:）之外字符的指标和标签名称生成文本展示时所使用的不同转义方案。这些方案在抓取过程中通过 Accept 和 Content-Type 头部的 escaping 参数进行协商。
引言
Prometheus 支持多种转义方案，用于处理文本展示中包含传统字符集（a-zA-Z0-9_:）之外字符的指标和标签名称。转义方案在抓取过程中进行协商，并影响指标生产者应如何格式化其指标名称。
转义方案
无转义 (allow-utf-8)
头部值: escaping=allow-utf-8
行为:
- 指标和标签名称必须是有效的 UTF-8 字符串。
- 当名称在展示格式中出现在双引号内时，
\、\n和"必须用反斜杠转义。 - 当名称在展示格式中未加引号时，
\和\n必须用反斜杠转义。 - 此方案仅在生产者和消费者都支持 UTF-8 名称时使用。
下划线转义 (underscores)
头部值: escaping=underscores
行为:
- 任何不在传统字符集（a-zA-Z0-9_:）中的字符必须替换为下划线。
- 第一个字符必须是字母、下划线或冒号。
- 后续字符必须是字母、数字、下划线或冒号。
- 示例：
metric.name/with/slashes变为metric_name_with_slashes。
点号转义 (dots)
头部值: escaping=dots
行为:
- 点号 (.) 必须替换为
_dot_。 - 现有的下划线必须替换为双下划线 (
__)。 - 其他非传统字符必须替换为单个下划线。
- 第一个字符必须是字母、下划线或冒号。
- 后续字符必须是字母、数字、下划线或冒号。
- 示例：
metric.name.with.dots变为metric_dot_name_dot_with_dot_dots。
值编码转义 (values)
头部值: escaping=values
行为:
- 名称必须以
U__为前缀。 - 任何不属于传统字符集（a-zA-Z0-9_:）的字符必须替换为其十六进制 Unicode 码点，并用下划线包围。
- 单个下划线必须替换为双下划线。
- 示例：
metric.name变为U__metric_2E_name（其中 2E 是 '.' 的十六进制 Unicode 码点）。
默认行为
如果在 Accept 头部中未指定转义方案，则应使用 underscores 转义。
安全考量
- 目标在应用转义前必须验证输入名称。
- 必须验证转义方案以防止注入攻击。
allow-utf-8方案仅在生产者和消费者都支持 UTF-8 名称时使用。