Reflection
Reflection
は、Collector
が収集したデータを選別、加工、キャッシング、転送するアクションを管理するプラグインです。
Reflectionが保有する属性
-
name
: Reflectionの名前を指定します。ユニークである必要があります。 -
enable
: Reflectionの有効化モードを指定します。True
の場合、処理対象のデータを検出するとアクションを適用して実行します。False
の場合、動作しません。デフォルトは、True
です。 -
apply_condition
: 処理対象のデータを選別する条件を規定します。 -
apply_condition.data_type
: 適用する収集データタイプを選択します。SNMPで収集したデータはmib
、HTTPで収集したデータはhttp
、SCRIPTで収集したデータはscript
を指定してください。 -
apply_condition.oid
: data_typeがmib
の場合にマッチングするMIBオブジェクトIDを指定します。ifIndexを変数化して取得している場合は、1.3.6.1.2.1.31.1.1.1.6.{ifIndex}
のように指定します。 -
apply_condition.path
: data_typeがhttp
の場合にマッチングするHTTPリクエストパスを指定します。パス変数がある場合も、/api/vms/{vmid}/power
のように指定します。 -
apply_condition.name
: data_typeがscript
の場合にマッチングするscript名を指定します。Docs » Collector/Reflector » Collectionパターン
に記載されているcollections.method.name
を意味しています。 -
action_script
: カスタムスクリプトでアクションを記述します。
Note
実行空間は、collection
、correlation_info
、ifmap
、nocache
、additional_cache
という変数が事前定義されています。また、clear_cache
とpush_metrics
という事前定義関数が利用できます。
* collection変数: Collectorが収集したデータオブジェクトがMU
型で格納されています。
* correlation_info変数: Collectionのcorrelation_info
がMU
型で格納されています。
* ifmap変数: Collectorが自動収集したifName
とifIndex
の対応表が辞書型で格納されています。
* nocache変数: False
が初期設定されています。True
を代入するとキャッシング動作がスキップされます。
* additional_cache変数: 空の辞書が初期設定されています。通常キャッシングされるデータは、collection
変数のみですが、additional_cacheに任意の辞書を代入するとcollection
変数にマージされてキャッシングされます。
* clear_cache関数: キャッシングされているデータを全て破棄する関数です。引数は、不要です。
* push_metrics関数: メトリクス送信キューにデータをプッシュする関数です。現時点では、Zabbixへの転送のみをサポートしています。
collection
変数の構造について
Collectionで収集されたデータは、collection
変数によってReflecionのアクションスクリプトで参照できます。Collectionの収集方法によってcollection
変数のデータ構造が異なる点に注意が必要です。ここでは収集方法毎のデータ構造サンプルを紹介します。
全ての収集方法に共通して付与されるキーは、収集対象のaddress
、host
、sysuptime
と収集が実行されたUNIXタイムスタンプであるstamp
です。ただし、sysuptime
に関しては同周期でSNMPによって収集されるデータがある場合に限り、値がセットされます。
SNMP
による収集データの構造
SNMPによって収集されたデータを含むcollection
変数は以下の構造で格納されています。
address: 192.168.2.200
datetime: '2021-02-08T00:05:47+00:00'
host: CSR1000v
oid: 1.3.6.1.2.1.6.5.0
stamp: 1612742747
sysuptime: 72433
type: Counter32
value: 0
address: 192.168.2.200
datetime: '2021-02-08T00:05:46+00:00'
host: CSR1000v
oid: 1.3.6.1.2.1.1.3.0
stamp: 1612742746
sysuptime: 72433
type: TimeTicks
value: 72433
HTTP
による収集データの構造
HTTPによって収集されたデータを含むcollection
変数は以下の構造で格納されています。
address: 192.168.2.200
body:
power_state: poweredOn
code: 200
endpoint: http://localhost:8697
headers:
Cache-Control: no-cache
Content-Length: '32'
Content-Type: application/vnd.vmware.vmw.rest-v1+json
Date: Mon, 08 Feb 2021 00:05:48 GMT
X-Http-Reason: OK
host: CSR1000v
method: GET
path: /api/vms/75CE72DHP742RGQCMLI1MCRFK8I1KRNS/power
stamp: 1612742748
sysuptime: 72433
url: null
SCRIPT
による収集データフォーマット
SCRIPTによって収集されたデータを含むcollection
変数は以下の構造で格納されています。SCRIPTの場合は、任意の収集データを生成できるため、response
キーに格納されるデータ構造は、可変です。
address: 192.168.2.200
host: CSR1000v
name: ping
response: round-trip min/avg/max/stddev = 3.679/3.679/3.679/0.000 ms
stamp: 1612744728
sysuptime: 270401
-
cache_size
: データキャッシュのサイズを指定します。デフォルトは、0
です。 -
cache_unit
: データキャッシュの単位を指定します。name
単位とoid
単位が選択できます。デフォルトは、name
です。name
は、Reflectionの名前です。SNMP-BULKで一括取得したCounter値など過去に取得した値を参照してメトリック値を計算するような場合、oid
単位でキャッシングします。REST-APIで取得したデータは、必ず収集データとReflectionが1:1の関係となるため、name
でキャッシングします。 -
cache_ttl
: データキャッシュの生存期間を指定します。デフォルトは、3600
秒です。
サンプル
以下は、SNMPで収集したifHCInOctetsに対するReflection定義例です。ifHCInOctetsは、64bitカウンタのため、前回取得値との差分をメトリックとして算出しています。
- name: ifHCInOctets
action_script: |-
# キャッシュが空の場合は、初回収集のため、何もせずキャッシュする
if len(cache)==0:
return
# 値が取得できていない場合は、廃棄する
if collection.value is None:
return
# Zabbixの監視アイテムキーを生成するための処理
ifIndex = collection.oid.split(".")[-1]
rifmap = {v: k for k, v in ifmap.items()}
meterName = "{}.traffic.in.bps".format(rifmap[ifIndex].replace("/", ""))
# 前回値との差分を求める(カウンタリセットを考慮)
difference = 0
if collection.value < cache[-1]["value"]:
difference = (2**64-1)-cache[-1]["value"]+collection.value
else:
difference = collection.value-cache[-1]["value"]
if difference < 0:
difference*=-1
# 差分値をbpsに変換する
v = difference*8/(collection.stamp-cache[-1]["stamp"])
# Zabbix送信キューにプッシュする
await push_metrics(endpoint="%s:%s" % (correlation_info.zabbix_host, correlation_info.zabbix_port),
host=collection.host,
key=meterName,
value=round(v, 4),
stamp=collection.stamp)
apply_condition:
data_type: mib
oid: '1.3.6.1.2.1.31.1.1.1.6.{ifIndex}'
cache_size: 1
cache_ttl: 3600
cache_unit: oid
enable: true