翻译 Tim Rose 的kibana插件教程一基础篇

kibana官方没有插件的开发教程，Tim Rose的教程写的十分详尽，也是官方推荐的。由于这个系列的教程是英文版的，且基于kibana4，近日需要做kibana的开发，硬啃下这些教程之后，虽然这些教程比较古老，很多代码不能用了，但是开发思想还是通用的。记录下来，留下个爪。由于本人水平有限，错漏的地方欢迎大家指出。

原文链接：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和加载文件，这个在下面不再重复说了。准备好来写一个可视化插件了吗，跳到第二节吧。