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