テンプレート参照

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	number or string	string	SI接頭辞を使用して、数値を読みやすい形式に変換します。
humanize1024	number or string	string	`humanize` と同様ですが、基数として 1000 ではなく 1024 を使用します。
humanizeDuration	number or string	string	秒単位の期間を読みやすい形式に変換します。
humanizePercentage	number or string	string	比率の値を 100 分率に変換します。
humanizeTimestamp	number or string	string	秒単位の Unix タイムスタンプを読みやすい形式に変換します。
toTime	number or string	*time.Time	秒単位の Unix タイムスタンプを time.Time に変換します。
toDuration	number or string	*time.Duration	秒単位の期間を time.Duration に変換します。
now	none	float64	テンプレート評価時の Unix タイムスタンプ（秒）を返します。

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

文字列

名前	引数	戻り値	注記
title	string	string	cases.Title、各単語の最初の文字を大文字にします。
toUpper	string	string	strings.ToUpper、すべての文字を大文字に変換します。
toLower	string	string	strings.ToLower、すべての文字を小文字に変換します。
stripPort	string	string	net.SplitHostPort、文字列をホストとポートに分割し、ホストのみを返します。
match	pattern, text	boolean	regexp.MatchString アンカーなしの正規表現マッチをテストします。
reReplaceAll	pattern, replacement, text	string	Regexp.ReplaceAllString 正規表現置換、アンカーなし。
graphLink	式	string	式に対する式ブラウザのグラフビューへのパスを返します。
tableLink	式	string	式に対する式ブラウザの表形式（「テーブル」）ビューへのパスを返します。
parseDuration	string	float	"1h" のような期間文字列を、それが表す秒数に解析します。
stripDomain	string	string	FQDN のドメイン部分を削除します。ポートは変更しません。

その他

名前	引数	戻り値	注記
args	[]interface{}	map[string]interface{}	オブジェクトのリストを、キーが arg0、arg1 などのマップに変換します。これは、複数の引数をテンプレートに渡せるようにするためのものです。
tmpl	string, []interface{}	nothing	組み込みの `template` と同様ですが、テンプレート名としてリテラル以外のものを許可します。結果は安全であるとみなされ、自動エスケープされません。コンソールでのみ利用可能です。
safeHtml	string	string	文字列を、自動エスケープを必要としない HTML としてマークします。
externalURL	none	string	Prometheus が外部から到達可能な外部 URL。
pathPrefix	none	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 パスは .Path で利用可能で、/consoles/ プレフィックスは除外されます。グローバルに設定された外部ラベルは .ExternalLabels として利用できます。また、これら4つすべてに対応する便利な変数もあります: $rawParams、$params、$path、$externalLabels。

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

このページの内容