一文教你如何發揮好 TDengine Grafana 外掛作用

作為當前流行的圖形化運維監控解決方案之一，Grafana 提供了一個靈活易用的介面，可以連線多種不同的資料來源，包括時序資料庫（Time Series Database）、雲服務、監控系統等，然後從這些資料來源中提取資料並實時地將其視覺化。為了給使用者打造更豐富的視覺化方案，TDengine 在開源不久就提供了對 Grafana 的支援，此後也在不斷升級改造 TDengine Grafana 外掛，還推出了基於 Grafana 的零依賴監控解決方案 TDinsight。本篇文章將以 tdengine-datasource 為例介紹 Grafana 外掛開發。

實際上，tdengine-datasource 是 TDengine 為 Grafana 打造的 datasource 外掛，它能夠從 TDengine 讀取資料，並展示到 Grafana。

開發環境準備

• Grafana
• go
• Mage
• nodejs
• yarn

Grafana 配置

首先下載 Grafana 並解壓，修改 conf/default.ini 配置。

• 修改外掛載入路徑。Grafana 外掛會預設載入在 plugins = data/plugins，這裡需要修改為自己外掛的地址。這裡通常改為外掛專案下的 dist 目錄。

[paths]
plugins = /path/to/Grafana-plugins

• 修改 allow_loading_unsigned_plugins 配置，配置項的值為外掛的名字，允許 Grafana 載入 unsigned 的外掛。

allow_loading_unsigned_plugins = my_plugin_name

新建外掛

使用 grafna-create-plugin 建立外掛，然後根據提示新建外掛。

$ npx @Grafana/create-plugin
? What is going to be the name of your plugin? my-plugin # 輸入外掛名字
? What is the organization name of your plugin? taosdata # 輸入公司名字
? How would you describe your plugin? my testing plugin # 輸入外掛描述
? What type of plugin would you like? datasource # 選擇外掛型別 app or panel or datasource
? Do you want a backend part of your plugin? Yes # datasource 型別外掛是否包含後端
? Do you want to add Github CI and Release workflows? Yes # 是否新增 github ci 和 release 工作流
? Do you want to add a Github workflow for automatically checking "Grafana API compatibility" on PRs? Yes # 是否新增 pr 工作流

之後 grafna-create-plugin 會在目錄建立名為 taosdata-myplugin-datasource 的外掛工程。進到該目錄之後，執行 yarn install && yarn build && go mod tidy && mage -v build 即可構建外掛。啟動 Grafana，在 datasource 配置頁面就可以搜到該外掛，外掛的前端程式碼在 src 目錄，後端程式碼在 pkg 目錄。

後端程式碼

後端程式碼需要實現 QueryDataHandler 介面和 CheckHealthHandler 介面，分別用於查詢資料和 checkHealth。

頁面查詢資料時會呼叫 QueryData 方法。不同的資料來源，QueryData 方法實現會有差異，歸根結底，該方法的作用是從資料來源查詢資料，並將資料封裝成 Data Frame。

type QueryDataHandler interface {
   QueryData(ctx context.Context, req *QueryDataRequest) (*QueryDataResponse, error)
}

Grafana 會定時呼叫 CheckHealth 方法，以檢測外掛的健康狀態。資料來源配置頁面的 Save & Test 按鈕也會呼叫 CheckHealth 方法來檢測配置是否正確。

type CheckHealthHandler interface {
   CheckHealth(ctx context.Context, req *CheckHealthRequest) (*CheckHealthResult, error)
}

前端程式碼

grafana datasource plugin 需要有一定的前端程式碼開發量，包含 datasource、資料來源配置頁面和資料查詢頁面。

datasource-with-backend 外掛，datasource 的前端程式碼需要實現（extends）DataSourceWithBackend 介面。由於透過後端介面進行資料查詢，所以前端頁面程式碼比較簡單。

datasource-backend 外掛，datasource 的前端程式碼需要實現（extends）DataSourceApi 介面，並至少實現 query、testDatasource 等方法。其中 query 方法用於資料查詢，testDatasource 方法用於測試資料來源配置。

async query(options: DataQueryRequest<MyQuery>): Promise<DataQueryResponse>
async testDatasource()

資料來源外掛需要配置資料來源地址、授權等資訊，通常還需要配置資料查詢方式，因此需要資料來源配置頁面和資料查詢頁面。

plugin.json 和 module.ts

如果是透過 grafna-create-plugin 建立的外掛專案，grafna-create-plugin 會在 src 目錄下生成 plugin.json 和 module.ts 檔案。其中 plugin.json 包含了外掛的資訊，包括外掛型別、外掛名字、ID 等。而 module.ts 是 grafana 外掛的入口。

Grafana 和 backend plugin 通訊協議

Grafana 和 backend-plugin 是兩個程式，plugin 是 Grafana 的子程式，二者透過 gRpc 通訊，plugin 作為 server 端，Grafana 作為 client 端。

其 gRpc 通訊協議，從協議上看，backend-plugin 提供瞭如下 service：

//---------------------------------------------------------
// Resource service enables HTTP-style requests over gRPC.
//---------------------------------------------------------
service Resource {
  rpc CallResource(CallResourceRequest) returns (stream CallResourceResponse);
}
//-----------------------------------------------
// Data
//-----------------------------------------------
service Data {
  rpc QueryData(QueryDataRequest) returns (QueryDataResponse);
}
//-----------------------------------------------
// Diagnostics
//-----------------------------------------------
service Diagnostics {
  rpc CheckHealth(CheckHealthRequest) returns (CheckHealthResponse);
  rpc CollectMetrics(CollectMetricsRequest) returns (CollectMetricsResponse);
}
//-----------------------------------------------------------------
// Stream -- EXPERIMENTAL and is subject to change until 8.0
//-----------------------------------------------------------------
service Stream {
  // SubscribeStream called when a user tries to subscribe to a plugin/datasource
  // managed channel path – thus plugin can check subscribe permissions and communicate
  // options with Grafana Core. When the first subscriber joins a channel, RunStream
  // will be called. 
  rpc SubscribeStream(SubscribeStreamRequest) returns (SubscribeStreamResponse);
  // RunStream will be initiated by Grafana to consume a stream. RunStream will be
  // called once for the first client successfully subscribed to a channel path.
  // When Grafana detects that there are no longer any subscribers inside a channel,
  // the call will be terminated until next active subscriber appears. Call termination
  // can happen with a delay.
  rpc RunStream(RunStreamRequest) returns (stream StreamPacket);
  // PublishStream called when a user tries to publish to a plugin/datasource
  // managed channel path. Here plugin can check publish permissions and
  // modify publication data if required.
  rpc PublishStream(PublishStreamRequest) returns (PublishStreamResponse);
}

grafana backend-plugin 實現依賴 go-plugin 庫，go-plugin 是一個基於 gRpc 的golang 外掛系統，由 HashiCorp 開發，並在業界廣泛使用，grafana backend plugin 就是基於 go-plugin 實現的。

tdengine-datasource

tdengine-datasource 是 TDengine 的 grafana 資料來源外掛。目前，tdengine-datasource 不完全是一個 backend-plugin，TDinsight 或 dashboard 的資料仍然是透過前端頁面直接查詢，只有後端 alerting 的查詢請求會經過後端。

ConfigEditor

在資料來源配置頁面可以配置資料來源的資訊。新增資料來源時，需要配置資料來源的名字（預設為 TDengine Datasource）、TDengine 的地址、認證資訊，透過 Save&test 按鈕，可以校驗 TDengine 的認證資訊。

QueryEditor

在查詢配置頁面可以自定義資料查詢，包含查詢 sql、時間戳偏移配置、group by 配置等。

結語

現在你可以操作體驗了，希望本篇文章能帶給你一些幫助。 

如果在使用 TDengine Grafana 外掛的過程中遇到任何問題，或者有新的功能建議，也歡迎新增 小T vx：tdengine，和 TDengine 的技術研發人員進行直接溝通。