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	カスタムスクリプトでアクションを記述します。	-

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