ラベルと注釈のテンプレート作成
このドキュメントのトピックは、Grafana バージョン 9.x をサポートする Grafana ワークスペース向けです。
Grafana バージョン 10.x をサポートする Grafana ワークスペースについては、「Grafana バージョン 10 での作業」を参照してください。
Grafana バージョン 8.x をサポートする Grafana ワークスペースについては、「Grafana バージョン 8 での作業」を参照してください。
Grafana では、Prometheus と同じようにラベルと注釈をテンプレート化します。Prometheus を使用した経験がある場合は、アラートのラベルと値を含む $labels
変数と $value
変数に精通していると思います。アラートが Prometheus データソースを使用していない場合でも、Grafana で同じ変数を使用できます。以前に Prometheus を使用したことがない場合は、これらの変数のそれぞれとテンプレートの作成方法をこのページで説明するのでご安心ください。
Go のテンプレート言語
ラベルと注釈のテンプレートは、Go のテンプレート言語 text/template
開始と終了のタグ
テキスト/テンプレートでは、テンプレートが変数を印刷するか、if ステートメントなどのコントロール構造を実行するかに関係なく、テンプレートは {{
で始まり、}}
で終わります。これは、変数の出力に {{
と }}
を使用し、制御構造に {%
と %}
を使用する Jinja などの他のテンプレート言語とは異なります。
印刷
何かの値を印刷するには、{{
と }}
を使用します。関数の結果または変数の値を印刷できます。例えば、$labels
変数を印刷するには、次のように書き込みます。
{{ $labels }}
ラベルを反復処理する
$labels
内の各ラベルを反復処理するには、range
を使用できます。ここでは、$k
は名前を表し、$v
は現在のラベルの値を表します。例えば、クエリがラベル instance=test
を返した場合、 $k
は instance
になり、$v
は test
になります。
{{ range $k, $v := $labels }} {{ $k }}={{ $v }} {{ end }}
ラベル、値、値変数
ラベル変数
$labels
変数には、クエリのラベルが含まれます。たとえば、インスタンスがダウンしているかどうかを確認するクエリは、停止しているインスタンスの名前を含むインスタンスラベルを返す場合があります。例えば、インスタンスの 1 つが 5 分以上ダウンしたときに発生するアラートルールがあるとします。どのインスタンスがダウンしているかを知らせる概要をアラートに追加します。$labels
変数を使用すると、概要にインスタンスラベルを印刷する概要を作成できます。
Instance {{ $labels.instance }} has been down for more than 5 minutes
ドット付きのラベル
印刷するラベルに、テンプレート内の同じドットを使用して名前にドット (ピリオド) が含まれている場合、機能しません。
Instance {{ $labels.instance.name }} has been down for more than 5 minutes
これは、テンプレートが $labels.instance
で name
という既存のフィールドを使用しようとしているためです。代わりに、index
関数を使用する必要があります。この関数は、$labels
変数 instance.name
にラベルを出力します。
Instance {{ index $labels "instance.name" }} has been down for more than 5 minutes
値変数
$value
変数の動作は Prometheus とは異なります。Prometheusでは、$value
は式の値を含む浮動小数点数ですが、Grafana では、このアラートルールのすべてのしきい値、縮小式、数式およびクラシック条件のラベルと値を含む文字列です。クエリの結果は 10 から 10,000 行またはメトリクスのどこかに返される可能性があるため、含まれていません。
アラートの概要で $value
変数を使用する場合:
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $value }})
概要は、次のようになります。
api has an over 5% of responses with 5xx errors: [ var='B' labels={service=api} value=6.789 ]
ここでは、var='B'
は RefID B を持つ式を指します。Grafana では、すべてのクエリと式は、アラートルール内の各クエリと式を識別する RefID によって識別されます。同様に、labels={service=api}
はラベルを表し、value=6.789
は値を表します。
RefID A がないことが観察された可能性があります。これは、ほとんどのアラートルールでは RefID A がクエリを参照し、クエリが多くの行や時系列を返す可能性があるため、$value
に含まれていないためです。
値変数
$value
変数に必要以上の情報が含まれている場合は、代わりに $values
を使用して個々の式のラベルと値を印刷できます。$value
とは異なり、$values
変数は、各式のラベルと浮動小数点値を含むオブジェクトのテーブルで、RefID によってインデックス化されます。
アラートの概要に RefID B
を使用して式の値を印刷する場合:
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ $values.B }}%
概要には、値のみが含まれます。
api has an over 5% of responses with 5xx errors: 6.789%
ただし、{{ $values.B }}
は数字 6.789 を出力しますが、実際には RefID B のラベルと値の両方を含むオブジェクトを出力する文字列であり、B の浮動小数点値ではありません。RefID B の浮動小数点値を使用するには、$values.B
の Value
フィールドを使用する必要があります。アラートの概要の浮動小数点値をヒューマナイズする場合:
{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanize $values.B.Value }}%
データなし、ランタイムエラー、タイムアウト
アラートルールのクエリがデータなしを返す場合、またはデータソースのエラーやタイムアウトが原因で失敗した場合、そのクエリを使用するしきい値、縮小式、または数式もデータやエラーを返しません。この場合、これらの式は $values
には存在しません。使用する前に RefID が存在することを確認することをお勧めします。RefID が存在しない場合、クエリがデータやエラーを返さない場合にテンプレートが壊れます。これは、if ステートメントを使用して行うことができます。
{{ if $values.B }}{{ $labels.service }} has over 5% of responses with 5xx errors: {{ humanizePercentage $values.B.Value }}{{ end }}
クラシック条件
ルールがしきい値、縮小式、および数式の代わりにクラシック条件を使用する場合、$values
変数はクラシック条件の条件の Ref ID と位置の両方によってインデックス化されます。例えば、RefID B に 2 つの条件を含むクラシック条件がある場合、$values
には 2 つの条件 B0
と B1
が含まれます。
The first condition is {{ $values.B0 }}, and the second condition is {{ $values.B1 }}
関数
ラベルと注釈を展開するときにも、次の関数を使用できます。
args
args
関数は、オブジェクトのリストをキー arg0、arg1 などのマップに変換します。これは、複数の引数をテンプレートに渡せるようにすることを目的としています。
例
{{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}}
1 2
externalURL
externalURL
関数は、ini ファイル (複数可) で設定された Grafana サーバーの外部 URL を返します。
例
{{ externalURL }}
https://example.com/grafana
graphLink
graphLink
関数は、指定された式とデータソースの Grafana バージョン 9 で探索する のグラフィックビューへのパスを返します。
例
{{ graphLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":false,"range":true}]
humanize
humanize
関数は 10 進数をヒューマナイズします。
例
{{ humanize 1000.0 }}
1k
humanize1024
humanize1024
は humanize
と似ていますが、1000 ではなく 1024 をベースとして使用します。
例
{{ humanize1024 1024.0 }}
1ki
humanizeDuration
humanizeDuration
関数は、期間を秒単位でヒューマナイズします。
例
{{ humanizeDuration 60.0 }}
1m 0s
humanizePercentage
humanizePercentage
関数は、比率値をパーセンテージにヒューマナイズします。
例
{{ humanizePercentage 0.2 }}
20%
humanizeTimestamp
humanizeTimestamp
関数は Unix タイムスタンプをヒューマナイズします。
例
{{ humanizeTimestamp 1577836800.0 }}
2020-01-01 00:00:00 +0000 UTC
match
match
関数は、テキストを正規表現パターンと一致させます。
例
{{ match "a.*" "abc" }}
true
pathPrefix
pathPrefix
関数は、ini ファイル (複数可) で設定された Grafana サーバーのパスを返します。
例
{{ pathPrefix }}
/grafana
tableLink
tableLink
関数は、指定された式とデータソースの Grafana バージョン 9 で探索する の表形式ビューへのパスを返します。
例
{{ tableLink "{\"expr\": \"up\", \"datasource\": \"gdev-prometheus\"}" }}
/explore?left=["now-1h","now","gdev-prometheus",{"datasource":"gdev-prometheus","expr":"up","instant":true,"range":false}]
title
title
関数は、各単語の最初の文字を大文字にします。
例
{{ title "hello, world!" }}
Hello, World!
toLower
toLower
関数はすべてのテキストを小文字で返します。
例
{{ toLower "Hello, world!" }}
hello, world!
toUpper
toUpper
関数は、すべてのテキストを大文字で返します。
例
{{ toUpper "Hello, world!" }}
HELLO, WORLD!
reReplaceAll
reReplaceAll
関数は、正規表現に一致するテキストを置き換えます。
例
{{ reReplaceAll "localhost:(.*)" "example.com:$1" "localhost:8080" }}
example.com:8080