翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # テンプレートおよび変数 **** このドキュメントのトピックは、**Grafana バージョン 8.x** をサポートする Grafana ワークスペース向けです。 Grafana バージョン 12.x をサポートする Grafana ワークスペースについては、「」を参照してください[Grafana バージョン 12 での作業](using-grafana-v12.md)。 Grafana バージョン 10.x をサポートする Grafana ワークスペースについては、「[Grafana バージョン 10 での作業](using-grafana-v10.md)」を参照してください。 Grafana バージョン 9.x をサポートする Grafana ワークスペースについては、「[Grafana バージョン 9 での作業](using-grafana-v9.md)」を参照してください。 変数は、値のプレースホルダーです。メトリクスクエリとパネルタイトルで変数を使用できます。変数を使用するとよりインタラクティブで動的なダッシュボードを作成できます。メトリクスクエリでサーバー、アプリケーション、センサー名などをハードコーディングする代わりに、変数を使用できます。 変数は、ダッシュボードの上部にドロップダウンリストとして表示されます。ダッシュボードの上部にあるドロップダウンリストを使用して値を変更すると、パネルのメトリクスクエリには新しい値が反映されます。 これらは、ビューワーが視覚化をすばやく調整できるようにしたいが、完全な編集アクセス許可を付与したくない管理者にとって特に便利です。Grafana ビューワーは変数を使用できます。 変数とテンプレートを使用すると、単一ソースのダッシュボードにすることができます。同じデータソースまたはサーバーが複数ある場合は、1 つのダッシュボードを作成し、変数を使用して表示内容を変更できます。これにより、メンテナンスと維持が簡素化されます。 サポートされている変数タイプのリスト、各変数タイプの追加手順については、「[変数タイプ](variables-types.md)」を参照してください。 ## テンプレート *[テンプレート]*は、変数を含むすべてのクエリです。 例えば、複数サーバーをモニタリングするためにダッシュボードを管理している場合は、サーバーごとにダッシュボードを作成できます。または、次の例に示すように、1 つのダッシュボードを作成して、テンプレートクエリでパネルを使用できます。 ``` wmi_system_threads{instance=~"$server"} ``` 変数値は構文 `var-=value` を使用して常に URL に同期されます。 ## 変数のベストプラクティス 変数のドロップダウンリストは、**[ダッシュボード設定]** の変数リストに一覧されている順序で表示されます。 頻繁に変更する変数を一番上に置くと、ダッシュボードの左端に最初に表示されるようになります。 ## 変数構文 パネルタイトルとメトリクスクエリは、次の 2 つの異なる構文を使用して変数を参照できます。 + `$varname` これは次の例のように読みやすい構文です。`apps.frontend.$server.requests.count`ただし、単語の途中で変数を使用することができません。 + `${var_name}` この構文は式の途中で変数を補間する場合に使用します。 + `${var_name:}` この形式により、Grafana が値を解釈する方法をより細かく制御できます。詳細については、「[高度な変数フォーマットオプション](#advanced-variable-format-options)」を参照してください。 クエリがデータソースに送信される前に、クエリは*[補間されます]*。つまり、変数は現在の値に置き換えられます。補間中、変数値は、クエリ言語の構文と使用される場所に準拠するように*エスケープ*される可能性があります。例えば、Prometheus クエリの正規表現で使用される変数は、正規表現からエスケープされます。補間中の値のエスケープの詳細については、データソース固有のドキュメントトピックを参照してください。 データソースのデフォルトのフォーマットを上書きする高度な構文については、「[高度な変数フォーマットオプション](#advanced-variable-format-options)」を参照してください。 ## その他の変数オプション このセクションでは、他の使用可能な変数オプションについて説明します。 ### 変数選択オプションの入力 **選択オプション**を使用すると可変オプションの選択を管理できます。すべての選択オプションは任意で使用でき、デフォルトではオフになっています。 #### 複数値 このオプションをオンにすると、変数のドロップダウンリストで複数のオプションを同時に選択することができます。詳細については、「[複数値の変数のフォーマット](#formatting-multi-value-variables)」を参照してください。 #### すべてを含めるオプション Grafana ワークスペースは、変数ドロップダウンリストに `All` オプションを追加します。エンドユーザーがこのオプションを選択すると、すべての変数オプションが選択されます。 #### すべての値のカスタム化 このオプションは、**[すべてのオプションを含める]** が選択されている場合にのみ表示されます。 `All` オプションの値を定義するには、**[すべての値のカスタム化]** フィールドに regex、glob、または Lucene 構文を入力します。 デフォルトでは、`All` 値には結合式内のすべてのオプションが含まれます。これは非常に長くなり、パフォーマンスの問題が発生する可能性があります。ワイルドカード正規表現など、すべての値のカスタム化を指定する方がよい場合があります。 **すべての値のカスタム化**オプションでカスタム正規表現、glob、または Lucene 構文を使用する場合はエスケープされないため、データソースに有効な値は何かを考慮する必要があります。 ### 高度な変数フォーマットオプション 変数補間のフォーマットはデータソースによって異なりますが、デフォルトの形式を変更する場合があります。 例えば、MySQL データソースのデフォルトは、`'server01','server02'` などのように、複数の値を引用符でカンマ区切りで結合することです。場合によっては、`server01,server02` など、引用符なしでカンマ区切りの文字列を指定することもできます。これを実行するには、次の高度な可変フォーマットオプションを使用します。 #### 一般的な構文 構文: `${var_name:option}` 無効なフォーマットオプションが指定されている場合、`glob` はデフォルト、またはフォールバックのオプションです。 #### CSV 複数の値をカンマ区切り文字列として変数をフォーマットします。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:csv}' Interpolation result: 'test1,test2' ``` #### 分散 - OpenTSDB OpenTSDB のカスタム形式の複数の値を持つ変数をフォーマットします。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:distributed}' Interpolation result: 'test1,servers=test2' ``` #### 二重引用符 単一値変数と複数値の変数をカンマ区切りの文字列にフォーマットして、`\"` によって各値の `"` をエスケープし、`"` で引用符で囲みます。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:doublequote}' Interpolation result: '"test1","test2"' ``` #### Glob - Graphite 複数の値を持つ変数を glob にフォーマットします (Graphite クエリの場合)。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:glob}' Interpolation result: '{test1,test2}' ``` #### JSON 複数の値をカンマ区切り文字列として変数をフォーマットします。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:json}' Interpolation result: '["test1", "test2"]' ``` #### Lucene - OpenSearch OpenSearch の Lucene 形式の複数の値を持つ変数をフォーマットします。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:lucene}' Interpolation result: '("test1" OR "test2")' ``` #### Percentencode URL パラメータで使用する単一値の変数と複数値の変数をフォーマットします。 ``` servers = ['foo()bar BAZ', 'test2'] String to interpolate: '${servers:percentencode}' Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2' ``` #### パイプ 複数の値を持つ変数をパイプ区切り文字列にフォーマットします。 ``` servers = ['test1.', 'test2'] String to interpolate: '${servers:pipe}' Interpolation result: 'test1.|test2' ``` #### Raw SQL クエリにおける単一引用符など、データソース固有のフォーマットをオフにします。 ``` servers = ['test1.', 'test2'] String to interpolate: '${var_name:raw}' Interpolation result: '{test.1,test2}' ``` #### [正規表現] 複数の値を持つ変数を正規表現文字列にフォーマットします。 ``` servers = ['test1.', 'test2'] String to interpolate: '${servers:regex}' Interpolation result: '(test1\.|test2)' ``` #### 一重引用符 単一値の変数と複数値の変数をカンマ区切り文字列にフォーマットし、`\'` によって各値の `'` をエスケープし、`'` で各値を引用符で囲みます。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:singlequote}' Interpolation result: "'test1','test2'" ``` #### Sqlstring 単一値の変数と複数値の変数をカンマ区切り文字列にフォーマットし、`''` によって各値の `'` をエスケープし、`'` で各値を引用符で囲みます。 ``` servers = ["test'1", "test2"] String to interpolate: '${servers:sqlstring}' Interpolation result: "'test''1','test2'" ``` #### テキスト 単一値の変数と複数値の変数をテキスト表現にフォーマットします。単一値の変数の場合、テキスト表現のみを返します。複数値の変数の場合、テキスト表現は `+` と組み合わせて返されます。 ``` servers = ["test1", "test2"] String to interpolate: '${servers:text}' Interpolation result: "test1 + test2" ``` ### 複数値の変数のフォーマット 複数値が選択された変数を補間するのは、変数が使用されている特定のコンテキストで有効な文字列に複数の値をフォーマットする方法が単純ではないため、難しくなります。Grafana は、各データソースプラグインがテンプレート補間エンジンに、複数値に使用する形式を通知できるようにすることで、この問題を解決しようと試みます。 **注記** Grafana がすべての値を 1 つの文字列にフォーマットするには、 変数の **[すべての値をカスタム化]** オプションを空白にする必要があります。空白のままにすると、Grafana はクエリ内のすべての値を連結 (一緒に加える) します。`value1,value2,value3` のようになります。カスタム `all` 値を使用する場合、代わりに `*` または `all` のような値になります。 #### Graphite データソースを使用した複数値変数 Graphite は glob 式を使用します。この場合、複数の値を持つ変数は、現在の変数値が *host1*、*host2*、*host3* であった場合は、`{host1,host2,host3}` として補間されます。 #### Prometheus または InfluxDB データソースを使用した複数値変数 InfluxDB と Prometheus は正規表現を使用するため、同じ変数は `(host1|host2|host3)` として補間されます。すべての値も正規表現エスケープされます。そうでない場合、正規表現コントロール文字を持つ値は正規表現を破ります。 #### Elastic データソースを使用した複数値変数 Amazon OpenSearch は Lucene クエリ構文を使用するため、同じ変数は `("host1" OR "host2" OR "host3")` としてフォーマットされます。この場合、すべての値がエスケープされ、値には Lucene 制御語と引用符のみが含まれます。 #### フォーマットのトラブルシューティング 自動エスケープとフォーマットは問題を引き起こす場合があります。特に InfluxDB と Prometheus では正規表現構文を使用するため、変数を正規表現演算子コンテキストで使用する必要があり、問題の背後にあるロジックの把握が難しい場合があります。 Grafana でこの自動正規表現エスケープとフォーマットを実行したくない場合は、次のいずれかを実行する必要があります。 + **[複数値]** **[すべてのオプションを含める]** オプションをオフにします。 + [raw variable format]({{< relref "advanced-variable-format-options.md\#raw" >}}) を使用します。 ### 正規表現での変数のフィルタリング 正規表現クエリオプションを使用すると、変数クエリが返すオプションのリストをフィルタリング、または返すオプションを変更できます。 このセクションでは、正規表現を使用して変数ドロップダウンリスト内の値をフィルタリングおよび変更する方法を示します。 [正規表現クエリ] オプションを使用して、変数クエリによって返されるオプションの一覧をフィルタリングするか、返されるオプションを変更します。詳細については、「[正規表現](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)」を参照してください。 次のオプションリストでのフィルタリングの例: ``` backend_01 backend_02 backend_03 backend_04 ``` #### `01` または `02` で終わるオプションのみが返されるようにフィルタリング [Regex] (正規表現) ``` /.*[01|02]/ ``` 結果: ``` backend_01 backend_02 ``` #### 正規表現キャプチャグループを使用してテキストの一部を返すオプションのフィルタリングおよび変更 正規表現: ``` /.*(01|02)/ ``` 結果: ``` 01 02 ``` #### フィルタリングと変更 - Prometheus 例 オプションのリスト: ``` up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000 up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000 up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000 ``` 正規表現: ``` /.*instance="([^"]*).*/ ``` 結果: ``` demo.robustperception.io:9090 demo.robustperception.io:9093 demo.robustperception.io:9100 ``` #### 名前付きテキストおよび値のキャプチャグループを使用したフィルタリングと変更 名前付きキャプチャグループを使用すると、変数クエリが返すオプションから「テキスト」と「値」の部分を別々にキャプチャできます。変数ドロップダウンリストには、選択できる各値に対するわかりやすい名前を含めることができます。 例えば、`node_hwmon_chip_names` Prometheus メトリクスをクエリする場合、`chip_name` は `chip` 値よりもわかりやすくなります。次の変数クエリ結果で開始します。 ``` node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1 ``` これを次の正規表現に渡します。 ``` /chip_name="(?[^"]+)|chip="(?[^"]+)/g ``` 次のドロップダウンリストが生成されます。 ``` Display Name Value ------------ ------------------------- enp216s0f0np0 0000:d7:00_0_0000:d8:00_0 enp216s0f0np1 0000:d7:00_0_0000:d8:00_1 enp216s0f0np2 0000:d7:00_0_0000:d8:00_2 enp216s0f0np3 0000:d7:00_0_0000:d8:00_3 ``` **注:** `text` および `value` のキャプチャグループ名のみがサポートされています。 ### パネルまたは行の繰り返し *テンプレート変数*を使用すると動的ダッシュボードを作成できます。クエリ内のすべての変数は、クエリがデータベースに送信される前に変数の現在の値に拡張されます。変数を使用すると、すべての サービスで 1 つのダッシュボードを再利用できます。 ダッシュボード全体でクエリを動的に変更する際は、テンプレート変数が非常に役立ちます。選択した値に基づいて Grafana で新しいパネルまたは行を動的に作成させる場合は、*繰り返し*機能を使用できます。 #### パネルの繰り返し `Multi-value` または `Include all value` オプションがオンの変数がある場合は、1 つのパネルを選択して、Grafana に選択した値ごとにそのパネルを繰り返させることができます。*繰り返し*機能はパネル編集モードの*全般タブ*にあります。 `direction` はパネルの配置方法を制御します。 `horizontal` を選択するとパネルは並んで配置されます。Grafana は繰り返しパネルの幅を自動的に調整して行全体がいっぱいになるようにします。現在、行上の他のパネルと繰り返しパネルを混在して使うことはできません。 `Max per row` を設定して、行あたりの最大パネル数を Grafana に指示します。デフォルトは *4* です。 `vertical` を選択すると、パネルは列の上から下に配置されます。繰り返しパネルの幅は、繰り返される最初の繰り返しパネル (元のテンプレート) の幅と同じです。 最初のパネル (元のテンプレート) のみ変更します。すべてのパネルに変更が適用されるためには、動的ダッシュボードの再構築を開始する必要があります。このためには変数値を変更 (つまり、繰り返しの基礎)、またはダッシュボードを再ロードします。 **注記** パネルを繰り返すには、変数に対して 1 つ以上の項目を選択する必要があります。非表示にするためにパネルを 0 回繰り返すことはできません。 #### 行の繰り返し パネルに関して前述したように、変数に `Multi-value` または `Include all value` 選択オプションを設定している場合は、行を繰り返すこともできます。 この機能を有効にするには、まず *[パネルの追加]* メニューを使用して新しい*行*を追加する必要があります。次に、行タイトルの上にカーソルを置いて歯車ボタンを選択し、`Row Options` 設定パネルにアクセスします。行を繰り返す変数を選択できるようになります。 ベストプラクティスは行タイトルにも変数を使用することです。