Prometheus 中的 UTF-8
簡介
在 Prometheus 3.0 之前的版本中，要求指標和標籤名稱必須遵守一組嚴格的字元要求。在 Prometheus 3.0 中，所有 UTF-8 字串都是有效的名稱，但生態系統的其他部分仍需要進行一些手動更改，才能引入包含任意 UTF-8 字元的名稱。
在某些情況下，使用者可能希望強制執行舊版字元集，這可能是為了與較舊版本的 Prometheus 或其他尚不支援 UTF-8 的抓取器相容。
本文件將引導您瞭解 UTF-8 過渡的詳細資訊。
Go 插樁
目前，由官方 Prometheus client_golang 庫 建立的指標預設接受 UTF-8 名稱。
以前，文件建議使用者重寫 model.NameValidationScheme 的值，以便預設選擇舊版校驗。該布林值現在已被廢棄，且應始終設定為 UTF8Validation。如果需要強制執行舊版校驗，應由各個實現呼叫相應的校驗 API 來完成，這不再是客戶端庫的功能。
在其他語言中進行插樁
其他客戶端庫可能尚未支援 UTF-8，並且可能需要特殊的處理或配置。請檢視您所使用的庫的文件。
在抓取期間配置名稱校驗
預設情況下，Prometheus 3.0 接受所有 UTF-8 字串作為有效的指標和標籤名稱。您可以針對被抓取的目標覆蓋此行為，並拒絕不符合舊版字元集的名稱。
此選項可以在 Prometheus YAML 檔案中進行全域性設定
global:
metric_name_validation_scheme: legacy也可以針對每個抓取配置（scrape_config）進行設定
scrape_configs:
- job_name: prometheus
metric_name_validation_scheme: legacy抓取配置中的設定會覆蓋全域性設定。如果設定了抓取配置校驗但未設定轉義方案，則轉義方案將從校驗方案中推斷。這允許使用者在抓取配置中僅設定 metric_name_validation_scheme，而無需同時指定 metric_name_escaping_scheme。
用於 UTF-8 轉義的抓取內容協商
在抓取時，抓取系統 必須 在 Accept 請求頭中傳遞 escaping=allow-utf-8，才能獲取 UTF-8 名稱。如果抓取目標沒有檢測到此請求頭，它將自動使用下劃線替換將 UTF-8 名稱轉換為與舊版相容的名稱。
如果需要，Prometheus 和相容的抓取系統也可以透過將 escaping 頭部設定為不同的值來請求特定的轉義方法。
underscores：預設：將不符合舊版規範的字元轉換為下劃線。dots：類似於 UnderscoreEscaping，區別在於點（.）會被轉換為_dot_，而原本存在的下劃線會被轉換為__。這允許對包含點的簡單指標名稱進行往返（round-tripping）無損轉換。values：此模式會在名稱前加上U__，並將所有無效字元替換為包裹在下劃線中的 Unicode 值。單個下劃線會被替換為雙下劃線。此模式允許在舊版 Prometheus 中對 UTF-8 名稱進行完整的往返（round-tripping）無損轉換。
在內容協商中宣告支援 UTF-8 表示 Prometheus 有能力 接收 UTF-8 字元，但這並不要求指標名稱必須包含以前不支援的字元。宣告支援 UTF-8 的 Accept 請求頭也不要求指標生產者必須在他們那一側停用名稱轉換。具體的名稱轉換策略由指標生產者自行決定。唯一的要求是，當 Prometheus 請求除 allow-utf-8 之外的其他轉義方案時，生產者要按照所請求的方式轉換名稱。
遠端寫入 2.0
Remote Write 2.0 在 Prometheus 3.0 中會自動接受所有 UTF-8 名稱。在 Remote Write 2.0 中無法強制執行舊版字元集校驗。
OTLP 指標
預設情況下，Prometheus 3.0 中的 OTLP 接收器仍會將所有名稱規範化為 Prometheus 格式。您可以在 Prometheus 配置的 otlp 部分進行如下更改
otlp:
# Ingest OTLP data keeping UTF-8 characters in metric/label names.
translation_strategy: NoTranslation
請注意，如果不追加型別（type）和單位（unit）字尾，如果存在兩個名稱相同但型別或單位不同的指標，這些指標將在 Prometheus 中發生衝突。一旦 Prometheus 原生支援型別和單位元資料，這個問題就會迎刃而解。
有關更多詳細資訊，請參閱 OpenTelemetry 指南。
查詢
在 PromQL 中查詢具有 UTF-8 名稱的指標將需要略有不同的語法。
經典的查詢語法仍適用於與舊版相容的名稱
my_metric{}
但 UTF-8 名稱必須用引號括起來並且移到大括號內
{"my.metric"}
如果標籤名稱包含與舊版不相容的字元，也必須用引號括起來
{"metric.name", "my.label.name"="bar"}
指標名稱可以出現在大括號內的任何位置，但在風格上，首選將其作為第一項。