パッシブおよびアクティブチェックのプロトコル

このセクションでは、Zabbix agent と Zabbix agent 2 によって実行されるパッシブチェックおよびアクティブチェックのプロトコル詳細を説明します。

Zabbix は、エージェントとの通信に JSON ベースの通信プロトコルを使用します。

Zabbix agent と Zabbix agent 2 のプロトコルは、Zabbix 7.0 以降で統一されています。Zabbix agent と Zabbix agent 2 のリクエスト/レスポンスの違いは、「variant」タグの値で表されます。

パッシブチェック

パッシブチェックは、単純なデータ要求です。Zabbix サーバーまたはプロキシが 何らかのデータ（たとえば CPU 使用率）を要求し、Zabbix エージェントが結果を サーバーに返します。

パッシブチェックは非同期で実行されます。つまり、他のチェックが開始される前に 1つの要求への応答を受信する必要はありません。DNS 解決も同様に非同期です。

エージェントポーラーは、DNS ルックアップで返されたすべてのアドレスへの接続を試行します。これにより、1つの IP アドレスに到達できない場合でも、ポーラーは次に利用可能なアドレスを試し、接続成功の可能性を高めます。この拡張は Zabbix サーバーとプロキシの両方に適用されます。

非同期チェックの最大同時実行数は 1000 です（MaxConcurrentChecksPerPoller により定義）。

非同期エージェントポーラーの数は StartAgentPollers パラメーターで定義されます。

サーバー要求

ヘッダーとデータ長の定義については、protocol details を参照してください。

{
  "request": "passive checks",
  "data": [
    {
      "key": "agent.version",
      "timeout": 3
    }
  ]
}

エージェント応答

{
  "version": "8.0.0",
  "variant": 2,
  "data": [
    {
      "value": "8.0.0"
    }
  ]
}

たとえば、サポートされているアイテムの場合:

1. サーバーが TCP 接続を開く
2. サーバーが <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]} を送信する
3. エージェントが要求を読み取り、次のように応答する <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"value":1}]}
4. サーバーがデータを処理して、ここでは値 '1' を取得する
5. TCP 接続が閉じられる

サポートされていないアイテムの場合:

1. サーバーが TCP 接続を開く
2. サーバーが <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]} を送信する
3. エージェントが要求を読み取り、次のように応答する <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
4. サーバーがデータを処理し、指定されたエラーメッセージとともにアイテムの状態をサポート対象外に変更する
5. TCP 接続が閉じられる

古いプロトコルへのフェイルオーバー

Zabbix サーバーまたはプロキシが、プレーンテキストプロトコルを使用する 7.2 より前のバージョンのエージェントと連携できるように、古いプロトコルへのフェイルオーバーが実装されています。

パッシブチェックは、再起動後またはインターフェース設定が変更されたときに、JSON プロトコル（7.0 以降）を使用して実行されます。
応答として有効な JSON が受信されない場合（エージェントが "ZBX_NOTSUPPORTED" を送信した場合）、Zabbix はそのインターフェースを古いプロトコルとしてキャッシュし、アイテムキーのみを送信してチェックを 再試行 します。

なお、Zabbix サーバー/プロキシは 1 時間ごとに、すべてのインターフェースで再び新しいプロトコルでの動作を試み、必要に応じて古いプロトコルにフォールバックします。

アクティブチェック

アクティブチェックには、より複雑な処理が必要です。
エージェントはまず、独立して処理するために、サーバー/プロキシからアイテムおよび/またはリモートコマンドの一覧を取得する必要があります。

アクティブチェックの取得元となるサーバー/プロキシは、エージェントの設定ファイルの 'ServerActive' パラメータに一覧表示されます。
これらのチェックを要求する頻度は、同じ設定ファイル内の 'RefreshActiveChecks' パラメータで設定されます。
ただし、アクティブチェックの更新に失敗した場合は、60秒後に再試行されます。

エージェントはその後、定期的に新しい値をサーバーに送信します。 エージェントが実行するように remote commands を受信していた場合は、実行結果も送信されます。 アクティブエージェントでのリモートコマンド実行は、Zabbix agent 7.0 以降でサポートされていることに注意してください。

アイテム一覧の取得

エージェント要求

active checks request は、エージェントによって処理される active checks を取得するために使用されます。
この要求はエージェント起動時に送信され、その後は RefreshActiveChecks の間隔で送信されます。

{
  "request": "active checks",
  "host": "Zabbix server",
  "host_metadata": "mysql,nginx",
  "interface": "zabbix.server.lan",
  "ip": "159.168.1.1",
  "port": 12050,
  "version": "8.0.0",
  "variant": 2,
  "config_revision": 1,
  "session": "e3dcbd9ace2c9694e1d7bbd030eeef6e"
}

サーバー応答

active checks response は、active checks request の処理後にサーバーからエージェントへ送信されます。

{
  "response": "success",
  "config_revision": 2,
  "data": [
    {
      "key": "system.uptime",
      "itemid": 1234,
      "delay": "10s",
      "lastlogsize": 0,
      "mtime": 0
    },
    {
      "key": "agent.version",
      "itemid": 5678,
      "delay": "10m",
      "lastlogsize": 0,
      "mtime": 0,
      "timeout": "30s"
    }
  ],
  "commands": [
    {
      "command": "df -h --output=source,size / | awk 'NR>1 {print $2}'",
      "id": 1324,
      "wait": 1
    }
  ]
}

サーバーは success を返さなければなりません。

例:

1. エージェントが TCP 接続を開く
2. エージェントがチェック一覧を要求する
3. サーバーがアイテム一覧と実行するリモートコマンドを返す
4. エージェントが応答を解析する
5. TCP 接続が閉じられる
6. エージェントが定期的なデータ収集を開始し、リモートコマンドを実行する（Zabbix agent 7.0 以降でサポート）

収集済みデータの送信

エージェントの送信

エージェントのデータ要求には、収集されたアイテム値と、実行されたリモートコマンドの値（ある場合）が含まれます。

{
  "request": "agent data",
  "data": [
    {
      "id": 1,
      "itemid": 5678,
      "value": "7.0.0",
      "clock": 1712830783,
      "ns": 76808644
    },
    {
      "id": 2,
      "itemid": 1234,
      "value": "69672",
      "clock": 1712830783,
      "ns": 77053975
    }
  ],
  "commands": [
    {
      "id": 1324,
      "value": "16G"
    }
  ],
  "session": "8495cd52070e6ca52b371f29c8574165",
  "host": "Zabbix server",
  "version": "8.0.0",
  "variant": 2
}

各値には仮想 ID が割り当てられます。値 ID は単純な昇順のカウンターで、1つのデータセッション（セッショントークンで識別）内で一意です。この ID は、接続品質の悪い環境で送信される可能性のある重複値を破棄するために使用されます。

サーバー応答

エージェントデータの応答は、サーバーがエージェントデータ要求を処理した後にサーバーからエージェントへ送信されます。

{
  "response": "success",
  "info": "processed: 2; failed: 0; total: 2; seconds spent: 0.003534"
}

例:

1. エージェントが TCP 接続を開く
2. エージェントが値の一覧を送信する
3. サーバーがデータを処理し、ステータスを返す
4. TCP 接続が閉じられる

ハートビートメッセージ

エージェントが送信

ハートビートメッセージは、アクティブなエージェントから Zabbix サーバー/プロキシへ、HeartbeatFrequency 秒ごとに送信されます（Zabbix agent/agent 2 の設定ファイルで構成）。

これは、アクティブチェックの可用性を監視するために使用されます。

{
  "request": "active check heartbeat",
  "host": "Zabbix server",
  "heartbeat_freq": 60,
  "version": "8.0.0",
  "variant": 2
}

リダイレクト応答

ホストが再割り当てされた場合、サーバーはエージェントに対して、ハートビート（および以降のアクティブチェック）を別のプロキシまたはサーバーインスタンスへリダイレクトするよう指示できます。

  {
    "response": "failed",
    "redirect": {
      "revision": 2,
      "address": "192.0.2.1:10055"
    }
  }

旧XMLプロトコル