Protocolos de verificação passiva e ativa

Esta seção fornece detalhes do protocolo sobre verificações passivas e ativas realizadas por Zabbix agent e Zabbix agent 2.

O Zabbix usa um protocolo de comunicação baseado em JSON para se comunicar com os agents.

Os protocolos do Zabbix agent e do Zabbix agent 2 foram unificados desde o Zabbix 7.0. A diferença entre as solicitações/respostas do Zabbix agent e do Zabbix agent 2 é expressa pelo valor da tag "variant".

Verificações passivas

Uma verificação passiva é uma solicitação simples de dados. O server ou proxy do Zabbix solicita alguns dados (por exemplo, carga de CPU) e o agent do Zabbix envia de volta o resultado para o server.

As verificações passivas são executadas de forma assíncrona - não é necessário receber a resposta de uma solicitação antes que outras verificações sejam iniciadas. A resolução de DNS também é assíncrona.

O poller do agent tentará se conectar a todos os endereços retornados pela consulta DNS. Isso garante que, se um endereço IP estiver inacessível, o poller tentará o próximo endereço disponível, aumentando a probabilidade de uma conexão bem-sucedida. Essa melhoria se aplica tanto ao server quanto ao proxy do Zabbix.

A concorrência máxima de verificações assíncronas é 1000 (definida por MaxConcurrentChecksPerPoller).

O número de pollers assíncronos do agent é definido pelo parâmetro StartAgentPollers.

Solicitação do server

Para a definição do cabeçalho e do comprimento dos dados, consulte os detalhes do protocolo.

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

Resposta do agent

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

Por exemplo, para itens suportados:

1. O server abre uma conexão TCP
2. O server envia <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"agent.ping","timeout":3}]}
3. O agent lê a solicitação e responde com <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"value":1}]}
4. O server processa os dados para obter o valor, '1' no nosso caso
5. A conexão TCP é fechada

Para itens não suportados:

1. O server abre uma conexão TCP
2. O server envia <HEADER><DATALEN>{"request":"passive checks","data":[{"key":"vfs.fs.size[/nono]","timeout":3}]}
3. O agent lê a solicitação e responde com <HEADER><DATALEN>{"version":"8.0.0","variant":2,"data":[{"error":"Unsupported item key."}]}
4. O server processa os dados, altera o estado do item para não suportado com a mensagem de erro especificada
5. A conexão TCP é fechada

Failover para o protocolo antigo

Para garantir que o Zabbix server ou proxy possa funcionar com agents de versões anteriores à 7.2, que usam o protocolo em texto simples, foi implementado um failover para o protocolo antigo.

As verificações passivas são realizadas usando o protocolo JSON (7.0 e posteriores) após a reinicialização ou quando a configuração da interface é alterada.
Se nenhuma resposta JSON válida for recebida (o agent enviou "ZBX_NOTSUPPORTED"), o Zabbix armazenará em cache a interface como protocolo antigo e tentará novamente a verificação enviando apenas a chave do item.

Observe que, a cada hora, o Zabbix server/proxy tentará novamente trabalhar com o novo protocolo em todas as interfaces, retornando ao protocolo antigo se necessário.

Verificações ativas

As verificações ativas exigem um processamento mais complexo. O agent deve primeiro recuperar do server/proxy uma lista de items e/ou comandos remotos para processamento independente.

Os servers/proxies dos quais obter as verificações ativas estão listados no parâmetro 'ServerActive' do arquivo de configuração do agent. A frequência de solicitação dessas verificações é definida pelo parâmetro 'RefreshActiveChecks' no mesmo arquivo de configuração. No entanto, se a atualização das verificações ativas falhar, a tentativa é repetida após 60 segundos fixos.

O agent então envia periodicamente os novos valores para o server(s). Se o agent recebeu algum remote commands para executar, o resultado da execução também será enviado. Observe que a execução de remote command em um agent ativo é suportada desde o Zabbix agent 7.0.

Obtendo a lista de items

Solicitação do agent

A solicitação de active checks é usada para obter os active checks a serem processados pelo agent.
Essa solicitação é enviada pelo agent na inicialização e, depois, em intervalos de 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"
}

Resposta do server

A resposta de active checks é enviada pelo server de volta ao agent após o processamento da solicitação de active checks.

{
  "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
    }
  ]
}

O server deve responder com sucesso.

Por exemplo:

1. O agent abre uma conexão TCP
2. O agent solicita a lista de checks
3. O server responde com uma lista de items e comandos remotos a serem executados
4. O agent interpreta a resposta
5. A conexão TCP é encerrada
6. O agent inicia a coleta periódica de dados e executa comandos remotos (suportado desde o Zabbix agent 7.0)

Envio de dados coletados

Agent envia

A solicitação de dados do agent contém os valores dos items coletados e os valores dos comandos remotos executados (se houver).

{
  "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
}

Um ID virtual é atribuído a cada valor. O ID do valor é um contador simples crescente, exclusivo dentro de uma sessão de dados (identificada pelo token da sessão). Esse ID é usado para descartar valores duplicados que possam ser enviados em ambientes com conectividade ruim.

Resposta do server

A resposta de dados do agent é enviada pelo server de volta ao agent após o processamento da solicitação de dados do agent.

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

Por exemplo:

1. O agent abre uma conexão TCP
2. O agent envia uma lista de valores
3. O server processa os dados e envia o status de volta
4. A conexão TCP é encerrada

Mensagem de heartbeat

Agent envia

A mensagem de heartbeat é enviada por um agent ativo para o server/proxy do Zabbix a cada HeartbeatFrequency segundos (configurado no arquivo de configuração do Zabbix agent/agent 2).

Ela é usada para monitorar a disponibilidade de verificações ativas.

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

Resposta de redirecionamento

Quando um host é reassigned, o server pode instruir o agent a redirecionar seu heartbeat (e as verificações ativas subsequentes) para outra instância de proxy ou server.

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

Protocolo XML antigo