UTF-8 指标和标签名称转义方案
摘要
本文档规定了 Prometheus 在为包含传统字符集之外字符的指标和标签名称生成文本暴露格式时使用的不同转义方案。这些方案在抓取过程中通过 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 名称时才可使用。