【 Grafana 】よくわかるGrafana応用【バックエンドプラグイン開発編②】

2023.08.02 Grafanaコラム

はじめに

Grafanaでプラグインを作成するための開発環境作成というトピックで、当社のエンジニアがSIOS Tech.Labに記事を投稿しましたので、こちらでもご紹介します。
業務で行ったGrafanaのプラグイン開発の際の知見を共有してくれています。

Grafana plugin開発がテーマの記事は、以下のように2部構成になります。今回は開発編です。

環境構築編
開発編　←　今回はこちら

はじめに
そもそもGrafanaデータソースバックエンドプラグインって？
- バックエンドデータソースプラグインでしかできないこと
今回の内容
おわりに

そもそもGrafanaデータソースバックエンドプラグインって？

ここで改めて、Grafanaのデータソースバックエンドプラグインってそもそもなんなのか、振り返ってみましょう。

Grafanaでは、パネル・アプリ・データソース・バックエンドの4種類のプラグインを作成することができます。この機能によりユーザーは、社内独自のデータソースを使用したり、斬新な方法でデータを視覚化したり、Grafanaに自分好みのカスタマイズを行うことができます。Grafanaのそれぞれのプラグインについての解説はこちらの記事にもありました。

データソースバックエンドプラグインは、ここでいう4つのプラグインのうち、バックエンドプラグインのことを指します。データソースプラグインにバックエンド部があるバージョンだから「バックエンドデータソースプラグイン」であり、省略してバックエンドプラグインとも呼ばれています。公式のドキュメントでも「Backend plugin」と略されています。

では、通常のデータソースプラグインとバックエンドプラグインは何が違うのか、なぜ違うのか、疑問に思う方もいるかもしれません。通常のデータソースプラグインはフロントエンド、Grafanaが動いているサーバではなくGrafanaにアクセスしているブラウザ側で動作するのに対し、バックエンドプラグインはgoで実装されるバックエンドを持ちます。ブラウザで実行される通常のデータソースプラグインには実現できない処理があり、そのために、バックエンドコンポーネントで拡張した「バックエンドプラグイン」が存在しています。以下に、バックエンドデータソースプラグインでしかできないことを挙げています。

バックエンドデータソースプラグインでしかできないこと

データを収集しアラートを飛ばす
SQLサーバなどHTTP通信でないデータソースへのアクセス
データのキャッシュをユーザ間で共有
Grafana標準でサポートしていない認証方式などの利用
ユーザに公開したくない認証情報やアクセス先などの保持
フロントエンド部からバックエンド部へのGrafana標準では実現できない通信。

今回の内容

今回は、以下の流れでGrafanaのデータソースバックエンドプラグイン開発のディレクトリ構成の説明と開発について説明していきたいと思います。詳細の実際のデータソースと繋げていく部分については、今回は割愛します。開発環境の作成については前回の記事で作成した環境を使用しています。

ディレクトリ構成
フロントエンドの開発
バックエンドの開発

ディレクトリ構成

前回の記事の最後でVS CodeにSSH接続を行って、プラグインディレクトリを開くことができました。作成されたプラグインの構成を改めて確認しましょう。

このプラグインのビルド、デプロイなどの方法や、テストの一般的な方法などについてREADME.mdに記載があるので、一度目を通してみて下さい。必要なビルド&デプロイ方法については本記事でも説明します。

Grafanaのbackend datasource plugin 開発において主に編集することになる部分を、以下に列挙します。パスは、プラグインディレクトリ配下の相対パスです。

srcディレクトリ – フロントエンド関連ディレクトリ
- src/components/ConfigEditor.tsx – データソース設定画面
- src/components/QueryEditor.tsx – クエリ設定画面
- src/types.ts – データソースプラグインで扱う項目のtype定義
pkgディレクトリ – バックエンド関連ディレクトリ
- pkg/main.go – バックエンドのエントリポイント
- pkg/plugin/datasource.go – プラグインのバックエンド部コード
- pkg/plugin/datasource_test.go – プラグインのバックエンド部テストコード

フロントエンド部の開発

データソース設定画面

データソース設定画面は、データソースを追加する際、データソースへの接続のために必要な情報を入力する画面です。ひな形として生成されたプラグインでは、下記画像のような表示となっています。

データソース設定画面の編集、ビルド、反映

ここで、データソースのPathという項目をURLに編集して、ビルド & デプロイしてみましょう。

データソース設定画面の項目を変更したり追加したりするためには、src/components/ConfigEditor.tsx を編集します。このファイルはReactコンポーネントとして編集できます。また、項目自体を追加する際は、src/types.tsにもtype定義を追加する必要があります。

ConfigEditor.tsxに変更を加えました。以下は編集したConfigEditor.tsxの抜粋です。

~~~上略~~~
  return (
    <div className="gf-form-group">
// Labelを"Path"から"URL"に変更
      <InlineField label="URL" labelWidth={12}>
        <Input
          onChange={onPathChange}
          value={jsonData.path || ''}
          placeholder="json field returned to frontend"
          width={40}
        />
      </InlineField>
~~~下略~~~

項目を編集したので、ビルドを行います。
フロントエンドのビルドは、下記のコマンドで行います。

# プラグインディレクトリに移動
cd ~/sios-myplugin-datasource
# 依存モジュールのインストール
yarn install
# プラグインのフロントエンド部のビルド
yarn build

また、ビルドしたプラグインをGrafanaのサーバに反映するためには、ビルドされたプラグインのディレクトリ(/dist)をGrafana内のプラグイン配置用ディレクトリに配置し、サーバを再起動する必要があります。（これはバックエンドプラグインのビルド後も同様）

今回は、環境構築編で作成した環境で、プラグインの再配置を行うコマンドを示します。

# プラグインディレクトリに移動
cd ~/sios-myplugin-datasource
# コンテナ内Grafanaサーバのプラグイン配置用ディレクトリにマウントしたディレクトリの不要なディレクトリを削除し、新たにビルドされたプラグインディレクトリを配置
# その後、dockerで建てたGrafanaサーバを再起動する
sudo rm -rf /opt/grafana-plugins/sios-myplugin-datasource && sudo cp -R ./dist /opt/grafana-plugins/sios-myplugin-datasource && sudo docker restart grafana

ビルドされると、Grafanaサーバに変更が反映されます。ラベル内の文字がPathからLabelに変更されていることが確認できました。

クエリ設定画面

クエリ設定画面は、ダッシュボードの画面でクエリを選択するための画面で、以下画像下方の入力エリアです。

この画面を編集するためには、src/components/QueryEditor.tsxやsrc/types.tsを編集します。編集・ビルド・プラグインの配置は、データソース画面の設定と同様の方法で行います。

grafana uiについて

UIを更にカスタマイズする際は、Grafana公式が公開しているGrafana UIというUIコンポーネントを利用することができます。StoryBookで見た目や挙動を確認し、様々なUIを使用可能です。

yarn watchについて

ここまで、フロントエンドの編集・ビルド・配置の方法を見て頂きました。しかし、編集を行うたびに毎回ビルドを行わないといけないのはかなり面倒ですよね。grafana-toolkitのwatch機能を使うと、自動的にフロントエンドの変更を開発用にビルドすることができ、変更をより早くブラウザでチェックすることができます。ビルドは自動で行われ、プラグインの配置を行うだけで、プラグインを反映させることができます。

ウォッチモードで開発用ビルドを行う
yarn dev -w

今回の環境ではinotifyの設定によりエラーが起きてしまったため、こちらのブログを参考にinotifyの監視対象ファイルの上限数を変更しました。

バックエンド部の開発

バックエンド部についてもフロントエンド部と同様に、変更を加えてビルドを行います。

バックエンド部の編集、ビルド、反映

pkg/plugin/datasource.go には、データソースが正しく動作しているかを確認するためのヘルスチェックが記載されています。ひな形で生成されたコードには、半分の確率でエラーが出るようにコードが書かれています。
今回は、エラー生成部分をコメントアウトで無効化してビルドします。
下記のようにpkg/plugin/datasource.goを編集します。

~~~上略~~~
// CheckHealth handles health checks sent from Grafana to the plugin.
// The main use case for these health checks is the test button on the
// datasource configuration page which allows users to verify that
// a datasource is working as expected.
func (d *Datasource) CheckHealth(_ context.Context, req *backend.CheckHealthRequest) (*backend.CheckHealthResult, error) {
	// when logging at a non-Debug level, make sure you don't include sensitive information in the message
	// (like the *backend.QueryDataRequest)
	log.DefaultLogger.Debug("CheckHealth called")

	var status = backend.HealthStatusOk
	var message = "Data source is working"

// 以下をコメントアウト (あわせて math/rand のインポートも削除)
//	if rand.Int()%2 == 0 {
//		status = backend.HealthStatusError
//		message = "randomized error"
//	}

	return &backend.CheckHealthResult{
		Status:  status,
		Message: message,
	}, nil
}

コードを編集したら、ビルドを行います。以下はビルドを行うためのコマンドです。今回はバックエンド部の編集を行いましたが、ヘルスチェック機能はフロントエンド部へも影響が及ぶため、フロントエンド部とバックエンド部の両方のビルドを行いました。

# プラグインディレクトリに移動
cd ~/sios-myplugin-datasource
# 依存モジュールのインストール
yarn install
# プラグインのフロントエンド部のビルド
yarn build
# プラグインのバックエンド部のビルド
mage -v

ビルドを行ったら、プラグインのフロントエンド部をビルドしたときと同様に、ビルドされたプラグインのディレクトリ(/dist)をGrafana内のプラグイン配置用ディレクトリに配置し、サーバを再起動する必要があります。私の環境では、以下のコマンドを叩きました。

# プラグインディレクトリに移動
cd ~/sios-myplugin-datasource
# コンテナ内Grafanaサーバのプラグイン配置用ディレクトリにマウントしたディレクトリの不要なディレクトリを削除し、新たにビルドされたプラグインディレクトリを配置
# その後、dockerで建てたGrafanaサーバを再起動する
sudo rm -rf /opt/grafana-plugins/sios-myplugin-datasource && sudo cp -R ./dist /opt/grafana-plugins/sios-myplugin-datasource && sudo docker restart grafana

Grafanaに反映されると、何度 [Save & test] を押してヘルスチェックを実行しても、**「Data source is working」**が表示されるようになり、変更が適用されたことが確認できました。