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

実行空間は、collectioncorrelation_infoifmapnocacheadditional_cacheという変数が事前定義されています。また、clear_cachepush_metricsという事前定義関数が利用できます。

変数 詳細
collection変数 Collectorが収集したデータオブジェクトがMU型で格納されています。
correlation_info変数 Collectionのcorrelation_infoMU型で格納されています。
ifmap変数 Collectorが自動収集したifNameifIndexの対応表が辞書型で格納されています。
nocache変数 Falseが初期設定されています。Trueを代入するとキャッシング動作がスキップされます。
additional_cache変数 空の辞書が初期設定されています。通常キャッシングされるデータはcollection変数のみですが、additional_cacheに任意の辞書を代入するとcollection変数にマージされてキャッシングされます。
clear_cache関数 キャッシングされているデータを全て破棄する関数です。引数は、不要です。
push_metrics関数 メトリクス送信キューにデータをプッシュする関数です。現時点では、Zabbixへの転送のみをサポートしています。

collection変数の構造について

Collectionで収集されたデータは、collection変数によってReflecionのアクションスクリプトで参照できます。Collectionの収集方法によってcollection変数のデータ構造が異なる点に注意が必要です。ここでは収集方法毎のデータ構造サンプルを紹介します。
全ての収集方法に共通して付与されるキーは、収集対象のaddresshostsysuptimeと収集が実行された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