翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # ラベルと注釈のテンプレート作成 **** このドキュメントのトピックは、**Grafana バージョン 9.x** をサポートする Grafana ワークスペース向けです。 Grafana バージョン 10.x をサポートする Grafana ワークスペースについては、「[Grafana バージョン 10 での作業](using-grafana-v10.md)」を参照してください。 Grafana バージョン 8.x をサポートする Grafana ワークスペースについては、「[Grafana バージョン 8 での作業](using-grafana-v8.md)」を参照してください。 Grafana では、Prometheus と同じようにラベルと注釈をテンプレート化します。Prometheus を使用した経験がある場合は、アラートのラベルと値を含む `$labels` 変数と `$value` 変数に精通していると思います。アラートが Prometheus データソースを使用していない場合でも、Grafana で同じ変数を使用できます。以前に Prometheus を使用したことがない場合は、これらの変数のそれぞれとテンプレートの作成方法をこのページで説明するのでご安心ください。 ## Go のテンプレート言語 ラベルと注釈のテンプレートは、Go のテンプレート言語 [ text/template ](https://pkg.go.dev/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 で探索する](v9-explore.md) のグラフィックビューへのパスを返します。 **例** ``` {{ 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 で探索する](v9-explore.md) の表形式ビューへのパスを返します。 **例** ``` {{ 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 ```