本文へジャンプ

Grafana 入力プラグインガイド

Revision: 1.6.0-10082-768e556f

1 概要

Grafana用GridDB入力プラグインはGridDBからデータを取得し、 Grafana上にグラフやテーブルとして表示するために使用するプラグインです。

1.1 必須要件

本GridDB入力プラグインには以下の必須要件があります。

  1. サーバもしくは組織の管理者権限を持つGrafanaユーザについては 権限を参照。

  2. GridDBサーバには最低1名のGridDBユーザが必要です。

1.2 既知の制限事項

該当なし

2 インストール

2.1 Grafanaのインストール

Grafanaのインストールを参照。

2.2 GridDB入力プラグインのインストール

2.2.1 ビルド方法

1. npm install -g yarn
2. yarn install
3. yarn build

2.2.2 インストール方法

1. $GRAFANA_HOME/plugins-bundled/internal/input-datasourceで新規フォルダGridDB-pluginを作成します。

2. GridDBプラグインのdistフォルダをGridDB-pluginフォルダにコピーします。

3. Grafanaサーバを再起動します。

2.3 GridDBのデータソースの追加

📝 Grafanaサーバがプロキシサーバの背後にある場合、 GridDBに接続する前に、環境変数を設定してプロキシを構成する必要があります。

  1. (必要であれば)プロキシ構成用の環境変数を設定します。
  2. $GRAFANA_HOME/binでgrafana-serverを実行します。
  3. ブラウザを開き、"localhost:3000"アドレスに移動します。
  4. Grafanaのusername(ユーザ名)password(パスワード) を使ってGrafanaにログインします。初回ログインの場合、初期usernameとpasswordはいずれもadminです。
  5. (初回ログインの場合)パスワードを変更します。
  6. 上部ヘッダのGrafanaアイコンをクリックし、サイドメニューを開きます。
  7. サイドメニューのConfiguration リンクの下の Data Sources というリンクをクリックします。
  8. 上部ヘッダの + Add data source ボタンをクリックします。
  9. 検索領域にGridDBと入力します。データソースとしてGridDBが表示されたことを確認し、Select ボタンをクリックします。
  10. GridDB-Cloud等、任意のデータソース名を Name 領域に記入します。
  11. GridDB Connection セクションの host 領域にGridDB Web APIのURLを入力します。この際、/griddb/v2などのコンテキストパスは含めないようにしてください。
  12. GridDBの cluster name(クラスタ名) を入力します。
  13. database name(データベース名) を入力します。何も入力されない場合、デフォルトのデータベース"public"が使われます。
  14. 手順13で指定したデータベースに対し、読み込み権限を持つGridDBユーザの username(ユーザ名)password(パスワード) を入力します。
  15. min time interval(最小時間間隔) を入力します。デフォルトは1 second(1秒)です。
  16. Save & test ボタンをクリックし、GridDBへの接続を確認します。
GridDBへの接続の確認

3 データの準備

ここでは3つのコンテナを作成します。

  1. 1番目のコンテナを作成します。
  • コンテナ名: table30DayTo5years

  • コンテナのタイプ: TIMESERIES

  • コンテナのスキーマ:

    | Name      | Type           | Constraints    |
    |---------  |-----------     |-------------   |
    | mycolumn1 | TIMESTAMP      | NOT NULL       |
    | col_1     | BYTE           |                |
    | col_2     | SHORT          |                |
    | col_3     | INTEGER        |                |
    | col_4     | LONG           |                |
    | col_5     | FLOAT          |                |
    | col_6     | DOUBLE         |                |
    
1番目のコンテナの作成
  1. 2番目のコンテナを作成します。
  • コンテナ名: Multiple_Time_Columns
  • コンテナのタイプ: TIMESERIES
  • コンテナのスキーマ:
| Name      | Type           | Constraints  |
|---------  |-----------     |------------- |
| col1      | TIMESTAMP      | NOT NULL     |
| col2      | TIMESTAMP      |              |
| col3      | STRING         |              |
| col4      | INTEGER        |              |
2番目のコンテナの作成
3. 3番目のコンテナを作成します。
  • コンテナ名: grafana
  • コンテナのタイプ: TIMESERIES
  • コンテナのスキーマ:
| Name      | Type           | Constraints  |
|---------  |-----------     |------------- |
| time      | TIMESTAMP      | NOT NULL     |
| col1      | INTEGER        |              |
| col2      | INTEGER        |              |
| col3      | INTEGER        |              |
| col4      | INTEGER        |              |
| col5      | INTEGER        |              |
| col6      | INTEGER        |              |
3番目のコンテナの作成

4 可視化

4.1 ダッシュボード

4.1.1 可視化のためのダッシュボードの作成

  1. サイドメニューの ''+" のアイコンの上にマウスカーソルをかざして、 Dashboard をクリックします。

    デフォルトのダッシュボードの作成
  2. New dashboard 画面のAdd panel の領域で Add an empty panel の四角部分をクリックします。

    空のパネルの作成
  3. Edit panel 画面で、 画面下部の Query のタブを選択後、 GridDBのデータソースの追加の項で追加したデータソースを選択します。

Selecting the data source
  1. Query 部分で、ドロップダウンリストからコンテナと時間カラムを選択します。
コンテナ選択のクエリ
カラム選択のクエリ
  1. クエリに条件を追加します。

    条件用のカラムの追加
    演算条件の追加
    被演算子の追加

    📝 condition セクションの "+" ボタンをクリックすると、さらに条件を追加できます。

  2. データを表示する時間範囲を選択します。

    時間範囲の選択
  3. 下に示すように、グラフのスタイルを選択することもできます。

    グラフのスタイルの選択
  4. クエリを追加し終えると、次のようなダッシュボードが表示されます。

    クエリ追加後のダッシュボード

    📝 クエリを編集するたびに グラフは追加の操作なしに自動的に更新されます。

  5. 下に示すように、ALIASED BY のテキスト領域にユーザ定義の値を入力すると、表示される凡例を変更できます。

    alias(別名)を指定したクエリ

    使用できる特殊変数については、 データフィールドごとの特殊なクエリ式の利用可否の表の Edit Panel画面のALIASED BYフィールド の列を参照。

  6. Apply ボタンをクリックしダッシュボードを保存します。ユーザは変数画面にリダイレクトされ、グラフが指定したとおりに表示されます。

ダッシュボード
  1. Save ボタンをクリックし、ダッシュボードを保存します。

4.1.2 追加設定

可視化のためのダッシュボードの作成の項で説明したように、可視化のためにダッシュボードを作成する以外に、構成を追加することにより、変数 を用いてより対話的・動的なダッシュボードを作成できます。

4.1.2.1 変数

変数は値のプレースホルダです。変数はメトリックのクエリとパネルのタイトルに使用できます。

詳細は Grafanaの変数を参照。

データ可視化用の変数

4.1.2.1.1 変数の設定
  1. 任意のパネルを開き、トップ画面の Settings ボタンをクリックします。

  2. サイドメニューの Settings の下の Variables というリンクをクリックします。

  3. + Add variable ボタンをクリックします。

  4. Edit画面のQueryフィールドにクエリを入力します。その際、次の3つの定義済みのパラメータを使うことができます。

    1. パラメータを使って全コンテナを取得する場合、$griddb_container_listの形式を用います。
    2. パラメータを使って特定のコンテナの全カラムを取得する場合、$griddb_column_list({container name})の形式を使います。
    3. パラメータを使って特定のコンテナのデータを取得する場合、 $griddb_query_data({container name}, {columns}, {TQL})の形式を使います。
  5. クエリ結果が Preview of values の領域に表示されます。

    • $griddb_container_list
    コンテナ一覧用の変数
    • $griddb_column_list({container name})
    コンテナ'grafana'のカラム一覧用の変数
    • $griddb_query_data({container name}, {columns}, {TQL})
コンテナ'grafana'内のデータ(col1)用の変数

📝 Multi-valueInclude all options の2つのオプションを構成できます。Multi-value を有効にすると、チェックボックスをチェックすることにより、複数の値を選択できます。また、 Include all options を有効にすると、"All"のチェックボックスをチェックすることですべてのチェックボックスを自動的に選択できます。

  1. Update ボタンと Save As ボタンをクリックし、変数を保存します。

    UpdateボタンとSave Asボタンのクリック後
  2. Save dashboard as... ダイアログで dashboard name(ダッシュボード名) を入力し、folder(フォルダ) (デフォルトはGeneral)を選択します。ダッシュボードにフォルダを作成するには、 How To Create A Folder(フォルダの作成方法)を参照。

    Save dashboard as...ダイアログ
  3. Save ボタンをクリックします。上記で作成した変数でダッシュボードが作成されます。

4.1.3 変数を用いたデータの可視化

  1. 変数の設定の項で変数が問題なく作成された場合、ユーザは作成した変数の画面にリダイレクトされます。

    変数画面
  2. 画面上部右側の赤で囲んだ Add panel ボタンをクリックします。

    変数用のパネルの追加
  3. 可視化のためのダッシュボードの作成 の項の手順2と手順3を行います。

  4. 変数の設定の項で作成したコンテナの変数を1つ選択します。

    コンテナの変数の選択
  5. 下に示すように時間カラムを選択します。

    時間カラムの選択
  6. グラフに表示されたデータを制御するためには、CONDITION領域に1つ以上の条件を追加します。CONDITION条件にはこれまで作成した変数を指定できます。ただし、制約により変数は手動で入力する必要があります。ドロップダウンリストから選択することはできません。

    変数を用いた条件の追加
  7. グラフ上にあるリストの具体的な値を指定し、変数に反映します。

    具体的な値と変数の間の関係

4.1.3.1 アノテーション

可視化のためのダッシュボードの作成の項で説明したように、可視化のためにダッシュボードを作成したり、変数を用いてデータを可視化する以外に、アノテーションを設定して、グラフ上の点に豊富なイベントのマークを付けることができます。アノテーションにマウスカーソルをかざすと、イベントの説明とイベントタグを取得できます。テキスト領域には詳細がわかる他システムへのリンクが含まれている場合もあります。

詳細は Grafanaのアノテーションを参照。

4.1.3.1.1 アノテーションの設定
  1. 任意のパネルを開き、トップ画面の Settings ボタンをクリックします。

  2. サイドメニューの Settings の下の Annotations というリンクをクリックします。

  3. + Add Annotation Query ボタンをクリックします。

  4. 現在、GridDB入力プラグインは、annotationregion annotation の2つのアノテーションに対応しています。region annotationは複数の時間カラム(例:Multiple_Time_Columns)を持つコンテナに使用します。

    4.1. 次のデータを入力し annotation を作成します。

    annotationの作成

​ 4.2. 次のデータを入力し region annotation を作成します。

region annotationの作成

動的なクエリを作成するためにクエリのフィールドに追加できる引数については付録を参照。

クエリのフィールドに引数を追加
  1. Save As... ボタンをクリックし、アノテーションを作成します。

  2. 変数の作成方法と同様の要領で Save dashboard as... ダイアログでダッシュボード情報を追加し、Save ボタンをクリックし、ダッシュボードを保存します。

  3. ダッシュボードを保存後、上記で作成したアノテーション付きのダッシュボードが作成されます。

ダッシュボード設定を完了後、サイドメニューの Dashboardsリンクの下の Manage というリンクをクリックします。Manage タブの下に、設定したダッシュボードの一覧を表示した画面が表示されます。

ダッシュボード管理
4.1.3.1.2 アノテーションを用いたデータの可視化
  1. アノテーションの設定の項でアノテーションが問題なく作成された場合、ユーザは作成したアノテーションの画面にリダイレクトされます。

  2. ドロップダウンリストからコンテナを選択し、下記に示すように Add panel ボタンをクリックします。

    アノテーション画面
  3. アノテーションパネルが表示されます。前の項でクエリを追加したのと同様の要領で、データの可視化のためにクエリを追加します。

    アノテーションパネル
  4. 次のアノテーション画面が表示されます。

グラフ付きのアノテーション画面

4.2 探索

  1. Explore 画面は2つ(1.1.と1.2.)アクセス方法があります。

    1.1. サイドメニューの Explore をクリックします。

    サイドメニューのExploreをクリック

    システムは次のようにデータを選択しない状態の画面を表示します。

    サイドメニューからのExplore画面

    1.2. 可視化用の変数またはアノテーション画面で Panel Title のドロップダウンリストの中の Explore のオプションをクリックします。

    可視化画面からのExplore画面

    すると、システムは、現在選択されている可視化ダッシュボードから取得した時間範囲とともにExplore画面を表示します。

    可視化ダッシュボードから取得した時間範囲付きのExplore画面
  2. 可視化のためのダッシュボードの作成の項の手順4、手順5、手順7でクエリを追加したのと同様の要領でクエリを追加します。

Explore画面でのクエリの追加
  1. Run query ボタンをクリックし、データを更新します。

  2. 以下のExplore可視化画面が表示されます。

Explore可視化画面

5 関連コンテンツ

該当なし

6 付録

6.1 特殊なクエリ式

クエリに次のような特殊な式を使って動的クエリを作成できます。

6.1.1 利用可能な特殊なクエリ式

名称 説明
特殊変数: 次のシンタックスはGrafana用GridDB入力プラグインで定義される特殊な値で置換されます。
$__timeFrom

ダッシュボードの現在の時間範囲の開始時間

置換後:

TIMESTAMP({Dashboard start time})

📝 : 現在の時間範囲はダッシュボードの上部右側にあります。

$__timeTo

ダッシュボードの現在の時間範囲の終了時間

置換後:

TIMESTAMP({Dashboard end time})

📝: 現在の時間範囲はダッシュボードの上部右側にあります。

$__col aliasのパターンに使用されます。特定のカラム名で置換されます。
$__container aliasのパターンに使用されます。特定のコンテナ名で置換されます。
$__interval

マクロ $__timeSampling でのみ利用されます。

この変数の値はダッシュボードの時間範囲に応じて自動的に変化します。

例:

ダッシュボードが1年分のデータを表示する場合、 $__interval = 1 day となります。

ダッシュボードが1日分のデータを表示する場合、 $__interval = 1 minute となります。

この変数の下限は $__minInterval 変数で指定します。

クエリに使用した場合、この変数はGrafanaの時間範囲で置換されます。

📝: Grafanaのtime interval(時間間隔)はダッシュボードの上部右側の現在の時間範囲に応じて自動的に変化する自動オプションです。

$__minInterval $__interval変数の下限。Create Data Source画面で定義されます。
変数: 次のシンタックスはユーザが定義するカスタム変数の値で置換されます。
${variable name} 変数の現在の値で置換されます。
マクロ: 次のシンタックスはTQL式で置換されます。
$__timeFilter

データを制限するために使います。

置換後の条件式:

{time column} > $__timeFrom AND {time column} < $__timeTo

$__rangeFilter

region annotationでデータを制限するために使います。

region annotationにのみ使用します。置換後の条件式:

({start time column} > $__timeFrom AND {start time column} < $__timeTo) OR

({end time column} > $__timeFrom AND {end time column} < $__timeTo)

$__timeSampling({column name}, {time interval})

この変数は全期間ではなく、ある期間分のサンプルデータを表示するために使います。

置換後の条件式:

TIME_SAMPLING ({column name}, $__timeFrom, $__timeTo, {time interval value}, {time interval unit})

{time interval} の入力はGrafanaのtime intervalの値によって決まります。

6.1.1.1 データフィールドごとの特殊なクエリ式の利用可否

下表にデータフィールドごとのクエリ式の利用可否を示します。

Edit Panel画面のALIASED BYフィールド Edit Variables画面のQueryフィールド Edit Annotation画面のQueryフィールド
$__timeFrom - x x
$__timeTo - x x
$__col x - -
$__container x - -
$__interval - x x
$__minInterval - x x
ユーザが作成した変数:
/^${variable name}$/
- x -
$__timeFilter - - x (1)
$__rangeFilter - - x (2)
$__timeSampling({column name}, {time interval}) - x x

(1): 単一のannotation(アノテーション)付きのクエリに使用します。データを制限するためには$__timeFilterを常に使用する必要があります。
(2): region annotation付きのクエリに使用します。 データを制限するためには $__rangeFilterを常に使用する必要があります。