ちょこちょことmuninのpluginを作ってるけど、毎回作り方を調べるのが面倒なので備忘録として書いておきます。

pluginの基本

• munin-node側の/etc/munin/pluginsにスクリプトファイルを置けばOK。
• munin-run <plugin名>で「値」を表示。munin-run <plugin名> configでグラフ情報を表示。plugin名は基本的には/etc/munin/plugins以下に置いたファイル名。
• munin-runはrootアカウントで実行すること。
• デフォルトでmuninアカウントで実行される。muninアカウントはデフォルトでシェルを持たないので、テストしたい場合は「su -s /bin/bash – munin」などでsuする。
• muninアカウント以外で実行したい場合は、「/etc/munin/plugin-conf.d/munin-node」に「[plugin名]」セクションを作成し、「user root」など、別のアカウント名を指定すれば良い。
• pluginを追加した場合は、munin-nodeの再起動が必要。
  munin(サーバ側)はcron実行なので、再起動という概念が無いので不要。

pluginの書き方

bashで書くならだいたいこんな感じ。本当はautoconfigなどのオプションにも対応すべきだけど、サンプルは最低限動く内容にしてます。

#!/bin/bash
LANG=C
TARGET_PATH=/hoge/fuga

if [ "$1" = "config" ]; then
 # config
 echo 'graph_title kvm image size'
 echo 'graph_args --base 1024 --vertical-label byte -l 0'
 echo 'graph_category kvm'
 echo 'server1.label Server-1'
 echo 'server1.type GAUGE'
 echo 'server1.min 0'
 echo 'server1.draw LINE2'
 echo 'server2.label Server-2'
 echo 'server2.type GAUGE'
 echo 'server2.min 0'
 echo 'server2.draw LINE2'
 exit 0
fi

# value
echo server1.value `du -b ${TARGET_PATH}/server1/server1.qcow2 | cut -f 1`
echo server2.value `du -b ${TARGET_PATH}/server2/server2.qcow2 | cut -f 1`

 

ちなみに、muninは関係無いけど、for文で動的に複数のグラフを定義することもよくやる。

# value
HOST_ITEMS=`virsh list | grep running | awk '{print $2}'`
for HOST_ITEM in ${HOST_ITEMS}
do
 echo ${HOST_ITEM}.value `du -b ${TARGET_PATH}/${HOST_ITEM}/${HOST_ITEM}.qcow2 | cut -f 1`
done

 

config

「munin-run <plugin名> config」を実行すると以下のように表示される。

# munin-run vmimg_size config
graph_title kvm image size
graph_args --base 1024 --vertical-label byte -l 0
graph_category kvm
server1.label server1
server1.type DERIVE
server1.min 0
server1.draw LINE2
server2.label server2
server2.type DERIVE
server2.min 0
server2.draw LINE2

基本的に左辺が「文字.文字」となっている部分はグラフの線毎の設定。ちなみに「フィールド名.属性」。後述の値を表示の際の「フィールド名.value」のフィールド名と連動してます。
左辺にドットが無い部分はグラフ全体の設定。右辺は設定毎に指定方法が違います。

ちなみに属性とグラフの関連性は以下の図のような感じ。

なお、configの表示内容を変更した場合は、munin-nodeの再起動をしましょう。

全体の属性

 

graph_title

グラフのタイトル。HTML及びグラフそのものに表示される。グラフにはグラフの尺度によって「- by day」などの文字が付く。

graph_args

これには、グラフに関する様々なオプションが指定できる。スペース区切りで付与します。

書き方
graph_args --base 1024 --vertical-label byte -l 0

• –base 値
  グラフの縦軸ラベルに値が表示されますが、1000を超えると「1k」などに表示が丸められます。で、byteなどの場合は1k=1024な訳なので、いくつになると1kになるかをこれで指定します。だいたい–base 1000か–base 1024かいずれかでしょうね。
• –vertical-label ラベル名
  縦軸に表示されるラベル名
• –upper-limit 値、–lower-limit 値
  グラフの縦軸の上限/下限を指定します。ちなみに上限/下限に収まれば縦軸の上限/下限がこの値の通りになりますが、それを超えた場合は最大値/最小値の値まで縦軸は伸びます。超えても伸ばしたく無い場合は「–rigid」を使います。
  上記の例では「-l」と省略して書いてます。
• –rigid
  指定すると、グラフデータが–upper-limit、–lower-limitを超えても絶対に縦軸が変化しません。

 

graph_category

HTMLで複数のグラフを見た場合に、カテゴリに分けられて表示されます。

フィールド毎の設定

フィールド名は好きな文字でいいけど、同一フィールド名は同じ値にしないとダメです。

フィールド名.label

グラフのラベル。グラフの下の凡例に表示される。環境によっては日本語が旨く表示されなくて困ることも多い。

フィールド名.type

GAUGEを指定した場合はvalで表示した値をそのまま表示しますが、例えば累積値など、前回の差を表示したい場合などに指定を変えることで対応できます。

書き方
 フィールド名.type GAUGE

type	意味
GAUGE	値がそのままグラフの値になります。
COUNTER	前回の差をグラフの値とします。例えば総通信量など、前回が10bit/s、今回が12bit/s、次回が18bit/sという場合、そのままグラフに表現(GAUGE)すると永遠と右肩上がりの表現となります。「COUNTER」を指定すると前回からの差をグラフ値とします。
DERIVE	COUNTERと同じですが、こっちはオーバーフローを考慮しません。 値が常に増分ならCOUNTERを使用すべきですが、希にリセットされる場合や値が減少する場合はこっちを使った方がリセット時の値が正しく表示されます。
ABSOLUTE	DERIVEと同じだけど、最大許容値などが指定できるなど細かな制御ができる(本サイトでは詳細は省略します)

 

フィールド名.max、フィールド名.min

値の最大値・最小値。グラフに与えられる値がこれを超えた場合は、これを超えない値がセットされる。主にオーバフロー対策で使用する。原則としてグラフの縦軸の調整に用いるべきでは無い(縦軸を制限するのはgraph_argsの–upper-limit、–lower-limit、–rigid)。

フィールド名.draw

グラフのデザイン。主に折れ線グラフか面グラフと、積み重ねグラフかどうかの指定となる。
面グラフを積み重ねない場合は、munin-runなどで表示されるconfigの順番で重なるので、裏側のグラフが見えなくなるのに注意。
また、積み重ねグラフも上位から順番に重ねていくことになる。それぞれフィールド毎に指定できるので、面と線グラフの併用も当然できる。

• AREA
  面グラフ
• LINE、LINE[n]
  折れ線グラフ。LINE2とか数値を追加すると線が太くなる。
• AREASTACK
  積み重ねの面グラフ

value

何も指定しないと表示される値。muninはこの値を定期的に取得し、グラフを生成する。
基本的には「フィールド名.value 値」で表現するが、フィールド名はconfigのフィールド名と連動させないと表示されない。

# munin-run vmimg_size
server1.value 7962492928
server2.value 4277010432