概要
GrafanaのVariablesを使う方法を説明します。
GrafanaのVariablesは、以下の図のようにダッシュボード上でダッシュボードの閲覧者がパラメータを指定できる機能です。
ダッシュボードの閲覧者が、パラメータを指定すると紐づいた値がクエリに反映できます（SQLのWhere句などフィルタに利用できます）。
基本的には以下の公式ドキュメントのとおりです。
なお、本記事の正確性や完全性について保証しませんので、ご注意ください。
Variablesの利用
ダッシュボードの設定から Variablesを選択し「+New variable」を選択します。
Variableの追加
Variableには、以下の4つの typeがあります。
- Query : データソースに対してクエリを発行しその結果をユーザは指定できます。
- Label : 入力ボックスでユーザがテキストを自由に指定できます。
- Custom : カンマ区切りリストを手動で定義します。
- Constants : 隠れた定数を指定します。
ここでは一番使いそうな「Query」での使い方を詳しく説明します。
Query Variableの使い方
Variable typeは「Query」を指定します。
Name, Label, Descriptionは適当に。
「Show on dashboard」 は概要の図のように、Labelで指定した値(display name)と選択肢の値(display text)を表示したければ「Label and value」を指定しましょう。
Query optionsと Regex
Query variableでは、display textとvalueの2つの値のセットのリストを持つことができます。
display text は選択肢用の表示テキストで、valueはユーザが選択肢を選択したときにクエリに代入する値になります。
Query optionsで、variableに指定したいデータを取得するためのデータソースに対するクエリを記述します。
Regexでは、クエリの返却結果からvariableで使うデータを分離します。
重要なポイントとして、クエリの結果は、2つの値（display textとvalue）に相当するデータを1つの文字列として返し、Regexでdisplay textとvalueに分解します。
以下の図のクエリでは、Amazon Athenaにクエリを発行し、あるデータセットのidとtitleをカンマ区切りの文字列(id || ',' || title)のデータセットとして返却するように設定しています。
Regexで/(?<value>.*),(?<text>.*)/と指定して、返却されたデータからvalueとdisplay text を分離しています。
これにより表示テキスト(title)とvalue(id)のリストを作っています（図の例でvariableを作ると、スプリントのリストが表示され、選択時にそのスプリントのidがパネルなどの実行クエリに代入されます）。
その他のオプションは以下のとおりです。
- Sort : text valueの順序指定
- Refresh : ダッシュボードの表示時に１回 or タイムレンジ変更時に１回
- Selection options
- Multi-value : 有効な場合、複数の値を同時に選択できるようにする
- Include All options : 有効な場合、「All」選択肢を追加します。「Custom all value」に「All」選択時のvalueを指定します。
variableで設定された値を使う
variableを追加したダッシュボード上のパネルのクエリで、${Nameで記述した値} と記述することでユーザが指定した選択肢のvalue が代入されます。
例えば上記の図のようにNameが milestoneの場合は、$milestoneとなります。
SQLのwhere句に使うとなると以下な感じです。
select * FROM $__table() where id = $milestone
TIPS
- ダッシュボードで選択したvariableを初期値にしたい（ロード時に必ずその値にしたい）場合はダッシュボードのセーブ時の設定「Save current variable values as dashboard defalut」をONにすることで出来ます。
- 「Include All options」を利用する際に、Athenaなどでは「Custiom all value」をうまく指定できず困ることがあります。
普通に考えると*ですが、Athenaではwhere句で*を利用できません(where id = *が利用できません)。
その場合は、ハック的ですが0 OR 1=1のように指定することで全件を対象と出来ます(where id = 0 OR 1=1 となってidが全件対象となる)。
おわりに
今回は Grafanaでの Variablesの使い方をまとめました。
Variablesを使うことでユーザがダッシュボードのデータをフィルタ等することで、可視化の高度化が可能です。
商標
記載の会社名、製品名、サービス名等はそれぞれの会社の商標または登録商標です。