编写插件¶

插件分为两种，一种接受参数，另外一种不接受。

带参数的插件¶

所有接受参数的插件都在 plugin 目录里，命名需要跟报告的 metric 一致，比如 plugin/net.port.listen 会上报 net.port.listen 这个 metric 。接受参数的插件需要在在运行的时候通过 stdin 读取 json 格式的参数：

[
  {"_metric": "net.port.listen", "_step": 30, "port": 6379},
  {"_metric": "net.port.listen", "_step": 30, "port": 3306}
]

警告

注意这里是 object 列表，不是单一的 object

参数是在规则配置中指定的，比如

(def mysql-and-redis-rules
  (where (host "mysql-and-redis-host")
    (plugin "net.port.listen" 30 {:port 3306})
    (plugin "net.port.listen" 30 {:port 6379})
    (your-other-rules ...)))

这里 plugin 的参数分别是插件名字、采集周期(step)、插件的参数。采集周期如果是 0 则代表这个插件是持续运行的，agent 不会设置超时时间将插件杀死。插件名字和采集周期会在参数里以 _metric 和 _step 作为 key 传递进去。

之后，插件需要输出如下格式的 json :

[
  {
    "endpoint": "mysql-and-redis-host",
    "metric": "net.port.listen",
    "value": 1,
    "timestamp": 1431349763,
    "tags": {"port": "3306"}
  },
  {
    "endpoint": "mysql-and-redis-host",
    "metric": "net.port.listen",
    "value": 0,
    "timestamp": 1431349763,
    "tags": {"port": "6379"}
  }
]

插件参数（比如上个例子中的 port ）可以任意添加。

警告

注意这里是 object 的 list，不是单一的 object。

文档中为了清晰，json 是多行的，实际编写插件的时候 同一个 list 请保持单行输出 ，因为 Satori 接受多行的输出（每一行是一个 list），需要通过换行来作为边界。

Key	Value
endpoint	可选 [1] ，机器名，在 riemann 对应事件的 `:host` 。
tags	可选 [2] ，标签。在 riemann 中会直接附加到 event 上。
timestamp	时间戳，事件发生的时间，以秒为单位的 UNIX 时间戳。
metric	监控项的名字。在 riemann 中对应事件的 `:service` 表示。
value	监控项的值。在 riemann 中对应事件的 `:metric` 。

[1]	缺失则 agent 会按照自身配置填充这个值。如果不需要控制这个值推荐省略让 agent 填充。

[2]	缺失则不会附加额外的 tag 。

注解

插件的输出格式基本与 Open-Falcon 的插件格式相同，但是 tags 是个 object，不是拼接的字符串。

插件中的 Key 跟 riemann 中对应不上是一个比较恼人的坑，需要特别注意。

无参数的插件¶

无参数插件的命名需要类似于 30_nginx.py 这样的， _ 前面需要是数字，表示采集的周期。采集周期如果是 0 则代表这个插件是持续运行的，agent 不会设置超时时间将插件杀死。插件输出的格式跟跟带参数插件格式一致（上面的 json）。

之后可以在规则中配置使用这个插件（假设你把这个插件放到了 plugin/nginx 目录）

(def some-nginx-related-rules
  (where (host "nginx-machine")
    (plugin-dir "nginx")
    (your-other-rules ...)))

持续输出的插件¶

插件可以输出多行 json，输出的 json 会马上被 agent 收集起来并上报。

此类插件可以将采集周期 step 设置成 0 ，agent 会认为插件没有超时时间，并且只会在插件失败后才会重新调度。