翻譯 Tim Rose 的kibana外掛教程

atxiaoxian發表於2019-04-08
ROS

kibana官方沒有外掛的開發教程，Tim Rose的教程寫的十分詳盡，也是官方推薦的。由於這個系列的教程是英文版的，且基於kibana4，近日需要做kibana的開發，硬啃下這些教程之後，且根據kibana6.3.2版本做了些改進，記錄下來，留下個爪。由於本人水平有限，錯漏的地方歡迎大家指出。

原文連結：www.timroes.de/writing-kib…

原文標題： Writing Kibana 4 Plugins – Basics

基礎篇

自從kibana4.2.0之後，自定義外掛（或其他型別的外掛）可以由廣大開發者自己來開發並且使用。本系列教程會帶領你寫下你第一個外掛，也會介紹一些比較有意義和有擴充套件性的外掛，例如自定義的視覺化外掛，新版帶有的app外掛（自4.2.0以後，在他的架構當中，那個你熟知的，人見人愛的kibana也是一個app外掛），或者加一些新的tabs到視覺化的視察視窗。

巨大的warning

kibana提供安裝外掛的介面，自4.2.0之後，但是沒有提供對應的開發api。不管怎麼樣吧，他們還是很推薦自定義外掛的，所有我寫了這個教程。由於這裡，對於公開和私有api沒有明顯的的區分，開發的外掛可能會和版本補丁有衝突。他們會修改一些你已經用了的服務，所以要記住，你開發的每一個外掛都是對應一個特定版本的kibana的，使用前要對每個版本進行相容性測試。關於公開api的討論，你可以在github issue裡面找到。本教程不會對最新的kibana做測試。如果你發現了一些最版的變化，歡迎在討論區指出。

本教程（編寫普通的kibana外掛）需要你有一定的web開發基礎，以下的一些基礎技能會在本文用到，且不會解釋：

  • JavaScript 開發（npm lodules ...）
  • angularjs
  • webpack

這是本系列的第一篇，包括一些構建開發環境，和各類基礎外掛的架構的知識。在閱讀其他型別外掛開發的時候，你應該先閱讀這個基礎部分。

構建開發環境

更新：kibana官方的人搞了一個開發環境構建的視訊 （注：需要科學上網）

  1. 下載kibana 你需要一個本地的開發環境來開發kibana外掛。在生產環境下，熱更新服務是不可用的。你需要下載你想要的版本的kibana原始碼，利用git來checkout對應的tag，或者選擇對應的tag之後下載相應的zip檔案。
  2. 安裝依賴 下載完原始碼之後，執行yarn kbn bootstrap 來安裝依賴
  3. 啟動對應的elasticsearch 除了需要啟動kibana也需要啟動一個elasticsearch讓kibana來連線。任意啟動的elasticsearch都是一個選擇（可以通過配置config/kibana.yml裡的url欄位來配置）。另外一個選擇是在kibana的開發環境啟動一個elasticsearch，這樣做有一個優勢，就是kibaa知道他自己需要一個什麼版本的elasticsearch，他會自動啟動正確的版本。在kibana目錄下執行以下命令來啟動elasticsearch：
 > npm run elasticsearch
複製程式碼

這個命令執行起來需要一定時間，需要去下載對應的elasticsearch和執行起來，等命令結束，你會看到輸出一個表格顯示埠號和族群名稱。 4. 啟動kibana 上面步驟執行成功之後，就可以在kibana原始碼的資料夾下啟動kibana啦，執行：

> yarn start
複製程式碼

這個命令會啟動開發模式的kibana，在你修改外掛程式碼的時候，會自動過載。啟動的過程會需要幾分鐘，當你看到‘Lazy optimization success’，他就啟動成功了。

外掛的原始碼應該放在plugins目錄下，kibana會自動監聽這個目錄的修改，注意： 這個不能夠把原始碼用符號連結到這個目錄下，因為依賴追蹤的問題。一定要把原始碼放在這目錄下。

在plugins目錄下建立一個資料夾，資料夾的名字就是你外掛的名字，這個在下面章節會詳細說到。

每次你修改外掛的原始碼，kibana會自動重新打包和優化原始碼，這會需要一定的時間（簡單的外掛，如本文建立的外掛，大概是10s左右）一旦打包成功，你會看到以下的訊息列印出來。

restarting server due to changes in
 - "installedPlugins/tr-k4p-clock/index.js"
server log [21:49:59.323] [info][status][plugin:tr-k4p-clock] Status changed from uninitialized to green - Ready
[...]
server log [21:49:59.421] [info][listening] Server running at http://0.0.0.0:5601
optmzr log [21:50:07.177] [info][optimize] Lazy optimization started
optmzr log [21:50:13.834] [info][optimize] Lazy optimization success in 6.66 seconds
複製程式碼

當lazy optimization 成功的時候，程式碼修改就知道生效了。重新整理瀏覽器就能看見你的修改了。有時候kibana沒辦法自動過載修改，手動殺死再重啟（可能需要兩分鐘）可能會解決你的問題。

外掛基礎

每一個外掛都是一個npm模組，所以他至少需要兩根檔案。

在外掛的根目錄下，需要有一個package.json檔案，說明這是一個npm package檔案，你至少還需要指定一個外掛名稱，指明版本號，也是一個不錯的選擇，我們第一個外掛的包檔案，可能會像以下檔案一樣：

{
  "name": "tr-k4p-myplugin",
  "version": "0.1.0"
}
複製程式碼

在package.json裡面的name欄位一定要跟你的外掛所在的資料夾的名稱一致（事實上，可以不一致，但是當兩者不一致的時候，到最後你可以會搞不清楚上面時候用資料夾名稱，什麼時候用package name欄位，安裝那些不遵守這些規則的外掛，可能會導致事情變得複雜和容易混淆，所以我非常推薦package的name欄位魚資料夾的名稱一致）。

第二個必須的檔案是模組的主檔案，一定要命名為index.js，除非你在package.json檔案內指定檔名稱，這就是npm模組需要的全部東西了，他設定好了你外掛所需要的全部東西。在檔案裡，你可以得到一個kibana物件的引用，外掛一定要新例項化一個外掛物件，如下：

module.exports = function(kibana) {
  return new kibana.Plugin({
    // Your plugin configuration
  });
};
複製程式碼

這兩個檔案組成了最簡單的外掛，kibana可以載入這個外掛，但是目前為止，這個外掛啥也沒做。在接下來的教程中，我們會教你如何往外掛的index.js(以及其他檔案)裡面填寫東西，讓你的外掛活起來。

除了以上兩個檔案，大部分外掛在根目錄下還有一個資料夾叫public，不在伺服器端跑的，而被傳送到客戶端執行的全部檔案都會放在這個資料夾下。

Package/Plugin Name

package ID/name都應該是全域性唯一的，他會被kibana用來載入的外掛檔案，不能和其他外掛相沖突，所以我推薦用特定的字串做字首，這就定義了這個外掛屬於你或者你的組織，我一般使用 tr-k4p (for Tim Roes, Kibana 4 Plugin)，作為字首，在本教程的大部分地方。

Yeoman 生成器

有一個Yeoman 生成器可以幫助你來啟動你的kibana外掛，你可以在npm package的 generator-kibana-plugin找到他，我們強烈推薦你使用這個生成器。我們在這個階段不使用生成器的原因是，我需要詳細介紹每個檔案，並寫一些簡單的程式碼，以後你應該使用這個生成器。

獲得使用指南，請瀏覽npm 頁面，npm page。

因為在最新的版本中，使用生成器會自動建立打包任務，自動來啟動你的kibana例項。所以如果你使用生成器，就跳過上面步驟4，不要啟動你的kibana。

釋出和安裝外掛

即使你的外掛現在啥也不幹，他包含了能被載入到kibana的最少程式碼。

在開發的過程中，你不用安裝你的外掛，因為我們工作在plugins目錄下，一旦你完成你的外掛，你可能需要把外掛安裝在一些kibana例項上。

釋出外掛，你只需要把你的目錄內容打包成zip檔案。

node_modules 如果你的package.json檔案需要執行時依賴，你需要打包這些依賴（例如，適當的node_mudules的子目錄）進入zip檔案，如果你使用上述的生成器，你可以執行npm run build來打包生成一個boundled zip 檔案。

你要使這個zip檔案處於可用狀態，然後執行如下命令安裝進你的kibana例項：

bin/kibana plugin --install plugin-name -u https://url.to/plugin
複製程式碼

url也可以指定為本地檔案路徑，從本地資料夾安裝外掛。

不同型別的外掛

外掛可以從不同角度來擴充套件kibana，一個外掛可以從一個或多個擴充套件點，來提供新的功能。最常用的擴充套件點如下：

  • visTypes -新增新的視覺化型別到kibana
  • apps -kibana可以新增一個完全獨立的app，用來提供新的功能，一個著名的例子就是timelion，kibana的時間序列生成器，是一個kibana內部的app。
  • fieldFormatter -新增新的欄位格式化工具到kibana
  • 其他

本教程主要專注於新增新的視覺化外掛，如果你需要新增別的擴充套件點外掛，我推薦你看其他外掛的原始碼來學習（kibana的core plugins也有一些值得學習的），這些跟你需要做的外掛會很相似。

下一步

在接下來的教程中，我們會展示不同型別的外掛，和建立一些有意思的外掛。接下來章節你會看到的外掛，全部都包含上面提到的package.json和載入檔案，這個在下面不再重複說了。準備好來寫一個視覺化外掛了嗎，跳到第二節吧。

相關文章