目錄
寫在最前：
自定義 push 數據到 open-falcon:
不僅僅是 falcon-agent 採集的數據可以 push 到監控系統，一些場景下，我們自定義的一些數據指標，也可以 push 到 open-falcon 中，比如：
- 線上某服務的 qps
- 某業務的在線人數
- 某個接⼝的響應時間
- 某個⻚面的狀態碼(500、200)
- 某個接⼝的請求出錯次數
- 某個業務的每分鐘的收⼊統計
- ......
注意, http request body 是個 json，這個 json 是個列表。
1、API 詳解
###API詳解
metric: 最核心的字段，代表這個採集項具體度量的是什麼, 比如是 cpu_idle 呢，還是 memory_free, 還是 qps
endpoint: 標明 Metric 的主體(屬主)，比如 metric 是 cpu_idle，那麼 Endpoint 就表示這是哪臺機器的 cpu_idle
timestamp: 表示彙報該數據時的 unix 時間戳，注意是整數，代表的是秒
value: 代表該 metric 在當前時間點的值，float64
step: 表示該數據採集項的彙報週期，這對於後續的配置監控策略很重要，必須明確指定。60 代表每分鐘上報一次
counterType: 只能是 COUNTER 或者 GAUGE 二選一，前者表示該數據採集項爲計時器類型，後者表示其爲原值（注意大小寫）GAUGE：即用戶上傳什麼樣的值，就原封不動的存儲
COUNTER：指標在存儲和展現的時候，會被計算爲 speed，即（當前值 - 上次值）/ 時間間隔
tags: 一組逗號分割的鍵值對, 對 metric 進一步描述和細化, 可以是空字符串. 比如 idc=lg，比如service=xbox 等，多個 tag 之間用逗號分割
說明：這7個字段都是必須指定
2、Python 版本
### python版本 ###
#!-*- coding:utf8 -*-
import requests
import time
import json
ts = int(time.time())
payload = [
{
"endpoint": "test-endpoint",
"metric": "test-metric",
"timestamp": ts,
"step": 60,
"value": 1,
"counterType": "GAUGE",
"tags": "idc=lg,loc=beijing",
},
{
"endpoint": "test-endpoint",
"metric": "test-metric2",
"timestamp": ts,
"step": 60,
"value": 2,
"counterType": "GAUGE",
"tags": "idc=lg,loc=beijing",
},
]
r = requests.post("http://127.0.0.1:1988/v1/push", data=json.dumps(payload))
print r.text
3、Shell 版本
### shell版本 ###
ts=`date +%s`;
curl -X POST -d "[{\"metric\": \"test-metric\", \"endpoint\": \"test-endpoint\", \"timestamp\": $ts,\"step\": 60,\"value\": 1,\"counterType\": \"GAUGE\",\"tags\": \"idc=lg,project=xx\"}]" http://127.0.0.1:1988/v1/push
4、PHP 版本
### php版本 ###
$timestamp = time();
$params = array(
array(
"endpoint" => "yz-higo-xxx.lehe.com",
"metric" => "order_xxx",
"timestamp" => $timestamp,
"step" => 60,
"value" => xxx,
"counterType" => "GAUGE",
"tags" => "xxx",
)
);
$url = 'http://127.0.0.1:1988/v1/push';
curl($params, $url);
function curl($params, $url) {
if (empty($params)) {
return FALSE;
}
$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_HEADER, FALSE);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, 3);
curl_setopt($curl, CURLOPT_TIMEOUT, 10);
$resp = curl_exec($curl);
curl_close($curl);
return $resp;
}
5、Plugin 機制
Plugin 可以看做是對 agent 功能的擴充。對於業務系統的監控指標採集，最好不要做成 plugin，而是把採集腳本放到業務程序發佈包中，隨着業務代碼上線而上線，隨着業務代碼升級而升級，這樣會比較容易管理。
要使用Plugin，步驟如下：
5.1 編寫採集腳本
用什麼語言寫沒關係，只要目標機器上有運行環境就行，腳本本身要有可執行權限。採集到數據之後直接打印到stdout即可，agent會截獲並push給server。數據格式是json，官網給的例子如下：
[root@host01:/path/to/plugins/plugin/sys/ntp]#./600_ntp.py
[{"endpoint": "host01", "tags": "", "timestamp": 1431349763, "metric": "sys.ntp.offset", "value": 0.73699999999999999, "counterType": "GAUGE", "step": 600}]
注意，這個 json 數據是個 list 哦。
5.2 上傳腳本到 git
插件腳本也是 code，所以最好也用 git、svn 管理，這裏我們使用 git 管理，公司內部如果沒有搭建 gitlab，可以使用 gitcafe、coding.net 之類的，將寫好的腳本 push 到 git 倉庫，比如上例中的 600_ntp.py，姑且放到 git 倉庫的 sys/ntp 目錄下。注意，這個腳本在 push 到 git 倉庫之前要加上可執行權限。
5.3 檢查 agent 配置
大家之前部署 agent 的時候應該注意到 agent 配置文件中有配置 plugin 吧，現在到了用的時候了，把 git 倉庫地址配置上，enabled 設置爲 true。注意，配置的 git 倉庫地址需要是任何機器上都可以拉取的，即 git:// 或者 https:// 打頭的。如果 agent 之前已經部署到公司所有機器上了，那現在手工改配置可能略麻煩，之前講過的嘛，用 ops-updater 管理起來~
5.4 拉去 plugin 腳本
agent 開了一個 http 端口 1988，我們可以挨個 curl 一下 http://ip:1988/plugin/update 這個地址，這會讓 agent 主動 git pull 這個插件倉庫。爲啥沒做成定期拉取這個倉庫呢？主要是怕給 git 服務器壓力太大……大家悠着點用，別給人 pull 掛了……
5.5 讓 plugin run 起來
上一步我們拉取了 plugin 腳本到所有機器上，不過 plugin 並沒有執行。哪些機器執行哪些 plugin 腳本，是在 portal 上面配置的。其實我很想做成，只要插件拉取下來了就立馬執行，不過實際實踐中，有些插件還是不能在所有機器上跑，所以就在 portal 上通過配置控制了。在 portal 上找到要執行插件的 HostGroup，點擊對應的 plugins 超鏈接，對於上例 sys/ntp 目錄下的 600_ntp.py，直接把 sys/ntp 綁定上去即可。sys/ntp 下的所有插件就都執行了。
5.6 補充
portal 上配置完成之後並不會立馬生效，有個同步的過程，最終是 agent 通過調用hbs的接口獲取的，需要一兩分鐘。上例我們綁定了 sys/ntp，這實際是個目錄，這個目錄下的所有插件都會被執行，那什麼樣的文件會被看做插件呢？文件名是數字下劃線打頭的，這個數字代表的是 step，即多長時間跑一次，單位是秒，比如 60_a.py，就是在通過命名告訴 agent，這個插件每 60 秒跑一次。sys/ntp 目錄下的子目錄、其他命名方式的文件都會被忽略。
5.7 插件如何傳遞參數
Open-Falcon 在 PR #672 中，對插件傳遞傳遞自定義參數進行了支持。在 dashboard 中，配置 HostGroup 綁定插件時，可以支持針對單個腳本配置參數。
比如：sys/ntp/30_xx.sh(a, "33 4", 'test.sh f\,d')，表示對 hostgroup 綁定一個插件腳本 sys/ntp/30_xx.sh, 並傳遞 4 個參數，多個參數之間用,分割，每個參數可以用雙引號或者單引號括起來。如果參數中本身就包含逗號，可以使用 \, 來轉義。
- 參數，只在綁定單個插件腳本時有效。如果綁定的是一個插件目錄，傳遞的參數會忽略掉。
- 如果某個目錄下的某個插件腳本，被單獨綁定到某個hostgroup，同時該目錄也被綁定到了這個hostgroup，這個插件腳本不會重複被執行，綁定目錄時這個插件腳本會被忽略（也就是說，單個腳本的綁定會覆蓋目錄綁定方式下的同一個腳本）。