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 转义。

安全注意事项

1. 目标端必须在应用转义之前验证输入名称。
2. 必须验证转义方案以防止注入攻击。
3. allow-utf-8 方案仅在生产者和消费者都支持 UTF-8 名称时才允许使用。