UTF-8 指標和標籤名稱轉義方案
摘要
本文件詳細說明了 Prometheus 在為包含傳統字元集之外字元的指標和標籤名稱生成文字展示時，所使用的不同轉義方案。這些方案在抓取期間透過 Accept 和 Content-Type 請求頭中的 escaping 引數進行協商。
簡介
Prometheus 支援多種轉義方案，用於處理文字展示中包含傳統字元集（a-zA-Z0-9_:）之外字元的指標和標籤名稱。轉義方案在抓取期間進行協商，並會影響指標生成器格式化其指標名稱的方式。
轉義方案
不轉義 (allow-utf-8)
請求頭的值：escaping=allow-utf-8
行為:
- 指標和標籤名稱必須（MUST）是有效的 UTF-8 字串。
- 當名稱出現在展示格式的雙引號內時，
\、\n和"必須（MUST）使用反斜槓進行轉義。 - 當名稱在展示格式中未加引號時，
\和\n必須（MUST）使用反斜槓進行轉義。 - 此方案必須（MUST）僅在生成端和消費端都支援 UTF-8 名稱時使用。
下劃線轉義 (underscores)
請求頭的值：escaping=underscores
行為:
- 任何不在傳統字元集（a-zA-Z0-9_:）中的字元必須（MUST）替換為下劃線。
- 首字元必須（MUST）是字母、下劃線或冒號。
- 後續字元必須（MUST）是字母、數字、下劃線或冒號。
- 示例：
metric.name/with/slashes變為metric_name_with_slashes。
點號轉義 (dots)
請求頭的值：escaping=dots
行為:
- 點號（.）必須（MUST）替換為
_dot_。 - 已有的下劃線必須（MUST）替換為雙下劃線（
__）。 - 其他非傳統字元必須（MUST）替換為單下劃線。
- 首字元必須（MUST）是字母、下劃線或冒號。
- 後續字元必須（MUST）是字母、數字、下劃線或冒號。
- 示例：
metric.name.with.dots變為metric_dot_name_dot_with_dot_dots。
值編碼轉義 (values)
請求頭的值：escaping=values
行為:
- 名稱必須（MUST）以
U__為字首。 - 每個不屬於傳統字元集（a-zA-Z0-9_:）的字元必須（MUST）替換為其十六進位制的 Unicode 碼點，並用下劃線包圍。
- 單下劃線必須（MUST）替換為雙下劃線。
- 示例：
metric.name變為U__metric_2E_name（其中 2E 是“.”的十六進位制 Unicode 碼點）。
預設行為
如果在 Accept 請求頭中未指定任何轉義方案，則應當（SHOULD）使用 underscores 轉義。
安全考慮
- 目標在應用轉義之前必須（MUST）驗證輸入的名稱。
- 必須（MUST）對轉義方案進行驗證，以防止注入攻擊。
allow-utf-8方案必須（MUST）僅在生成端和消費端都支援 UTF-8 名稱時使用。