テンプレートリファレンス
Prometheus は、アラートのアノテーションとラベル、および提供されるコンソールページでテンプレートをサポートしています。テンプレートは、ローカルデータベースに対してクエリを実行したり、データを反復処理したり、条件を使用したり、データをフォーマットしたりすることができます。Prometheus のテンプレート言語は、Go テンプレートシステムに基づいています。
データ構造
時系列データを扱う主要なデータ構造はサンプルであり、以下のように定義されます。
type sample struct {
Labels map[string]string
Value interface{}
}サンプルのメトリック名は、`Labels` マップ内の特別な `__name__` ラベルにエンコードされます。
`[]sample` はサンプルのリストを意味します。
Go の `interface{}` は C の void ポインタに似ています。
関数
Go テンプレートが提供するデフォルト関数に加えて、Prometheus はテンプレートでクエリ結果を簡単に処理するための関数を提供します。
パイプラインで関数を使用する場合、パイプライン値は最後の引数として渡されます。
クエリ
| 名前 | 引数 | 戻り値 | 注 |
|---|---|---|---|
| クエリ | クエリ文字列 | []sample | データベースをクエリし、範囲ベクトルを返すことはサポートしていません。 |
| 最初 | []sample | サンプル | `index a 0` と同等 |
| ラベル | ラベル、サンプル | 文字列 | `index sample.Labels label` と同等 |
| 値 | サンプル | interface{} | `sample.Value` と同等 |
| sortByLabel | ラベル、[]samples | []sample | 指定されたラベルでサンプルをソートします。安定しています。 |
`first`、`label`、`value` は、クエリ結果をパイプラインで簡単に使用できるようにすることを意図しています。
数値
| 名前 | 引数 | 戻り値 | 注 |
|---|---|---|---|
| 人間化 | 数値または文字列 | 文字列 | SI接頭辞を使用して、数値をより読みやすい形式に変換します。 |
| 人間化1024 | 数値または文字列 | 文字列 | `humanize` と同様ですが、1000 ではなく 1024 をベースとして使用します。 |
| 人間化期間 | 数値または文字列 | 文字列 | 秒単位の期間をより読みやすい形式に変換します。 |
| 人間化パーセンテージ | 数値または文字列 | 文字列 | 比率値を 100 分の 1 に変換します。 |
| 人間化タイムスタンプ | 数値または文字列 | 文字列 | 秒単位の Unix タイムスタンプをより読みやすい形式に変換します。 |
| toTime | 数値または文字列 | *time.Time | 秒単位の Unix タイムスタンプを time.Time に変換します。 |
人間化関数は、人間が消費するのに適した出力を生成することを意図しており、Prometheus のバージョン間で同じ結果を返すことを保証するものではありません。
文字列
| 名前 | 引数 | 戻り値 | 注 |
|---|---|---|---|
| タイトル | 文字列 | 文字列 | cases.Title、各単語の最初の文字を大文字にします。 |
| toUpper | 文字列 | 文字列 | strings.ToUpper、すべての文字を大文字に変換します。 |
| toLower | 文字列 | 文字列 | strings.ToLower、すべての文字を小文字に変換します。 |
| stripPort | 文字列 | 文字列 | net.SplitHostPort、文字列をホストとポートに分割し、ホストのみを返します。 |
| 一致 | パターン、テキスト | ブール値 | regexp.MatchStringアンカーなしの正規表現の一致をテストします。 |
| reReplaceAll | パターン、置換、テキスト | 文字列 | Regexp.ReplaceAllString正規表現置換、アンカーなし。 |
| グラフリンク | 式 | 文字列 | 式ブラウザでの式のグラフ表示へのパスを返します。 |
| テーブルリンク | 式 | 文字列 | 式ブラウザでの式の表形式（「テーブル」）表示へのパスを返します。 |
| parseDuration | 文字列 | 浮動小数点 | "1h" のような期間文字列を、それが表す秒数に解析します。 |
| stripDomain | 文字列 | 文字列 | FQDN のドメイン部分を削除します。ポートは変更しません。 |
その他
| 名前 | 引数 | 戻り値 | 注 |
|---|---|---|---|
| 引数 | []interface{} | map[string]interface{} | これは、オブジェクトのリストを、arg0、arg1などのキーを持つマップに変換します。これは、複数の引数をテンプレートに渡せるようにすることを意図しています。 |
| tmpl | 文字列、[]interface{} | なし | 組み込みの `template` と同様ですが、テンプレート名としてリテラルでないものを使用できます。結果は安全であると仮定され、自動エスケープされないことに注意してください。コンソールでのみ利用可能です。 |
| safeHtml | 文字列 | 文字列 | 文字列を自動エスケープ不要な HTML としてマークします。 |
| 外部URL | なし | 文字列 | Prometheus が外部からアクセス可能な外部 URL。 |
| pathPrefix | なし | 文字列 | コンソールテンプレートで使用する外部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 用に予約されており、上記の関数も同様です。