テンプレートリファレンス

Prometheus は、アラートのアノテーションとラベル、および提供されるコンソールページでテンプレートをサポートしています。テンプレートには、ローカルデータベースに対してクエリを実行したり、データを反復処理したり、条件を使用したり、データをフォーマットしたりする機能があります。Prometheus テンプレート言語は、Go テンプレートシステムに基づいています。

データ構造

時系列データを扱うための主要なデータ構造はサンプルであり、次のように定義されます。

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

サンプルのメトリクス名は、Labels マップ内の特別な __name__ ラベルでエンコードされます。

[]sample はサンプルのリストを意味します。

Go の interface{} は C の void ポインターに似ています。

関数

Go テンプレートで提供されるデフォルト関数に加えて、Prometheus はテンプレートでクエリ結果を簡単に処理するための関数を提供しています。

関数がパイプラインで使用されている場合、パイプラインの値は最後の引数として渡されます。

クエリ

名前 引数 戻り値 備考
query クエリ文字列 []sample データベースをクエリします。範囲ベクトルを返すことはサポートしていません。
first []sample sample index a 0 と同等
label label, sample string index sample.Labels label と同等
value sample interface{} sample.Value と同等
sortByLabel label, []samples []sample 指定されたラベルでサンプルをソートします。安定しています。

first、label、および value は、クエリ結果をパイプラインで簡単に使用できるようにすることを目的としています。

数値

名前 引数 戻り値 備考
humanize 数値または文字列 string 数値を、より読みやすい形式に変換します。メートル接頭辞を使用します。
humanize1024 数値または文字列 string humanize と同様ですが、1000 ではなく 1024 をベースとして使用します。
humanizeDuration 数値または文字列 string 秒単位の期間を、より読みやすい形式に変換します。
humanizePercentage 数値または文字列 string 比率値を 100 分率に変換します。
humanizeTimestamp 数値または文字列 string 秒単位の Unix タイムスタンプを、より読みやすい形式に変換します。
toTime 数値または文字列 *time.Time 秒単位の Unix タイムスタンプを time.Time に変換します。

人間向け関数は、人間が消費するのに適した出力を生成することを目的としており、Prometheus のバージョン間で同じ結果を返すことは保証されていません。

文字列

名前 引数 戻り値 備考
title string string strings.Title、各単語の最初の文字を大文字にします。
toUpper string string strings.ToUpper、すべての文字を大文字に変換します。
toLower string string strings.ToLower、すべての文字を小文字に変換します。
stripPort string string net.SplitHostPort、文字列をホストとポートに分割し、ホストのみを返します。
match パターン、テキスト ブール値 regexp.MatchString アンカーなしの正規表現一致をテストします。
reReplaceAll パターン、置換、テキスト string Regexp.ReplaceAllString 正規表現置換、アンカーなし。
graphLink expr string 式の 式ブラウザのグラフビューへのパスを返します。
tableLink expr string 式の 式ブラウザの表形式 ("Table") ビューへのパスを返します。
parseDuration string float "1h"などの期間文字列を、それが表す秒数に解析します。
stripDomain string string FQDN のドメイン部分を削除します。ポートは変更しません。

その他

名前 引数 戻り値 備考
args []interface{} map[string]interface{} これは、オブジェクトのリストを arg0、arg1 などのキーを持つマップに変換します。これは、複数の引数をテンプレートに渡せるようにすることを目的としています。
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 のマップとして使用できます。同じ名前の複数の URL パラメータにアクセスするには、.RawParams が各パラメータのリスト値のマップになります。URL パスは、/consoles/ プレフィックスを除いて .Path で使用できます。グローバルに構成された外部ラベルは .ExternalLabels として使用できます。また、4 つすべてに便利な変数があります: $rawParams、$params、$path、および $externalLabels。

コンソールは、-web.console.libraries フラグで指定されたディレクトリ内の *.lib ファイルにある {{define "templateName"}}...{{end}} で定義されたすべてのテンプレートにもアクセスできます。これは共有名前空間であるため、他のユーザーとの衝突を避けるように注意してください。prom、_prom、および __ で始まるテンプレート名、および上記の関数は、Prometheus で使用するために予約されています。

このドキュメントはオープンソースです。問題の提出やプルリクエストにより、改善にご協力ください。