ZabbixテンプレートでCatoのトラフィックを収集する実践ガイド【シリーズ第3弾】

シリーズ第3回では、これまで準備してきた内容に続き、実際にZabbixのローレベルディスカバリ（LLD）を活用したZabbixテンプレート作成を通じて、CATOのサイト監視用のメトリクスを実際に取得する方法を解説します。

CATOのAPIを利用して「サイト」を検出し、その増減に自動で対応しながら、そのサイトの利用帯域のメトリクスを取得する仕組みを構築します。

本記事は、これまでのシリーズで紹介した内容を使って進めていきますので、ぜひ以下の記事もご覧ください。

　◆シリーズ第1回： GraphQLをcurlで扱う
　◆シリーズ第2回： Zabbixのローレベルディスカバリ

まず、今回実装する全体像を俯瞰しましょう。


下記のステップで、サイト毎にメトリクスを取得できるようにします。

　1. 全サイトのメトリクスを取得 （マスターアイテム）
　　a. カスタムで実装したアイテム用のキー cato.account_metrics.sites で、
　　　所有する全てのサイトの全てのメトリクスを取得します。
　　b. 全サイトのメトリクスを 1 回の API 呼び出しでまとめて取得することで、負荷軽減を狙います。
　2. サイト検出 （LLD でのディスカバリ）
　　a. カスタムで実装したディスカバリ用のキー cato.site.discovery で CATO の「サイト」を検出します。
　3. プロトタイプの適用
　　a. アイテム用のキー cato.site.metric で、1 の cato.account_metrics.sites の値から検出されたサイトの
　　　特定のメトリクスを抜き出します。

すべての「サイト」のメトリクスを取得するアイテムのためのキーを実装します。
このアイテムでは、API のクエリ “accountMetrics” の返す JSON をそのまま記録します。
JSON の具体的な値の加工は行わず、値の取り出しは LLD で生成される各アイテムで行います。

実装

Zabbix の「外部チェック」というタイプのキーのためのスクリプトを実装します。

外部チェックは、Zabbix サーバ上に設置したスクリプトを実行する機能です。

スクリプトは、Zabbix サーバの設定ファイルで指定された ExternalScripts のディレクトリ配下に配置します。パスは適宜読み替えてください。

Zabbix でのアイテムの引数は、そのままスクリプトの引数として渡されます。
Cato のアカウント ID と API キーを引数で受け取れるように実装しています。

### /usr/lib/zabbix/externalscripts/cato.account_metrics.sites (0755)

#!/usr/bin/env bash
#
# cato.account_metrics.sites[account_id,api_key]
#

ACCOUNT_ID="${1:?}"
API_KEY="${2:?}"

_query=$(cat <<'___EOL___'
query query(
  $accountID: ID!
  $timeFrame: TimeFrame!
  $groupInterfaces: Boolean
  $groupDevices: Boolean
  $toRate: Boolean
) {
  accountMetrics(
    accountID: $accountID
    timeFrame: $timeFrame
    groupInterfaces: $groupInterfaces
    groupDevices: $groupDevices
  ) {
    from
    to
    sites {
      id
      name
      metrics(toRate: $toRate) {
        bytesTotal
        bytesDownstream
        bytesUpstream
      }
      interfaces {
        name
        metrics(toRate: $toRate) {
          bytesTotal
          bytesDownstream
          bytesUpstream
        }
      }
    }
  }
}
___EOL___
)

_variables=$(cat <<'___EOL___'
{
  "accountID": "${ACCOUNT_ID}",
  "timeFrame": "$(date -u '+utc.%Y-%m-%d/{00:00:00--%H:%M:%S}')",
  "groupInterfaces": false,
  "groupDevices": false,
  "toRate": false
}
___EOL___
)

curl -fsSL 
  -X POST "https://api.catonetworks.com/api/v1/graphql2" 
  -H "X-Api-Key: ${API_KEY}" 
  -H "Content-Type: application/json" 
  -d @- <<___EOL___
{"query":"$(echo ${_query})","variables":${_variables}}
___EOL___

Zabbix の LLD にて、「サイト」を検出するためのディスカバリ用のキーを実装します。
API のクエリ “entityLookup” の返す JSON を、LLD が利用できる形の JSON に加工します。

### 例: クエリ entityLookup の返す JSON
{
  "data": {
    "entityLookup": {
      "items": [
        {
          "entity": {
            "id": "100100",
            "name": "Tokyo-HeadOffice"
          }
        },
        {
          "entity": {
            "id": "100101",
            "name": "Osaka-BranchOffice"
          }
        }
      ],
      "total": 2
    }
  }
}

### 例: LLD に利用できる JSON
[
  {
    "{#SITEID}": "100100",
    "{#SITENAME}": "Tokyo-HeadOffice"
  },
  {
    "{#SITEID}": "100101",
    "{#SITENAME}": "Osaka-BranchOffice"
  }
]

実装

こちらも cato.account_metrics.sites と同様に、Zabbix の「外部チェック」タイプのキーとして、スクリプトを実装します。
JSON の加工のため、jq コマンドを利用します。

### /usr/lib/zabbix/externalscripts/cato.site.discovery (0755)
#!/usr/bin/env bash
#
# cato.site.discovery[account_id,api_key]
#
ACCOUNT_ID="${1:?}"
API_KEY="${2:?}"
_query=$(cat <<'___EOL___'
query query(
  $accountID: ID!
  $type: EntityType!
  $limit: Int
) {
  entityLookup(
    accountID: $accountID
    type: $type
    limit: $limit
  ) {
    items {
      entity {
        id
        name
      }
    }
    total
  }
}
___EOL___
)
_variables=$(cat <<'___EOL___'
{
  "accountID": "${ACCOUNT_ID}",
  "type": "site"
}
___EOL___
)
out=$(curl -fsSL 
  -X POST "https://api.catonetworks.com/api/v1/graphql2" 
  -H "X-Api-Key: ${API_KEY}" 
  -H "Content-Type: application/json" 
  -d @- <<'___EOL___'
{"query":"$(echo ${_query})","variables":${_variables}}
___EOL___
)
echo "${out}" | jq -M -c '[.data.entityLookup.items[] | {"{#SITEID}": .entity.id, "{#SITENAME}": .entity.name}]'

Zabbix のテンプレートを作成し、以下の要素を設定します。

- アイテム
　　　- cato.account_metrics.sites
- ディスカバリルール
　　　- lld_cato_site
- アイテムのプロトタイプ
　　　- cato.site.metric[{#SITEID},bytesTotal]
　　　- cato.site.metric[{#SITEID},bytesDownstream]
　　　- cato.site.metric[{#SITEID},bytesUpstream]

アイテム「cato.account_metrics.sites」を設定

下記のような、実装したカスタムキーを利用したアイテムを設定します。

Cato のアカウント ID や API キーは、マクロを設定しておき、テンプレートを適用するホスト側のマクロで設定が行えるようにしておきます。

また、このアイテムは、自動で生成したアイテムから値を取り出すため「マスターアイテム」として機能します。そのため、このアイテムの値を保持する必要はありません。そのため、「ヒストリを保存しない」という設定にしておくことがポイントです。

- キー
    - cato.account_metrics.sites[{$CATO_ACCOUNT_ID},{$CATO_API_KEY}]
- ヒストリの保存期間
    - ヒストリを保存しない

ディスカバリルール「lld_cato_site」を設定

実装したカスタムキーを利用し、下記のようなディスカバリルールを設定します。

- キー
    - cato.site.discovery[{$CATO_ACCOUNT_ID},{$CATO_API_KEY}]

アイテムのプロトタイプを設定

実装したアイテム cato.account_metrics.sites の値 (JSON) から、検出されたサイトの特定のメトリクスを取り出すためのアイテムを設定します。

Zabbix の「依存アイテム」タイプのアイテムを利用し、保存前処理を記述することで、マスターアイテム cato.account_metrics.sites から値を取り出します。
下記の bytesTotal の例のように、bytesDownstream, bytesUpstream についても同様に設定します。

bytesTotal の例

- タイプ
    - 依存アイテム
- キー
    - cato.site.metric[{#SITEID},bytesTotal]
- マスターアイテム
    - cato: Cato AccountMetrics Sites
       - cato.account_metrics.sites

保存前処理
- 1: JSONPath
    - $.data.accountMetrics.sites[?(@.id=="{#SITEID}")].metrics.bytesTotal.first()
- 2: 1 秒あたりの差分

作成したテンプレートを弊社の検証環境に適用し、CATO サイトのトラフィックを実際に取得してみました。
結果として、以下のようにアイテムが自動で設定され、期待通りデータが取得できていることが確認できました。

アイテムが自動設定されている様子


メトリクスが取得できている様子


今後は、「トリガーのプロトタイプ」を使い、契約帯域に迫った場合にアラートを上げる、ということも容易に実装できそうです。

本連載では、CATO の提供する GraphQL API を利用し、自社の CATO ネットワークの情報を取得して Zabbix に連携して監視する具体的な方法について、3 回にわたり解説してきました。

この仕組みを導入することで、拠点の増減があった場合でも、手動での設定を最小限に抑えながら、利用帯域の状況を効率的に把握できるようになります。

本シリーズが、環境構築や運用改善などの一助になれば幸いです。
最後までお読みいただき、ありがとうございました！