Troubleshooting

Comece pelo sintoma e localize a camada

Antes de reiniciar qualquer processo, descreva exatamente o sintoma: “item não atualiza”, “item unsupported”, “queue cresce”, “Proxy offline”, “alerta não chega” ou “frontend lento”. Cada sintoma aponta para caminhos diferentes.

Diagnóstico deve seguir o caminho do dado

Uma métrica passa por origem, rede, coletor, preprocessing quando aplicável, history cache, processamento, banco, trigger e eventualmente alerting. A melhor estratégia é descobrir até onde o dado chegou e onde deixou de avançar.

Não confunda ausência de dado com valor zero

Item sem atualização, item unsupported e item que retorna zero são situações diferentes. Um gráfico vazio pode indicar falha de coleta; zero pode ser um valor real; unsupported significa que o Zabbix detectou erro de processamento ou coleta.

O primeiro ponto de inspeção costuma ser o último valor

Verifique timestamp, valor, erro e histórico recente em Latest data. Se existe valor novo, a coleta funcionou; se trigger não mudou, investigue expressão. Se o valor não chega, desça para item, interface, Proxy e origem.

Teste isolado reduz variáveis

Quando o tipo de item permite, use o teste do frontend ou ferramenta equivalente para validar conexão, credencial, key, OID, URL ou preprocessing. Separar teste de coleta do agendamento ajuda a descobrir se o problema está no item ou na execução periódica.

NOT SUPPORTED é estado diagnóstico, não erro genérico

Um item pode ficar unsupported por timeout, autenticação, conversão de tipo, preprocessing, OID inexistente, key inválida ou resposta inesperada. Leia a mensagem de erro do item antes de alterar configuração.

Tipo de informação incorreto pode quebrar um item saudável

Se um item Numeric recebe texto que não pode ser convertido, a normalização pode falhar e o item ficar NOT SUPPORTED. Confirme o valor bruto e o tipo final esperado.

Cada etapa pode transformar ou destruir o valor

JSONPath, regex, XPath, JavaScript, conversões e validações são executados em sequência. Teste preprocessing com valor real e hipotético. Uma etapa correta isoladamente pode falhar porque a etapa anterior alterou o formato.

Tratamento de erro não deve esconder problema estrutural

Custom on fail pode descartar valor, definir valor substituto ou mensagem de erro em etapas compatíveis. Use para exceções esperadas, não para mascarar parsing permanentemente quebrado.

Fila de preprocessing indica trabalho pendente

Quando workers não acompanham o volume, tarefas aguardam processamento. Em 7.4.1, valores de itens sem preprocessing e sem dependentes podem bypassar o preprocessing manager, reduzindo carga. Se a fila cresce, procure payloads pesados, JavaScript, dependent items e workers saturados.

Diagnóstico interno mostra quem está consumindo tempo

Runtime control diaginfo=preprocessing fornece estatísticas internas. No 7.4.1, a saída inclui top items por quantidade/tamanho de valores recebidos e destaca itens com maiores tempos de processamento, facilitando encontrar outliers.

Queue é uma representação lógica de itens atrasados

A Queue do Zabbix mostra itens com refresh agendado que ainda aguardam atualização. Não é uma fila IPC física. Ela é excelente indicador operacional, mas alguns tipos — como trapper, dependent items, SNMP traps e certos logs ativos — não aparecem nela.

Quantidade global é menos útil que distribuição

Use Queue overview e Queue details para saber quais hosts, proxies e tipos de item estão atrasados. Um ou dois atrasos curtos podem ser normais; grandes conjuntos envelhecendo indicam problema estrutural.

Interface indisponível pode remover itens da queue

Itens podem deixar de ser contados quando a interface é marcada indisponível por problema de conexão. Portanto “queue zerada” não prova que todos os dispositivos estejam acessíveis. Combine queue com host availability e problemas de interface.

Monitore o Zabbix com itens internos

Itens zabbix[...] permitem observar queue, caches, processos, número de itens unsupported, performance requerida e outros estados internos. Alguns checks internos são relativamente pesados, então não configure consultas de alto custo em frequência excessiva.

Busy poller alto sugere espera ou concorrência insuficiente

Se uma classe de processo permanece ocupada por longos períodos e a queue correspondente cresce, investigue quantidade de processos, timeout, latência e comportamento dos alvos. Aumentar pollers sem validar causa pode deslocar o gargalo.

Timeout alto pode prender workers

Dispositivo lento ou inacessível pode manter pollers ocupados até o timeout. Em grande escala, dezenas de destinos lentos podem consumir toda a concorrência. Ajuste timeout com cuidado e corrija reachability ou filtros de descoberta.

Agent passivo: valide rede, porta, origem e key

Teste conectividade até o Agent, configuração Server/ServerActive, hostname quando aplicável, firewall e key. Use zabbix_get quando apropriado para reproduzir a coleta fora do Server.

Active check depende do host chegar ao Server/Proxy

Para active checks, o fluxo é invertido. Valide ServerActive, Hostname/HostnameItem, DNS/rota, TLS e se o host foi corretamente associado ao Server/Proxy esperado.

SNMP exige separar reachability, credencial e OID

Primeiro confirme UDP/161 e resposta SNMP a partir do coletor correto. Depois valide versão, community ou SNMPv3 e somente então OID/index. Misturar as três camadas aumenta tempo de diagnóstico.

Engine state e credenciais podem causar falhas persistentes

Alterações de engine ID, boots/time ou credenciais SNMPv3 podem exigir limpeza de cache SNMP em Server/Proxy em casos específicos. O runtime control snmp_cache_reload existe para limpar propriedades mantidas no cache.

OID inexistente agora pode tornar walk/discovery unsupported

No Zabbix 7.4, SNMP walk/discovery em que nenhum OID ou instância válida exista passa a retornar erro e tornar o item unsupported, em vez de simplesmente retornar vazio como em comportamento anterior. Isso é importante após upgrade.

Valide DNS, TCP, TLS, HTTP e conteúdo separadamente

HTTP agent pode falhar por resolução, rota, certificado, autenticação, redirect, timeout, status code ou preprocessing da resposta. Reproduza a requisição a partir do Server/Proxy para eliminar diferenças de caminho.

ODBC e banco adicionam dependências locais

Cheque DSN/driver, biblioteca, credencial, TLS, rede e query. Uma consulta válida no notebook do DBA não prova que funciona a partir do host/Proxy onde o check é executado.

Ambiente do daemon é diferente do shell do administrador

Scripts podem funcionar manualmente e falhar no Zabbix por PATH, usuário, permissões, SELinux/AppArmor, working directory, dependências ou timeout. Execute como usuário do daemon e com ambiente semelhante.

Quando valores chegam mas não avançam, observe o cache

History cache pode ficar pressionado por banco lento ou itens que acumulam valores. O Zabbix 7.4 adicionou melhorias de diagnóstico e comando history_cache_clear para um item específico. Use limpeza como medida de recuperação, não substituto para corrigir a causa.

Limpeza seletiva evita reinício completo

O runtime control history_cache_clear=target permite remover do history cache os valores de um item pelo ID. Isso é útil quando um item específico bloqueia processamento, especialmente em cenários de logs ou volume anormal.

Logs do 7.4 ajudam a apontar os maiores ofensores

Quando history cache fica cheio, o Zabbix 7.4 registra diagnóstico em nível de debug mais acessível e lista itens com maior número de valores no cache. Esse dado deve orientar a correção do item, fonte ou banco.

Problema de value cache aparece em funções históricas

Value cache acelera trigger expressions e calculated items. diaginfo=valuecache ajuda a identificar uso e configurações que exigem muito histórico. Se cache entra em low memory, o Server pode aumentar consultas ao banco e degradar avaliações.

Banco lento pode parecer problema em qualquer camada

History atrasado, frontend lento, queue indireta, Actions demoradas e alta utilização de syncers podem ter origem no banco. Observe CPU, I/O, locks, conexões, checkpoint/WAL, buffer pool e queries.

Erro de conexão precisa ser separado de lentidão

Verifique DNS, porta, TLS, credencial, limite de conexões e logs do SGBD. Se a conexão está estável mas writes são lentos, o problema já mudou de disponibilidade para performance.

Espaço livre é necessário, mas latência também

Filesystem com espaço suficiente pode estar saturado em I/O. Monitore latency, utilization, queue depth e comportamento durante housekeeping, checkpoint e backup.

Exclusões grandes podem produzir períodos de carga

Mudanças agressivas de retenção ou banco muito grande podem tornar housekeeping custoso. Analise duração, I/O e políticas de history/trends antes de culpar o daemon principal.

Sempre pergunte onde o item é executado

Um item atribuído a Proxy precisa ser testado a partir do Proxy, não do Server. DNS, rota, firewall, MIBs, scripts, certificados e credenciais locais podem ser diferentes.

Distingua coleta local de sincronização central

Se Proxy perde o Server, ele pode continuar coletando e armazenando localmente. Portanto “Latest data não chegou ao Server” não significa automaticamente que o Proxy deixou de coletar. Verifique buffer e comunicação Proxy→Server.

Compatibilidade importa após upgrade

Para funcionalidade completa, Proxy deve usar a mesma major version do Server 7.4. Proxies antigos podem continuar parcialmente funcionais, mas não receber certas atualizações de configuração; isso pode parecer falha misteriosa após upgrade.

Alteração no frontend pode levar tempo para chegar ao coletor

Active Proxy busca configuração periodicamente; Server e Proxy também trabalham com caches de configuração. Ao testar mudança recente, confirme que a configuração foi sincronizada ou force reload quando apropriado.

Recarregue configuração sem restart quando possível

O runtime control config_cache_reload força atualização do cache de configuração. É preferível a reiniciar o processo apenas para aplicar configuração já disponível.

Leia o log da camada correta

Server, Proxy, Agent, web server, PHP, banco e integração possuem logs diferentes. “Olhei o zabbix_server.log” não ajuda se o erro está no Proxy ou frontend. Alinhe timestamp e reproduza o problema enquanto observa o componente certo.

Aumente debug somente pelo tempo necessário

Debug elevado gera muito volume e pode expor detalhes sensíveis. Aumente de forma controlada, reproduza, capture evidência e retorne ao nível normal. Evite usar DebugLevel máximo como configuração permanente.

Nem sempre é necessário reiniciar para mudar debug

Runtime control pode aumentar ou reduzir log level de processos em execução, dependendo do componente. Isso é útil para troubleshooting seletivo e reduz impacto de restart.

Erro visual pode ser PHP, web server, banco ou permissão

Página branca, timeout, gráfico lento ou erro de sessão exigem verificar logs de PHP/web server, conectividade ao banco, permissões e recursos do frontend. Nem todo problema visto no navegador é problema do Zabbix Server.

Erro da API deve ser reproduzido com request mínimo

Reduza payload e método ao caso mínimo, valide token/role, parâmetros e versão da API. Erros de permissão e filtros vazios podem parecer ausência de dados. Evite testar com Super Admin se a integração usa usuário restrito.

Valor correto + evento errado aponta para expressão

Se Latest data mostra exatamente o valor esperado, mas trigger não abre ou não recupera, revise função, período, operadores, macros, recovery expression, dependências e múltiplos eventos.

Trigger que flapeia precisa de desenho, não mais notificações

Use condições distintas de problem/recovery quando a métrica oscila próximo ao limite. Se o sinal é ruidoso, média, min/max, count ou persistência temporal podem ser mais adequados que last().

Problema dependente pode estar sendo suprimido corretamente

Se uma trigger não gera ação durante falha do upstream, confira dependencies. O evento pode existir ou ser tratado de forma diferente porque a causa raiz está ativa. Antes de remover dependência, confirme topologia.

Manutenção muda tratamento de eventos e alertas

Se ninguém foi notificado ou coleta parece diferente durante mudança, confirme maintenance, tipo de manutenção e período. Problema pode estar corretamente suprimido conforme política.

Evento existe e não há mensagem: siga a Action

Valide fonte de evento, condições, operações, steps de escalation, destinatário, permissões, user media, período ativo, severidade e media type. Alerting é pipeline; diagnostique de cima para baixo.

HTTP externo precisa ser tratado como dependência

Verifique DNS, TLS, timeout, status code, token, payload e rate limit do destino. Teste o media type isoladamente. Um HTTP 200 também pode conter erro lógico dependendo da API.

SMTP envolve mais que endereço e senha

Valide DNS, porta, TLS, autenticação, relay, sender, políticas antispam e resposta do servidor SMTP. Mensagem aceita pelo SMTP pode ainda ser filtrada posteriormente.

Sintoma global pede baseline global

Compare CPU, memória, NVPS, queue, busy processes, preprocessing, caches, banco e storage. Sem baseline, qualquer valor parece suspeito. Procure o primeiro indicador que mudou antes da degradação.

Comportamento novo pode ser mudança documentada

Após upgrade, consulte upgrade notes e changelog. Mudanças como SNMP walk unsupported ou novos caminhos de preprocessing podem alterar sintomas sem haver regressão. Não force configuração antiga a reproduzir comportamento obsoleto sem entender a mudança.

Caso mínimo é a ferramenta de diagnóstico mais poderosa

Copie um item problemático para laboratório, reduza preprocessing, teste uma URL simples, um OID, um host ou uma trigger. Quanto menor o caso reproduzível, mais fácil separar configuração de ambiente.

Capture antes de corrigir

Antes de restart, clear cache ou failover, registre timestamps, item IDs, event IDs, logs, queue, process utilization e estado do banco. Correção sem evidência resolve o momento mas não ensina a causa.

Saiba quando o problema deixou de ser do Zabbix

Se coleta manual a partir do Proxy falha exatamente como o item, o problema pode estar no dispositivo, rede ou serviço externo. Troubleshooting eficiente também sabe encerrar a investigação na camada do monitoramento e escalar com evidência.

Descubra até onde o dado chegou

ORIGEM
  │
  ├─ responde manualmente?
  ▼
SERVER / PROXY
  │
  ├─ item executou?
  ▼
PREPROCESSING
  │
  ├─ transformação funciona?
  ▼
HISTORY CACHE
  │
  ├─ cache está saudável?
  ▼
DATABASE
  │
  ├─ valor foi persistido?
  ▼
TRIGGER / EVENT
  │
  ├─ expressão foi satisfeita?
  ▼
ACTION / MEDIA
  │
  ├─ condição/operação casou?
  ▼
DESTINATÁRIO

Primeiro ponto onde a resposta muda:
→ camada prioritária de investigação.

Mensagem → hipótese inicial

Atraso por padrão

Ferramentas úteis sem restart

# Recarregar configuração
zabbix_server -R config_cache_reload
zabbix_proxy  -R config_cache_reload

# Diagnóstico geral
zabbix_server -R diaginfo
zabbix_proxy  -R diaginfo

# Diagnóstico específico
zabbix_server -R diaginfo=valuecache
zabbix_server -R diaginfo=historycache
zabbix_server -R diaginfo=preprocessing

# Limpar item específico do history cache
zabbix_server -R history_cache_clear=<ITEM_ID>
zabbix_proxy  -R history_cache_clear=<ITEM_ID>

# Recarregar cache SNMP
zabbix_server -R snmp_cache_reload
zabbix_proxy  -R snmp_cache_reload

Teste no mesmo ponto onde o Zabbix coleta

# Agent passivo
zabbix_get -s 10.0.0.10 -k agent.ping

# SNMP
snmpget  -v2c -c COMMUNITY 10.0.0.20 1.3.6.1.2.1.1.3.0
snmpwalk -v2c -c COMMUNITY 10.0.0.20 1.3.6.1.2.1.2.2

# TCP
nc -vz host.example 10050

# HTTP/TLS
curl -v https://app.example/health

# DNS
dig app.example

# Rota
traceroute app.example

# IMPORTANTE:
# execute do Server ou Proxy que realmente faz a coleta.

Sintoma → evidência → ação

Capture evidência reutilizável

INCIDENTE
Data/hora:
Sintoma:
Host:
Item ID:
Proxy:
Trigger/Event ID:

ÚLTIMO VALOR:
Timestamp:
Valor:
Erro:

TESTE MANUAL:
Comando:
Origem do teste:
Resultado:

ZABBIX:
Queue:
Busy process:
Cache:
diaginfo:

BANCO:
Latency:
I/O:
Locks:

MUDANÇAS RECENTES:
Upgrade:
Template:
Firewall:
Credencial:
Deploy:

HIPÓTESE:
Evidência a favor:
Evidência contra:

CORREÇÃO:
Ação:
Resultado:
Causa raiz:
Prevenção:

Como perder a causa raiz

Treine falhas antes da produção

Antes de reiniciar qualquer coisa

Base factual

Conteúdo estruturado a partir da documentação oficial do Zabbix 7.4 sobre Queue, Zabbix internal items, preprocessing e testes, value cache, runtime control, history cache, SNMP, Proxy e notas de upgrade do 7.4. Os fluxos de investigação, matrizes de diagnóstico, template de incidente, laboratórios e metodologia de troubleshooting são síntese editorial própria.

Linha Zabbix 7.4

Diagnóstico deve seguir o caminho do dado e separar ausência de dado, valor zero e item unsupported. Capture timestamps, queue, logs e último valor antes de reiniciar processos.