ZabbixAPI item.create - 姜の日記的な何か

本項ではアイテムの作成を行うAPIについて記載する。

http://kyou.hatenadiary.jp/entry/2017/12/25/233314
ZabbixAPIを使うメリットで記載した「新規監視登録」を大量に行う場合に使用する。

とはいえそもそもどんな監視を行うか？が明らかである必要がある。
監視対象のシステムやサーバの重要度やシステムのSLAに依存するため、適切な運用設計が行われているのが前提である。

http://kyou.hatenadiary.jp/entry/2018/01/01/010131
ZabbixAPIを使う作業環境で記載した環境のため、json2zabbix.shで使うJSON形式を作成して実行する方式とする。

また、Zabbix公式Docで参照するページは以下2つになる
https://www.zabbix.com/documentation/3.0/manual/api/reference/item/object
https://www.zabbix.com/documentation/3.0/manual/api/reference/item/create

公式Docのアイテム作成JSONのサンプルは以下のとおり
{
   "jsonrpc": "2.0",
   "method": "item.create",
   "params": {
     "name": "Free disk space on $1",
     "key_": "vfs.fs.size[/home/joe/,free]",
     "hostid": "30074",
     "type": 0,
     "value_type": 3,
     "interfaceid": "30084",
     "applications": [
       "609",
       "610"
     ],
     "delay": 30
   },
   "auth": "038e1d7b1735c6a5436ee9eae095879e",
   "id": 1
}

各パラメータの詳細を記載する。
jsonrpc: これは"2.0"固定

method: "item.create"でアイテム作成を指定する。必須項目。

name: アイテム名を指定する。必須項目。""で括り文字列で指定する。日本語OK。また、GUIで使用するマクロ(組み込み・ユーザ)使用可能。

key_: アイテムキーを指定する。必須項目。key_の末尾アンダースコアをよく忘れる。誤字っぽいが正式なパラメータ名である。アイテムキー内にダブルクォーテーションを入れる場合はバックスラッシュでエスケープしておく。

hostid: このアイテムを追加するホストIDもしくはテンプレートIDを指定する。必須項目。Zabbixの内部管理上、ホストとテンプレートは区別されてなく、両者ともhostidという5桁の数字で管理されホストとテンプレート通じて一意である。また数値ではなく"数字"であるため、ダブルクォーテーションで括って文字列指定をする必要がある。よく忘れる。また特定のホストやテンプレートのIDを調べる場合、ZabbixGUI画面上のURLを調べると5桁数字が入っているのがそれである。
また、1アイテムごとに指定できるため複数のホストやテンプレートに対して処理可能である。

type: アイテムタイプを指定する。公式Docのコピーだが以下のとおり
0 - Zabbix agent
1 - SNMPv1 agent
2 - Zabbix trapper
3 - simple check
4 - SNMPv2 agent
5 - Zabbix internal
6 - SNMPv3 agent
7 - Zabbix agent (active)
8 - Zabbix aggregate
9 - web item
10 - external check
11 - database monitor
12 - IPMI agent
13 - SSH agent
14 - TELNET agent
15 - calculated
16 - JMX agent
17 - SNMP trap

value_type: データ型のこと。必須項目。公式Docのコピーだが以下のとおり
0 - numeric float
1 - character
2 - log;
3 - numeric unsigned;
4 - text

interfaceid: ホストに対して指定する場合に必須。IPアドレスとポートのペアでinterfaceidが振られているためそれを指定する。host.getから引くことが可能だが、個人的にホスト指定のアイテムは作成しない運用をしているのでGUIでの調べ方は知らない。
(各ホストはなんらかのテンプレートをリンクする前提でZabbixを運用しているため)

applications: 各アイテムのアプリケーションを指定する。個人的にこのパラメータは使用せず、アイテム作成後にZabbixGUI画面の一括更新でアプリケーションを設定する。なのでApplicationIDは調べ方知りません。

delay: 更新間隔。必須項目。数値のためダブルクォーテーションで括ってはいけない。これもZabbixGUI画面の一括更新で変更可能なため、ZabbixAPIでは割と適当に指定して後から調整するケースが個人的には多い。

auth: ZabbixAPIの認証トークン。必須項目。json2zabbix.shの場合は ##TOKEN## を記載する。

id: ZabbixAPIの実行ID。必須項目。とりあえず1で良い。

上記以外で個人的に割と使うパラメータは以下のとおり。

status: 有効/無効の指定。なんらかの変更に合わせたアイテム追加を事前にアイテムを無効状態で作成する場合に使っている。画面上は2択の割にパラメータ型はIntegerなので注意。指定内容は公式Docコピーだが以下のとおり。
0 - (default) enabled item
1 - disabled item
また、ややこしいことにstateという別パラメータがあるが、これはreadonlyで、設定したアイテムが使用可能or使用不可を表すパラメータでありitem.getで使用する。

history: ヒストリの保存期間を指定する。任意項目。ZabbixGUI画面の一括更新で変更可能なのでアイテム作成してから変更する場合もあるがたまに使う。
trends: トレンドの保存期間を指定する。任意項目。ZabbixGUI画面の一括更新で変更可能なのでアイテム作成してから変更する場合もあるがたまに使う。

さて、前置き長くなったがここからが本題である。上記のパラメータを理解したところで、これらを覚えて1文字ずつ打っていては何らメリットはない。
新規監視登録時には何らか一覧(Excel表)を作成し、こんな監視をして欲しいという構築担当の依頼があるとする。

共通部分ごとに細かくテンプレート分けをするのもひとつであるが、ZabbixAPIで使うJSONの生成であれば
「対象ホスト」「アイテム名」「アイテムキー」の3列の表を作る。その上でホスト同士の共通部分からテンプレート設計を起こしたら、
「テンプレート名」「アイテム名」「アイテムキー」の3列表にする。

あとはそれぞれ
hostid 「テンプレート名」 name 「アイテム名」 key_ 「アイテムキー」
と列挿入後、タブ区切りの状態でテキストエディタに移し、JSON用の波括弧{}やダブルクォーテーションを正規表現を使って挿入していく。
(Excelの状態だと記号類を解釈されたりするのでテキストエディタに移している)

置換やマクロなどを使い、以下のようなリストにする。(statusパラメータは必須ではないが個人的には入れてZabbixGUI上で有効にするパターンが多い)

{"name": "TestItema", "key": "system.run[/usr/local/bin/a.com]","hostid": "10106", "type" :0, "value_type": 3, "delay": 60, status": 1},
{"name": "TestItemb", "key_": "system.run[/usr/local/bin/b.com]","hostid": "10106", "type" :0, "value_type": 3, "delay": 60, "status": 1},
{"name": "TestItemc", "key_": "system.run[/usr/local/bin/c.com]","hostid": "10106", "type" :0, "value_type": 3, "delay": 60, "status": 1},

その後、1行目に以下を挿入し

{"jsonrpc": "2.0", "method": "item.create", "params": [

末行に以下を挿入する

],"auth": "##TOKEN##","id": 1}

そして下から2番目の末尾にあるコンマが余分になるため削って以下の形式することでJSON形式になる。

{"jsonrpc": "2.0", "method": "item.create", "params": [
{"name": "TestItema", "key": "system.run[/usr/local/bin/a.com]","hostid": "10106", "type" :0, "value_type": 3, "delay": 60, "status": 1},
{"name": "TestItemb", "key_": "system.run[/usr/local/bin/b.com]","hostid": "10106", "type" :0, "value_type": 3, "delay": 60, "status": 1},
{"name": "TestItemc", "key_": "system.run[/usr/local/bin/c.com]","hostid": "10106", "type" :0, "value_type": 3, "delay": 60, "status": 1}
],"auth": "##TOKEN##","id": 1}

ここでのポイントは
・1行目と末行を固定化し、他の部分は1アイテム1行に収まるようにする

・正規表現置換やテキスト置換、テキストエディタのマクロ等を使用し数行から数千行でも同等の操作で行うようにする。
(手作業でやっても良いが量に応じて作業時間が増えるため推奨しない)

・Excelだろうがエディタだろうがこだわりなく使えるものを使う
(もちろんawk&sedでも良いし、Pythonで書いて生成しても良い。自分が使いやすいものを使えば良い)

あとはこれを bash json2zabbix.sh xxxx.json として実行すればOK。
何らかエラーが出た場合は相応の対処が必要になるが、それば別途記載する。

また、エラー時の切り分けをする場合や、行が長すぎる場合などは
適当な行途中に

],"auth": "##TOKEN##","id": 1}

{"jsonrpc": "2.0", "method": "item.create", "params": [

の2行を追加し、この行のところで別ファイル化することでファイルを半分にしつつJSON形式を維持するのも容易なのが
このZabbixAPI用JSONの良いところである。