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 名称时使用。