模板參考

Prometheus 支援在告警的註解（annotation）和標籤（label）中以及提供的控制檯頁面中使用模板。模板能夠對本地資料庫執行查詢、迴圈遍歷資料、使用條件判斷、格式化資料等。Prometheus 模板語言基於 Go 模板系統。

資料結構

處理時間序列資料的主要資料結構是樣本（sample），定義為

type sample struct {
  Labels map[string]string
  Value  interface{}
}

樣本的指標名稱編碼在 Labels 對映（map）中特殊的 __name__ 標籤裡。

[]sample 表示樣本列表。

Go 中的 interface{} 類似於 C 中的 void 指標。

函式

除了 Go 模板提供的預設函式之外，Prometheus 還提供了能在模板中更輕鬆處理查詢結果的函式。

如果函式用於管道中，管道值將作為最後一個引數傳遞。

查詢

名稱	引數	返回	備註
query	查詢字串	[]sample	查詢資料庫，不支援返回範圍向量（range vector）。
first	[]sample	sample	等同於 `index a 0`
label	label, sample	string	等同於 `index sample.Labels label`
value	sample	interface{}	等同於 `sample.Value`
sortByLabel	label, []samples	[]sample	按給定的標籤對樣本進行排序。該排序是穩定的（stable）。

first、label 和 value 旨在讓查詢結果能夠輕鬆在管道中使用。

數字

名稱	引數	返回	備註
humanize	數字或字串	string	使用指標字首將數字轉換為更具可讀性的格式。
humanize1024	數字或字串	string	類似於 `humanize`，但使用 1024 作為基數，而不是 1000。
humanizeDuration	數字或字串	string	將以秒為單位的持續時間轉換為更具可讀性的格式。
humanizePercentage	數字或字串	string	將比例值轉換為百分比（100的分數）。
humanizeTimestamp	數字或字串	string	將以秒為單位的 Unix 時間戳轉換為更具可讀性的格式。
toTime	數字或字串	*time.Time	將以秒為單位的 Unix 時間戳轉換為 time.Time。
toDuration	數字或字串	*time.Duration	將以秒為單位的持續時間轉換為 time.Duration。
now	無	float64	返回評估模板時的 Unix 時間戳（以秒為單位）。

人性化（humanizing）函式旨在產生適合人類閱讀的合理輸出，且不保證在不同的 Prometheus 版本之間返回相同的結果。

字串

名稱	引數	返回	備註
title	string	string	cases.Title ，將每個單詞的首字母大寫。
toUpper	string	string	strings.ToUpper ，將所有字元轉換為大寫。
toLower	string	string	strings.ToLower ，將所有字元轉換為小寫。
stripPort	string	string	net.SplitHostPort ，將字串拆分為主機和埠，然後僅返回主機。
match	pattern, text	布林值	regexp.MatchString 測試未錨定的正則表示式匹配。
reReplaceAll	pattern, replacement, text	string	Regexp.ReplaceAllString 正則表示式替換，未錨定。
graphLink	expr	string	返回表示式在表示式瀏覽器中圖表（graph）檢視的路徑。
tableLink	expr	string	返回表示式在表示式瀏覽器中表格（"Table"）檢視的路徑。
parseDuration	string	float	將持續時間字串（例如 "1h"）解析為其表示的秒數。
stripDomain	string	string	刪除 FQDN 的域名部分。保留埠不變。
urlQueryEscape	string	string	url.QueryEscape 對字串進行轉義，使其可以安全地放入 URL 查詢中。

其他

名稱	引數	返回	備註
args	[]interface{}	map[string]interface{}	這會將物件列表轉換為一個鍵為 arg0、arg1 等的對映（map）。旨在允許將多個引數傳遞給模板。
tmpl	string, []interface{}	無	類似於內建的 `template`，但允許使用非字面量作為模板名稱。請注意，結果被假定為安全的，不會自動進行轉義。僅在控制檯中可用。
safeHtml	string	string	將字串標記為不需要自動轉義的 HTML。
externalURL	無	string	Prometheus 可從外部訪問的外部 URL。
pathPrefix	無	string	用於控制檯模板中的外部 URL 路徑。

模板型別差異

每種型別的模板都提供不同的資訊，可用於使模板引數化，並且還有一些其他差異。

告警欄位模板

.Value、.Labels、.ExternalLabels 和 .ExternalURL 分別包含告警值、告警標籤、全域性配置的外部標籤以及外部 URL（使用 --web.external-url 配置）。為了方便起見，它們還分別作為 $value、$labels、$externalLabels 和 $externalURL 變數暴露。

控制檯模板

控制檯暴露在 /consoles/ 上，並源自 -web.console.templates 標誌所指向的目錄。

控制檯模板使用 html/template 進行渲染，該引擎提供了自動轉義。要繞過自動轉義，請使用 safe* 函式。,

URL 引數在 .Params 中以對映（map）形式可用。要訪問具有相同名稱的多個 URL 引數，.RawParams 是每個引數的列表值的對映。URL 路徑在 .Path 中可用，不包括 /consoles/ 字首。全域性配置的外部標籤在 .ExternalLabels 中可用。這四個引數也都有方便的變數：$rawParams、$params、$path 和 $externalLabels。

控制檯還可以訪問透過 -web.console.libraries 標誌指向的目錄中的 *.lib 檔案中定義的所有具有 {{define "templateName"}}...{{end}} 的模板。由於這是一個共享名稱空間，請注意避免與其他使用者發生衝突。以 prom、_prom 和 __ 開頭的模板名稱保留給 Prometheus 使用，上述列出的函式也是如此。

本頁內容