Collection Pattern

Collection Patternは、データ収集のパターンをテンプレート定義する機能です。

Collection Patternが保有する属性

  • name: パターン名を指定します。ユニークである必要があります。

  • collections: 収集アイテムを定義します。

  • collections.interval: 収集間隔を指定します。分単位で指定可能で 1 2 3 4 5 6 10 15 20 30 60が選択できます。デフォルトは1分です。

  • collections.description: 任意の説明を記述できます。

  • collections.correlation_info: 任意の関連情報を辞書型で指定します。指定した辞書は、後述するcollections.method情報へのレンダリングやカスタムスクリプト内で参照することができます。correlation_infoは、収集されたデータとセットでデータフローパイプライン横断で伝搬されます。

  • collections.method: 収集アイテムの収集方法を定義します。収集プロトコルは、SNMP-GET SNMP-BULK HTTP SCRIPTのいづれかが選択できます。
    collections.methodではレンダリング変数を定義できます。レンダリング変数は、{ 変数名 }形式で記述します。レンダリングパラメータは、collections.correlation_infoです。また、Collection側でもcorrelation_infoが定義されている場合はマージされます。


SNMP-GET

SNMPプロトコルのGETオペレーションで指定したOIDのMIBオブジェクトを収集します。

  • collections.method.protocol: SNMP固定
  • collections.method.port: SNMPエージェントのリスニングポートを指定します。デフォルトは、161です。
  • collections.method.credential: SNMPエージェントのクレデンシャルを指定します。SNMPバージョンによって設定パラメータが異なります。
  • collections.method.version: v1 v2c v3が選択できます。
  • collections.method.community: SNMPコミュニティを指定します。v1 v2cの場合に指定します。
  • collections.method.userName: SNMPユーザ名を指定します。v3の場合に指定します。
  • collections.method.authKey: SNMP認証鍵を指定します。v3の場合に指定します。
  • collections.method.privKey: SNMPプライバシー鍵を指定します。v3の場合に指定します。
  • collections.method.authProtocol: SNMP認証プロトコルを指定します。usmNoAuthProtocol usmHMACMD5AuthProtocol usmHMACSHAAuthProtocolのいづれかを選択します。デフォルトは、usmNoAuthProtocolです。v3の場合に指定します。
  • collections.method.privProtocol: SNMPプライバシープロトコルを指定します。usmNoPrivProtocol usmDESPrivProtocol usm3DESEDEPrivProtocol usmAesCfb128Protocol usmAesCfb192Protocol usmAesCfb256Protocol usmAesBlumenthalCfb192Protocol usmAesBlumenthalCfb256Protocolのいづれかを選択します。デフォルトは、usmNoPrivProtocolです。v3の場合に指定します。
  • collections.oid: GETするMIBオブジェクト識別子を指定します。MIBインスタンス識別子まで指定する必要があります。


SNMP-BULK

  • collections.method.protocol: SNMP固定
  • collections.method.port: SNMPエージェントのリスニングポートを指定します。デフォルトは、161です。
  • collections.method.credential: SNMPエージェントのクレデンシャルを指定します。SNMPバージョンによって設定パラメータが異なります。
  • collections.method.version: v1 v2c v3が選択できます。
  • collections.method.community: SNMPコミュニティを指定します。v1 v2cの場合に指定します。
  • collections.method.userName: SNMPユーザ名を指定します。v3の場合に指定します。
  • collections.method.authKey: SNMP認証鍵を指定します。v3の場合に指定します。
  • collections.method.privKey: SNMPプライバシー鍵を指定します。v3の場合に指定します。
  • collections.method.authProtocol: SNMP認証プロトコルを指定します。usmNoAuthProtocol usmHMACMD5AuthProtocol usmHMACSHAAuthProtocolのいづれかを選択します。デフォルトは、usmNoAuthProtocolです。v3の場合に指定します。
  • collections.method.privProtocol: SNMPプライバシープロトコルを指定します。usmNoPrivProtocol usmDESPrivProtocol usm3DESEDEPrivProtocol usmAesCfb128Protocol usmAesCfb192Protocol usmAesCfb256Protocol usmAesBlumenthalCfb192Protocol usmAesBlumenthalCfb256Protocolのいづれかを選択します。デフォルトは、usmNoPrivProtocolです。v3の場合に指定します。
  • collections.method.oids: BULK GETするMIBオブジェクト識別子を列挙指定します。
  • collections.method.nonRepeaters: collections.oidsに指定したOIDリストの先頭から繰り返し取得を行わないものの個数を指定します。例えばOID1, OID2, OID3配下のMIBをBULKで取得するとして、nonRepeatersを2 とすると、OID1とOID2 については繰り返し取得を実施せず、OID3 についてだけは繰り返し取得を実施する動作となります。デフォルトは0です。
  • collections.method.maxRepetitions: 一括繰り返し取得回数を指定します。MaxRepetitionsで指定できる数字に上限はありませんが、実際には、エージェント側の最大PDUサイズに依存し、それを超える場合には反映されません。デフォルトは50です。


HTTP

  • collections.method.protocol: HTTP固定
  • collections.method.endpoint: HTTP通信エンドポイントを指定します。
  • collections.method.path: HTTPリクエストパスを指定します。endpointを省略した場合は、APIGWにリクエストを送信します。
  • collections.method.method: HTTPリクエストメソッドを指定します。デフォルトはGETです。
  • collections.method.headers: HTTPリクエストヘッダーを指定します。
  • collections.method.body: HTTPリクエストボディーを指定します。
  • collections.method.retry_interval: リトライ間隔を指定します。デフォルトは0です。
  • collections.method.retry_count: リトライ回数を指定します。デフォルトは0です。
  • collections.method.retry_codes: リトライ判定するHTTP応答コードを列挙指定します。
  • collections.method.validate_cert: HTTPS通信においてサーバ証明書の検証要否を指定するモードを指定します。
  • collections.method.ca_certs: HTTPS通信においてPEM形式のCA証明書のファイル名を指定します。
  • collections.method.client_key: HTTPS通信においてクライアントSSL鍵のファイル名を指定します。
  • collections.method.client_cert: HTTPS通信においてクライアントSSL証明書のファイル名を指定します。
  • collections.method.authentication: 認証オプションを指定します。


SCRIPT

  • collections.method.name: スクリプト名を指定します。指定したnameは、スクリプトが生成したcollectionをreflectionにマッチングするキーワードとなるため、ユニークに名前付けする必要があります。
  • collections.method.script: カスタムスクリプトを記述します。カスタムスクリプトの名前空間には、address hostname collection_id correlation_info collection変数が事前定義されています。カスタムスクリプト内でcollection変数に辞書型でデータを代入することでreflectionに作成したデータを伝搬することができます。SCRIPTは、SNMPやHTTPで収集できないNETCONF/CLIなどでのデータ収集に使用します。

Note

collections.methodでcorrelation_infoによってレンダリングできるパラメータは、oid oids endpoint path body headers authenticationです。

Note

{インタフェース名}をSNMPのoidあるいは、oidsの変数として指定した場合、収集実行時に自動的にifindexに書き換えられます。
例として、1.3.6.1.2.1.31.1.1.1.6.{ge-0/0/0}のように設定した場合、{ge-0/0/0}部は実行時にifIndexに置換されます。該当するifNameが存在しない場合、データは破棄されます。BULK-GETのoidsリストに指定された場合で該当ifNameが存在しない場合は、該当oidを破棄し、nonRepeatersの数を必要に応じて自動補正します。また、インタフェース名を固定的に指定できない場合、{ge-0/0/0}を{.*}や{ge-.*}のように正規表現で指定することもできます。この場合も該当OIDにnonRepeatersが含まれている場合は自動補正されます。

サンプル

以下は、Collectionパターンのサンプル定義です。CSR1000vに対して1分間隔でsysUpTImeをGETで取得、5分単位でtcpActiveOpens、tcpPassiveOpens、ifHCInOctets、ifHCOutOctetsを収集します。また1分間隔でCSR1000vが稼働しているVMのパワー状態の収集とVMに対してpingを1回送信し、遅延を取得します。

- name: csr1000v
  collections:
    - interval: 1
      method:
        credential:
          community: '{snmp_community}'
          version: v2c
        oid: 1.3.6.1.2.1.1.3.0
        port: 161
        protocol: SNMP
    - interval: 5
      method:
        credential:
          community: '{snmp_community}'
          version: v2c
        nonRepeaters: 2
        oids:
          - 1.3.6.1.2.1.6.5
          - 1.3.6.1.2.1.6.6
          - '1.3.6.1.2.1.31.1.1.1.6.{Gi1}'
          - '1.3.6.1.2.1.31.1.1.1.6.{Gi2}'
          - '1.3.6.1.2.1.31.1.1.1.6.{Gi3}'
          - '1.3.6.1.2.1.31.1.1.1.10.{Gi1}'
          - '1.3.6.1.2.1.31.1.1.1.10.{Gi2}'
          - '1.3.6.1.2.1.31.1.1.1.10.{Gi3}'
        port: 161
        protocol: SNMP
    - interval: 1
      method:
        authentication:
          auth_mode: basic
          password: '{vmware_password}'
          username: '{vmware_username}'
        endpoint: '{vmware_endpoint}'
        path: '/api/vms/{vmid}/power'
        protocol: HTTP
    - interval: 1
      method:
        name: ping
        script: |-
          p = await asyncio.create_subprocess_shell("ping -c 1 {}".format(address), stdout=asyncio.subprocess.PIPE)
          r = await p.communicate()
          collection = r[0].decode("utf-8").splitlines()[-1]


インタフェース名に正規表現で指定する場合は、以下のように記述できます。

- name: csr1000v
  collections:
    - interval: 1
      method:
        protocol: SNMP
        port: 161
        oid: 1.3.6.1.2.1.1.3.0
        credential:
          version: v2c
          community: '{snmp_community}'
    - interval: 1
      method:
        protocol: SNMP
        port: 161
        oids:
          - 1.3.6.1.2.1.6.5
          - 1.3.6.1.2.1.6.6
          - '1.3.6.1.2.1.31.1.1.1.6.{Gi.$}'
          - '1.3.6.1.2.1.31.1.1.1.10.{Gi.$}'
        credential:
          version: v2c
          community: '{snmp_community}'
        nonRepeaters: 2
    - interval: 1
      method:
        protocol: HTTP
        endpoint: '{vmware_endpoint}'
        path: '/api/vms/{vmid}/power'
        authentication:
          auth_mode: basic
          username: '{vmware_username}'
          password: '{vmware_password}'
    - interval: 1
      method:
        name: ping
        script: |-
          p = await asyncio.create_subprocess_shell("ping -c 1 {}".format(address), stdout=asyncio.subprocess.PIPE)
          r = await p.communicate()
          collection = r[0].decode("utf-8").splitlines()[-1]