Itens e pré-processamento

O item é a unidade básica da observação

Cada item responde a uma pergunta mensurável: o host responde ICMP? quantos bits por segundo entram na interface? qual a temperatura? qual o estado administrativo? Um item deve ter propósito, unidade, frequência e política de retenção definidos. Criar itens “porque o equipamento fornece” transfere o custo da seleção para banco, frontend e operador.

Da coleta ao banco: entenda o caminho antes de otimizar

No Zabbix 7.4, valores que exigem pré-processamento — ou alimentam itens dependentes — passam pelo preprocessing manager e seus workers. Depois, os resultados seguem para o history cache e posteriormente são normalizados e sincronizados com o banco. Desde 7.4.1, valores que não precisam de preprocessing nem possuem dependentes podem seguir diretamente ao history cache/LLD manager, evitando trabalho desnecessário no preprocessing manager.

O tipo do valor é parte da modelagem

Numeric unsigned, Numeric float, Character, Log e Text não são escolhas cosméticas. A conversão para o tipo desejado ocorre ao fim do pipeline e uma conversão inválida pode tornar o item NOT SUPPORTED. Defina o tipo conforme a semântica final da métrica, não conforme a aparência temporária do valor bruto.

Nome para humanos, key para identidade técnica

O nome deve ser simples e descritivo. Uma convenção útil é “objeto: métrica”, por exemplo “Interface ge-0/0/1: Bits in”. A guideline oficial recomenda destacar itens mestres com “Get” quando isso ajuda a deixar claro que o item é coletor, não a métrica final. Keys devem ser estáveis, únicas no host e previsíveis.

Frequência é resolução temporal — e também custo

Um intervalo de 30 segundos produz dez vezes mais amostras que um intervalo de 5 minutos. Antes de reduzir o intervalo, pergunte qual evento você precisa enxergar e por quanto tempo ele pode durar sem ser observado. Disponibilidade, tráfego, temperatura, inventário e versão de firmware não precisam da mesma resolução.

Transforme o dado antes de persistir

O preprocessing aplica etapas sequenciais ao valor recebido. Ele pode converter unidades, calcular taxa de mudança, aplicar regex, JSONPath, XPath, JavaScript, Prometheus patterns, validar intervalos, substituir valores e descartar repetições. A ordem das etapas importa: cada etapa recebe o resultado da anterior.

Preprocessing também é uma fronteira de qualidade

Por padrão, uma etapa que falha pode levar o item a NOT SUPPORTED. Em transformações compatíveis, Custom on fail permite descartar o valor, definir um valor substituto ou produzir uma mensagem de erro. Isso deve ser usado para modelar exceções esperadas, não para esconder parsing quebrado.

Uma consulta, várias métricas

Quando uma API, comando ou SNMP walk retorna muitas métricas, prefira coletar uma vez e extrair várias séries com dependent items. O novo valor do master item alimenta automaticamente seus dependentes, que compartilham a cadência do mestre. Isso reduz chamadas externas e mantém métricas relacionadas temporalmente próximas.

Itens dependentes podem formar pipelines

Um dependent item também pode ser master de outros dependent items. Isso permite decompor payloads complexos em camadas. A dependência, porém, permanece limitada ao mesmo host/template. Profundidade deve ser usada para clareza e reaproveitamento, não para criar cadeias difíceis de diagnosticar.

Colete o documento; extraia as métricas

Para uma API que devolve JSON com CPU, memória, temperatura e estado, uma arquitetura eficiente é um HTTP agent master item seguido de dependentes com JSONPath. A mesma resposta pode alimentar dezenas de métricas sem dezenas de requests.

Walk como matéria-prima

Em tabelas SNMP, uma única coleta ampla pode alimentar LLD e dependent items. Isso é especialmente útil quando dezenas ou centenas de índices precisam ser processados. Para templates portáveis, as guidelines recomendam OIDs numéricos no campo SNMP OID, evitando dependência da instalação local de MIBs.

Counter não é taxa

Contadores acumulativos de octetos não representam bit/s diretamente. O pipeline típico calcula Change per second e depois multiplica por 8. Para interfaces de alta velocidade, contadores de 64 bits evitam wraps frequentes. Reset, reboot e wrap precisam ser considerados ao interpretar deltas.

Nem todo valor coletado precisa virar uma linha no banco

Discard unchanged remove valores repetidos; Discard unchanged with heartbeat preserva periodicamente um valor mesmo quando nada mudou. Isso é valioso para estados, inventário e métricas quase estáticas. Não aplique cegamente em séries em que cada amostra é necessária para análise estatística.

Detalhe e memória de longo prazo são coisas diferentes

History mantém valores individuais. Trends, para dados numéricos, guardam agregações horárias e permitem análise de longo prazo com custo muito menor. A retenção deve ser definida pelo uso: troubleshooting recente precisa de detalhe; planejamento de capacidade geralmente aceita agregação.

Guardar payload bruto para sempre raramente faz sentido

Master items podem transportar JSON/XML/texto volumoso usado apenas para alimentar dependentes. As guidelines oficiais sugerem reduzir a retenção do master; 1 hora é uma referência segura porque history=0 elimina evidência útil para troubleshooting e pode prejudicar verificações como nodata().

Preprocessing tem fila, workers e cache

O preprocessing manager distribui tarefas aos workers. Sequências que dependem do valor anterior — como change e throttling — exigem ordem. O Zabbix também possui cache de preprocessing para certos padrões repetidos em dependent items, como JSONPath e Prometheus, reduzindo trabalho duplicado. Fila crescente é sinal para investigar desenho, volume e capacidade dos workers.

Monitore o próprio pipeline

Em ambientes grandes, não basta monitorar dispositivos: acompanhe queue, processos internos, utilização dos preprocessors, history cache e banco. Um dashboard saudável deve permitir diferenciar “equipamento lento” de “coletor saturado” e “banco atrasado”.

Erros que multiplicam custo silenciosamente

Evite uma chamada HTTP por métrica quando uma resposta já contém todas; intervalos iguais para qualquer dado; JavaScript para transformações simples que JSONPath/regex resolvem; history longo para payload bruto; itens sem unidade; keys inconsistentes; armazenamento de valores que nunca serão usados; e Custom on fail configurado apenas para esconder erros.

Uma forma prática de pensar no processamento

FONTE
  │
  ├─ SNMP / Agent / HTTP / Script / Trapper / ...
  ▼
ITEM MESTRE
  │
  ├─ preprocessing do mestre
  │
  ▼
PREPROCESSING MANAGER / WORKERS
  │
  ├──────────────► DEPENDENT: CPU
  ├──────────────► DEPENDENT: MEMÓRIA
  ├──────────────► DEPENDENT: TEMPERATURA
  └──────────────► LLD / outros dependentes
  │
  ▼
HISTORY CACHE
  │
  ▼
NORMALIZAÇÃO
  │
  ▼
BANCO
  ├─ history: amostras individuais
  └─ trends: agregações horárias numéricas

Uma API, quatro métricas, uma chamada

{
  "cpu": 37.4,
  "memory": {"used_pct": 68.1},
  "temperature": 46.2,
  "status": "online"
}

De octetos acumulados para bit/s

Entrada SNMP:
ifHCInOctets = contador crescente de octetos

Preprocessing:
1. Change per second
2. Custom multiplier = 8

Saída:
bit/s

Exemplo matemático: se o contador aumenta 75.000.000 octetos em 30 s, a taxa média é 2.500.000 B/s; multiplicando por 8, temos 20.000.000 bit/s = 20 Mbit/s.

Calcule antes de coletar

amostras/dia = 86.400 / intervalo_em_segundos

30 s  = 2.880 amostras/dia/item
60 s  = 1.440 amostras/dia/item
300 s =   288 amostras/dia/item

10.000 itens @ 30 s  = 28.800.000 amostras/dia
10.000 itens @ 300 s =  2.880.000 amostras/dia

Esses números não equivalem diretamente ao tamanho do banco — índices, compressão, engine, tipos de valor e housekeeping alteram o armazenamento — mas mostram a ordem de grandeza produzida por uma simples decisão de intervalo.

Qual ferramenta usar?

Antes de liberar um conjunto de itens

Base factual

Conteúdo construído a partir da documentação oficial Zabbix 7.4 sobre items, dependent items, preprocessing, fluxo interno, history/trends e das Template Guidelines oficiais. Os modelos de decisão, cálculos, arquitetura operacional, exemplos e recomendações editoriais são síntese própria.

Linha Zabbix 7.4

Itens dependentes continuam sendo uma ferramenta central para reduzir coletas redundantes. Use master items com preprocessing previsível e valide erro, descarte e cardinalidade.