翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # ラベルと注釈のテンプレート作成 **** このドキュメントのトピックは、**Grafana バージョン 10.x** をサポートする Grafana ワークスペース向けです。 Grafana バージョン 9.x をサポートする Grafana ワークスペースについては、「[Grafana バージョン 9 での作業](using-grafana-v9.md)」を参照してください。 Grafana バージョン 8.x をサポートする Grafana ワークスペースについては、「[Grafana バージョン 8 での作業](using-grafana-v8.md)」を参照してください。 テンプレートを使用して、クエリや式からのデータをラベルや注釈に含めることができます。たとえば、クエリの値に基づいてアラートの重大度ラベルを設定したり、クエリのインスタンスラベルをサマリー注釈で使用して、CPU使用率が高いサーバーを特定したりできます。 すべてのテンプレートは、[テキスト/テンプレート ](https://pkg.go.dev/text/template)で記述する必要があります。ラベルと注釈のどちらをテンプレート化するかにかかわらず、テンプレート化するラベルまたは注釈内に各テンプレートをインラインで記述する必要があります。つまり、ラベルと注釈間でテンプレートを共有することはできません。代わりに、テンプレートを使用する場所を問わず、テンプレートをコピーする必要があります。 各テンプレートは、アラートルールが評価されるたびに評価され、アラートごとに個別に評価されます。例えば、アラートルールにテンプレート作成されたサマリー注釈があり、アラートルールに 10 個の起動アラートがある場合、テンプレートはアラートごとに 10 回実行されます。テンプレートで高価な計算をできるだけ行わないようにする必要があります。 ## 例 次の例では、テキスト/テンプレートに関する完全なチュートリアルを記述するのではなく、テンプレートに関連する最も一般的なユースケースを示しています。これらの例を逐語的に使用したり、ユースケースに合わせて必要に応じて変更したりできます。テキスト/テンプレートの記述方法の詳細については、[テキスト/テンプレート](https://pkg.go.dev/text/template)のドキュメントを参照してください。 **すべてのラベルをカンマ区切りで印刷する** すべてのラベルをカンマ区切りで印刷するには、`$labels` 変数を出力します: ``` {{ $labels }} ``` 例えば、ラベル `alertname=High CPU usage`、`grafana_folder=CPU alerts`、および `instance=server1` を含むアラートがあると、以下が印刷されます: ``` alertname=High CPU usage, grafana_folder=CPU alerts, instance=server1 ``` **注記** クラシック条件を使用している場合、 `$labels` にはクエリからのラベルは含まれません。詳細については、[\$1labels 変数](#v10-alerting-overview-labels-templating-the-labels-variable)を参照してください。 **すべてのラベルを 1 行に 1 つずつ印刷する** すべてのラベルを 1 行に 1 つずつ印刷するには、 `range` を使用して各キーと値のペアを反復し、個別に印刷します。ここでは、`$k` の名前と現在のラベルの値 `$v` を参照します。 ``` {{ range $k, $v := $labels -}} {{ $k }}={{ $v }} {{ end }} ``` 例えば、ラベル `alertname=High CPU usage`、`grafana_folder=CPU alerts`、および `instance=server1` を含むアラートがあると、以下が印刷されます: ``` alertname=High CPU usage grafana_folder=CPU alerts instance=server1 ``` **注記** クラシック条件を使用している場合、 `$labels` にはクエリからのラベルは含まれません。詳細については、[\$1labels 変数](#v10-alerting-overview-labels-templating-the-labels-variable)を参照してください。 **個々のラベルの印刷** 個々のラベルを印刷するには、`$labels` 変数で `index` 関数を使用します。 ``` The host {{ index $labels "instance" }} has exceeded 80% CPU usage for the last 5 minutes ``` 例えば、ラベル `instance=server1` のアラートがあると、以下が印刷されます: ``` The host server1 has exceeded 80% CPU usage for the last 5 minutes ``` **注記** クラシック条件を使用している場合、 `$labels` にはクエリからのラベルは含まれません。詳細については、[\$1labels 変数](#v10-alerting-overview-labels-templating-the-labels-variable)を参照してください。 **クエリの値を印刷する** インスタントクエリの値を印刷するには、`index` 関数と `$values` 変数を使用して Ref ID を印刷します。 ``` {{ index $values "A" }} ``` 例えば、値 81.2345 を返すインスタントクエリがあると、次の内容が印刷されます: ``` 81.2345 ``` 範囲クエリの値を印刷するには、まず縮小式を使用して時系列からインスタントベクトルに値を変換する必要があります。その後、代わりに Ref ID を使用して、縮小式の結果を印刷できます。例えば、縮小式が A の平均を取得し、Ref ID B がある場合、次のように記述します: ``` {{ index $values "B" }} ``` **クエリのヒューマナイズされた値を印刷する** インスタントクエリのヒューマナイズされた値を印刷するには、 `humanize` 関数を使用します: ``` {{ humanize (index $values "A").Value }} ``` 例えば、値 81.2345 を返すインスタントクエリがあると、次の内容が印刷されます: ``` 81.234 ``` 範囲クエリのヒューマナイズされた値を印刷するには、まず時系列から、縮小式を使用してインスタントベクトルに減らす必要があります。その後、代わりに Ref ID を使用して、縮小式の結果を印刷できます。例えば、縮小式が A の平均を取得し、Ref ID B がある場合、次のように記述します: ``` {{ humanize (index $values "B").Value }} ``` **クエリの値をパーセンテージで印刷する** インスタントクエリの値をパーセンテージで印刷するには、 `humanizePercentage` 関数を使用します: ``` {{ humanizePercentage (index $values "A").Value }} ``` この関数は、値が 0 から 1 までの 10 進数であることを想定しています。代わりに、値が 0 から 100 までの 10 進数の場合、クエリまたは数式を使用して 100 で割ることができます。クエリが範囲クエリである場合は、まず、時系列から縮小式を使用してインスタントベクトルにクエリを減らす必要があります。 **クエリの値から重要度を設定する** クエリの値から重要度ラベルを設定するには、if ステートメントと greater than 比較関数を使用します。テキスト/テンプレートは型強制をサポートしていないため、`$values` と比較するときは、必ず小数点 (`80.0`、`50.0`、`0.0` など) を使用してください。サポートされているすべての比較関数のリストは、[こちら](https://pkg.go.dev/text/template#hdr-Functions)で確認できます。 ``` {{ if (gt $values.A.Value 80.0) -}} high {{ else if (gt $values.A.Value 50.0) -}} medium {{ else -}} low {{- end }} ``` **クラシック条件からすべてのラベルを印刷する** 従来の条件を使用している場合、 `$labels` を使用してクエリからラベルを印刷することはできません。代わりに `$values` を使用する必要があります。これは、クラシック条件がこれらのラベルを破棄して一次元動作を適用するためです (アラートルールごとに最大 1 つのアラート）。クラシック条件でこれらのラベルが破棄されない場合、多くの時系列を返すクエリでは、アラートルールが評価されるたびにラベルが変更されるため、アラートの発射と解決の間でアラートが頻繁に発生します。 代わりに、 `$values` 変数には、発射するすべての条件のすべての時系列の減算値が含まれます。例えば、2 つの時系列を返すクエリ A と、2 つの条件を持つクラシック条件 B を持つアラートルールがある場合、 `$values` には、`B0`、`B1`、`B2`、`B3` が含まれます。クラシック条件 B に 1 つの条件しかない場合、 `$values` には `B0` と `B1` のみが含まれます。 すべての発射時系列のすべてのラベルを印刷するには、次のテンプレートを使用します (正規表現の `B` を、異なる場合はクラシック条件の Ref ID に置き換えてください)。 ``` {{ range $k, $v := $values -}} {{ if (match "B[0-9]+" $k) -}} {{ $k }}: {{ $v.Labels }}{{ end }} {{ end }} ``` 例えば、1 つの条件を超える 2 つの時系列のクラシック条件が出力されます。 ``` B0: instance=server1 B1: instance=server2 ``` クラシック条件に2つ以上の条件があり、時系列が同時に複数の条件を超える場合、超過した条件ごとにラベルが重複します。 ``` B0: instance=server1 B1: instance=server2 B2: instance=server1 B3: instance=server2 ``` 一意のラベルを印刷する必要がある場合は、代わりにアラートルールを一次元から多次元に変更することを検討する必要があります。これを行うには、クラシック条件を縮小式と数式に置き換えます。 **クラシック条件のすべての値を印刷する** クラシック条件のすべての値を印刷するには、前の例を取って `$v.Labels` を `$v.Value` に置き換えます。 ``` {{ range $k, $v := $values -}} {{ if (match "B[0-9]+" $k) -}} {{ $k }}: {{ $v.Value }}{{ end }} {{ end }} ``` 例えば、1 つの条件を超える 2 つの時系列のクラシック条件が出力されます。 ``` B0: 81.2345 B1: 84.5678 ``` クラシック条件に 2 つ以上の条件があり、時系列が同時に複数の条件を超える場合、`$values` にはすべての条件の値が含まれます。 ``` B0: 81.2345 B1: 92.3456 B2: 84.5678 B3: 95.6789 ``` ## [変数] ラベルと注釈をテンプレート化する場合、次の変数を使用できます: ### ラベル変数 `$labels` 変数には、クエリのすべてのラベルが含まれます。たとえば、すべてのサーバーの CPU 使用率を返すクエリがあり、いずれかのサーバーの CPU 使用率が過去 5 分間に 80% を超えたときに起動するアラートルールがあるとします。どのサーバーで CPU 使用率が高いかを知らせるサマリー注釈をアラートに追加します。`$labels` 変数を使用すると、次のような判読可能な文を印刷するテンプレートを記述できます: ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes ``` **注記** クラシック条件を使用している場合、 `$labels` にはクエリからのラベルは含まれません。クラシック条件は、一次元動作 (アラートルールごとに最大 1 つのアラート) を適用するために、これらのラベルを破棄します。テンプレートでクエリのラベルを使用する場合は、前の「*クラシック条件からすべてのラベルを印刷する*」の例に従います。 ### 値変数 `$value` 変数は、アラートルールのすべてのインスタントクエリのラベルと値、しきい値、縮小式と数式、およびクラシック条件を含む文字列です。範囲クエリの結果は、10 から 10,000 行またはメトリクスのどれかを返す可能性があるため、含まれていません。そうした場合、特に大きなクエリでは、1 つのアラートで 10 MB のメモリが使用され、Grafana でメモリが非常に迅速に不足する可能性があります。 サマリーで `$value` 変数を印刷するには、次のような内容を作成します。 ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ $value }} ``` 次のように表示されます。 ``` CPU usage for instance1 has exceeded 80% for the last 5 minutes: [ var='A' labels={instance=instance1} value=81.234 ] ``` ここで `var='A'` は、Ref ID A を使用したインスタントクエリを参照し、ラベル `labels={instance=instance1}` を参照し、過去 5 分間の平均 CPU 使用率 `value=81.234` を参照します。 完全な文字列ではなく一部の文字列のみを印刷する場合は、 `$values` 変数を使用します。`$value` と同じ情報が含まれていますが、構造化されたテーブルの形態をとっており、必要なテキストのみに一致する正規表現を記述するよりもはるかに使いやすくなっています。 ### 値変数 `$values` 変数は、すべてのインスタントクエリと式のラベルと浮動小数点値を含むテーブルで、Ref ID でインデックス化されます。 Ref ID A でインスタントクエリの値を印刷するには: ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "A" }} ``` 例えば、ラベル `instance=server1` 付きのアラートと値 `81.2345` のインスタントクエリがあるとすると、次の内容が出力されます。 ``` CPU usage for instance1 has exceeded 80% for the last 5 minutes: 81.2345 ``` Ref ID A のクエリがインスタントクエリではなく範囲クエリである場合は、縮小式を Ref ID B に追加し、`(index $values "A")` を `(index $values "B")` に置き換えます。 ``` CPU usage for {{ index $labels "instance" }} has exceeded 80% for the last 5 minutes: {{ index $values "B" }} ``` ## 関数 ラベルと注釈をテンプレート化するときは、次の関数を使用できます。 **args** `args` 関数は、オブジェクトのリストをキー arg0、arg1 などのマップに変換します。これは、複数の引数をテンプレートに渡せるようにすることを目的としています。 ``` {{define "x"}}{{.arg0}} {{.arg1}}{{end}}{{template "x" (args 1 "2")}} ``` ``` 1 2 ``` **externalURL** `externalURL` 関数は Grafana サーバーの外部 URL を返します。 ``` {{ externalURL }} ``` ``` https://example.com/grafana ``` **graphLink** `graphLink` 関数は、指定された式とデータソースの [Grafana バージョン 10 で探索する](v10-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` 関数は Grafana サーバーのパスを返します。 ``` {{ pathPrefix }} ``` ``` /grafana ``` **tableLink** `tableLink` 関数は、指定された式とデータソースの [Grafana バージョン 10 で探索する](v10-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 ```