fix: ajustes do template

This commit is contained in:
João Pedro 2026-01-06 12:04:50 -03:00
parent be2867ecd6
commit 033347b005
4 changed files with 133 additions and 567 deletions

View File

@ -1,457 +0,0 @@
Arquitetura Técnica e Engenharia de Templates Zabbix 7.0 via YAML
1. Introdução: A Mudança de Paradigma para Configuração como Código
A evolução das plataformas de observabilidade de nível empresarial atingiu um ponto de inflexão com o lançamento do Zabbix 7.0 LTS. Esta versão não representa apenas um incremento funcional, mas consolida uma mudança fundamental na gestão de configurações: a transição de uma administração baseada em interface gráfica (GUI) e banco de dados para uma metodologia de "Monitoramento como Código" (MaC). Central para essa transição é a padronização do formato YAML (Yet Another Markup Language) como o meio primário para definição, exportação e versionamento de templates.1
Historicamente, a engenharia de monitoramento no Zabbix dependia de arquivos XML verbosos ou manipulação direta via frontend, métodos que dificultavam a integração com pipelines modernos de CI/CD e práticas de GitOps. O XML, embora estruturado, carecia de legibilidade humana e facilidade de edição manual, tornando a revisão de código e a detecção de diferenças (diffs) processos árduos. Com o Zabbix 7.0, a estrutura YAML atinge um nível de maturidade que permite aos arquitetos de sistemas e engenheiros de DevOps escrever templates complexos "do zero", dissociando a lógica de monitoramento da instância do servidor.3
Este relatório técnico oferece uma análise exaustiva da engenharia de templates Zabbix 7.0 em YAML. Exploraremos não apenas a sintaxe, mas as implicações arquiteturais da gestão de UUIDs, a mecânica intrínseca da coleta nativa do Zabbix Agent 2, os fundamentos matemáticos dos triggers preditivos e a integração de camadas de visualização diretamente no código do template. O domínio destes elementos é essencial para construir pipelines de observabilidade resilientes, portáveis e escaláveis.
________________
2. Fundamentos Arquiteturais do Schema YAML no Zabbix 7.0
A construção de um template YAML válido exige uma compreensão profunda do schema que o rege. Diferente de formatos de configuração livres, o Zabbix impõe uma hierarquia estrita que deve ser respeitada para garantir a integridade referencial durante a importação.
2.1 A Estrutura Raiz e Controle de Versionamento
O documento YAML começa com o nó raiz zabbix_export, que atua como o namespace global para o arquivo. Imediatamente subordinado a ele, encontra-se o parâmetro version. Para o Zabbix 7.0, este valor deve ser explicitamente declarado como 7.0. O parser de importação do Zabbix utiliza este campo para determinar quais conversores de banco de dados aplicar. Embora o servidor Zabbix possua compatibilidade retroativa (permitindo a importação de templates 6.0, por exemplo), a criação de um template novo deve aderir estritamente à versão 7.0 para desbloquear recursos modernos como widgets avançados e novos tipos de item.1
Uma distinção crítica introduzida nas versões recentes e solidificada na 7.0 é a separação entre grupos de templates e grupos de hosts. Anteriormente, ambos compartilhavam a entidade groups. No schema 7.0, é obrigatório definir template_groups na raiz para a organização lógica dos templates. Falhar em distinguir isso pode resultar em erros de validação ou na criação de templates "órfãos" no frontend.
Estrutura Raiz Canônica:
YAML
zabbix_export:
version: '7.0'
template_groups:
- uuid: a571c0d144b14fd4a87a9d9b2aa9fcd6
name: Templates/Applications
templates:
- uuid:...
A indentação e a estrutura de lista (hífen -) são cruciais. O Zabbix utiliza um parser YAML estrito; erros de indentação ou mistura de tabs e espaços invalidarão o arquivo inteiro.3
2.2 O Imperativo do UUID: Estabilidade em GitOps
Um dos desafios mais profundos na criação manual de templates é a gestão de Identificadores Únicos Universais (UUIDs). No banco de dados relacional do Zabbix (seja PostgreSQL ou MySQL), as entidades são ligadas por IDs inteiros sequenciais (itemid, triggerid). No entanto, esses IDs são efêmeros e específicos da instância. Ao exportar um template, o Zabbix substitui essas chaves primárias por UUIDs de 32 caracteres hexadecimais para garantir a portabilidade.5
Quando um engenheiro assume a autoria do YAML, ele se torna responsável pela geração e manutenção desses identificadores. A regra cardinal do desenvolvimento de templates em YAML é: A persistência do UUID é sagrada.
2.2.1 Consequências da Instabilidade do UUID
Considere um cenário de fluxo de trabalho GitOps:
1. Um item "Carga de CPU" é criado no YAML com um UUID aleatório ($UUID_A$).
2. O template é importado para o Zabbix, que cria o registro no banco de dados e começa a coletar dados históricos vinculados a esse item.
3. O engenheiro edita o YAML para ajustar o intervalo de coleta, mas, por descuido ou uso de um gerador automático, altera o UUID para ($UUID_B$).
4. Ao reimportar, o Zabbix interpreta a mudança não como uma atualização, mas como duas operações atômicas: a exclusão do item associado a $UUID_A$ (e consequente perda de todo o histórico de dados) e a criação de um novo item associado a $UUID_B$.
Esta "rotatividade" de UUIDs destrói a continuidade dos dados, inviabilizando análises de tendência de longo prazo (SLA). Portanto, ao criar templates do zero, deve-se gerar UUIDs criptograficamente seguros uma única vez e mantê-los estáticos durante todo o ciclo de vida do template.5
2.2.2 Algoritmos de Geração e Prevenção de Colisão
O Zabbix espera uma string hexadecimal de 32 caracteres. Embora o formato padrão UUID v4 inclua hifens (ex: 550e8400-e29b-41d4-a716-446655440000), o schema de exportação do Zabbix frequentemente os remove ou normaliza. Para máxima compatibilidade e adesão ao padrão visual dos templates oficiais, recomenda-se o uso de strings de 32 caracteres minúsculas.
Metodologia de Geração para Autores:
Engenheiros não devem tentar "inventar" UUIDs manualmente (ex: 111111...), pois isso aumenta o risco de colisões globais, especialmente se o template for compartilhado publicamente ou importado em ambientes com múltiplos servidores. Deve-se utilizar ferramentas de linha de comando ou scripts para gerar blocos de identificadores:
Bash
# Exemplo de geração segura em shell UNIX
uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]'
No arquivo YAML, o campo uuid é obrigatório para o objeto template principal e crítico para todas as subentidades (itens, triggers, regras de descoberta) para permitir diffs precisos e atualizações idempotentes.5
________________
3. Estratégia de Aquisição de Dados: O Poder dos Itens Nativos
A eficiência de uma plataforma de monitoramento é definida pela razão entre a utilidade da informação coletada e o custo computacional de sua coleta. O Zabbix 7.0 suporta múltiplos tipos de itens, mas a ênfase em itens nativos ("baked-in") do Zabbix Agent e Agent 2 é fundamental para desempenho e segurança. Itens nativos são executados diretamente pelo binário do agente, sem a sobrecarga de criar novos processos (forking), invocar shells ou interpretar scripts externos, o que é comum em UserParameters ou system.run.7
3.1 O Namespace system: Telemetria do Sistema Operacional
O namespace system fornece as métricas fundacionais de saúde do SO. No YAML, a definição precisa destes itens exige atenção aos tipos de dados e unidades.
3.1.1 Discrepâncias de CPU: Carga vs. Utilização
Um template robusto deve distinguir claramente entre system.cpu.load e system.cpu.util.
* system.cpu.load[all,avg1]: Mede o tamanho da fila de execução do processador. É um valor adimensional e ilimitado. Em sistemas Linux, este valor inclui processos em estado "uninterruptible sleep" (geralmente aguardando I/O de disco). Portanto, uma alta carga de CPU pode, na verdade, diagnosticar um gargalo de armazenamento.
* system.cpu.util[all,user,avg1]: Mede a porcentagem de tempo que a CPU gastou em contextos específicos.
Implementação YAML Exemplar:
YAML
- uuid: 73e56303244c41499553641753755375
name: 'CPU I/O Wait time'
type: ZABBIX_ACTIVE
key: 'system.cpu.util[all,iowait,avg1]'
history: 7d
value_type: FLOAT
units: '%'
description: 'Tempo gasto pela CPU aguardando a conclusão de operações de I/O.'
tags:
- tag: component
value: cpu
Observe o uso de ZABBIX_ACTIVE. Em ambientes modernos de nuvem e contêineres, agentes ativos são preferíveis pois iniciam a conexão com o servidor (ou proxy), facilitando a configuração de firewalls e NATs, além de permitir o buffer de dados em caso de desconexão.8
3.1.2 Memória: A Hierarquia vm.memory
A chave vm.memory.size é polimórfica.
* vm.memory.size[available]: Esta é a métrica crítica para alertas. No Linux, ela não é apenas a memória livre, mas uma estimativa da memória disponível para iniciar novas aplicações sem swapping (calculada aproximadamente como free + buffers + cached).
* vm.memory.size[total]: Dado estático, útil para inventário e cálculos de porcentagem.
Não é necessário armazenar a porcentagem de memória como um item coletado se você já coleta available e total. O Zabbix pode calcular isso dinamicamente em gráficos ou triggers. No entanto, para relatórios de longo prazo (SLA), um Item Calculado (discutido na Seção 4) pode ser criado no template para armazenar o valor percentual explicitamente.9
3.2 O Namespace vfs: Engenharia de Sistemas de Arquivos
O monitoramento de armazenamento evoluiu. Verificar apenas o espaço livre é insuficiente em sistemas com filesystems virtuais, montagens bind e contêineres.
3.2.1 Descoberta Dinâmica: vfs.fs.discovery
Definições estáticas de partições (como / ou /home) são obsoletas e frágeis. O uso da chave vfs.fs.discovery é mandatório para templates portáveis. Esta chave retorna um JSON contendo macros LLD como {#FSNAME} e {#FSTYPE}.
Estratégia de Filtragem no YAML:
O YAML deve definir filtros rigorosos na regra de descoberta para evitar o monitoramento de pseudo-filesystems (tmpfs, overlay, sysfs), que geram ruído e alertas falsos.
YAML
discovery_rules:
- uuid: 88746067727448849764761405822606
name: 'Descoberta de Sistemas de Arquivos'
key: vfs.fs.discovery
delay: 1h
filter:
evaltype: AND
conditions:
- macro: '{#FSTYPE}'
value: 'ext|xfs|btrfs|zfs'
operator: MATCHES_REGEX
item_prototypes:
- uuid: 5b4c4091572c4146a896684784918491
name: 'Espaço livre em {#FSNAME}'
key: 'vfs.fs.size'
3.2.2 Esgotamento de Inodes
Um cenário comum de falha catastrófica é o esgotamento de inodes (muitos arquivos pequenos) enquanto o espaço em disco permanece abundante. A chave vfs.fs.inode deve ser pareada com cada verificação de espaço em disco nos protótipos de itens.9
3.3 O Namespace net: Telemetria de Interface
A chave net.if.discovery alimenta o monitoramento de interfaces de rede.
* Tráfego: net.if.in[{#IFNAME}] e net.if.out[{#IFNAME}].
* Preprocessing para Contadores: Contadores de rede são monotonicamente crescentes. O servidor Zabbix deve calcular o delta entre as coletas. No YAML, o passo de pré-processamento "Change per second" é obrigatório aqui. O Zabbix Agent 2 lida automaticamente com o overflow de contadores (32-bit vs 64-bit), mas a configuração correta do pré-processamento no template garante que resets de contadores (reboot do switch/servidor) sejam tratados sem gerar picos de dados absurdos (spikes).10
3.4 Zabbix Agent 2: Plugins Nativos e Coleta Assíncrona
O Zabbix Agent 2, escrito em Go, introduz uma arquitetura de plugins que permite a coleta de métricas complexas que anteriormente exigiam scripts externos ou binários adicionais. Ao criar templates para o Agent 2, o engenheiro pode utilizar chaves exclusivas que se comunicam diretamente com APIs ou sockets.8
3.4.1 Docker Nativo (docker.*)
Anteriormente, monitorar Docker exigia adicionar o usuário zabbix ao grupo docker e scripts Python/Bash. O Agent 2 possui um plugin Docker nativo que fala diretamente com o socket do Docker API.
Exemplo de Chaves Nativas no YAML:
* docker.container_info[{#NAME}]: Retorna JSON com estado detalhado.
* docker.container_stats[{#NAME}]: Estatísticas de recursos em tempo real.
YAML
- uuid: <UUID>
name: 'Docker: Quantidade de containers rodando'
key: 'docker.containers[,,running]'
type: ZABBIX_ACTIVE
O uso destas chaves reduz a latência de coleta e elimina dependências de scripts no host monitorado.11
3.4.2 Certificados Web (web.certificate)
Outro recurso poderoso "baked-in" do Agent 2 é a capacidade de verificar datas de validade de certificados SSL/TLS sem invocar o OpenSSL via shell.
* Chave: web.certificate.get[<website>,<port>,<ip>]
* Retorno: Um JSON contendo x509, datas de expiração, emissor, etc.
Isso permite criar um item dependente com pré-processamento JSONPath para extrair a data de expiração e um trigger preditivo para alertar 15 dias antes.13
________________
4. A Camada de Transformação: Pré-processamento e Itens Calculados
A "inteligência" de um template moderno reside na sua capacidade de transformar dados brutos em informação acionável antes mesmo de serem gravados no banco de dados.
4.1 Pré-processamento: O Pipeline ETL do Zabbix
O pré-processamento permite a aplicação de lógica de transformação sequencial. No schema YAML, isso é definido como uma lista de objetos preprocessing.
4.1.1 Descarte de Dados Inalterados (Throttling)
Para itens de configuração ou inventário (ex: system.uname, system.sw.os, números de série), gravar o mesmo valor string a cada minuto é um desperdício massivo de I/O de banco de dados e armazenamento.
Estratégia YAML:
Utilize DISCARD_UNCHANGED_HEARTBEAT. Isso instrui o servidor a descartar o valor se ele for idêntico ao anterior, mas gravar forçadamente uma vez a cada período (heartbeat) para confirmar que o item ainda está ativo.
YAML
preprocessing:
- type: DISCARD_UNCHANGED_HEARTBEAT
parameters:
- 1d # Grava pelo menos uma vez por dia
Isso reduz a tabela de histórico em ordens de magnitude para métricas estáticas.10
4.1.2 Multiplicadores Personalizados e Conversão de Unidades
O Zabbix opera nativamente em unidades base (Bytes, Segundos). Se um dispositivo ou API retorna valores em Kilobytes (KB) ou Milissegundos (ms), eles devem ser normalizados no pré-processamento.
* Exemplo: Memória retornada em KB.
* YAML:
YAML
preprocessing:
- type: MULTIPLIER
parameters:
- '1024' # Converte KB para Bytes
Isso garante que os sufixos automáticos do frontend (MB, GB, TB) funcionem corretamente.10
4.1.3 Expressões Regulares (Regex) para Extração
Para extrair versões de software de strings complexas, o pré-processamento REGEX é vital.
* Tipo: REGEX
* Parâmetros: padrão, saída.
* Uso: Extrair "7.0.5" de "Zabbix Agent 7.0.5 (revision 123)".
YAML
preprocessing:
- type: REGEX
parameters:
- '([0-9]+\.[0-9]+\.[0-9]+)'
- '\1'
Isso limpa os dados para relatórios de inventário.14
4.2 Itens Dependentes: Otimização de Polling
Para extrair múltiplas métricas de uma única fonte rica (como um JSON de status do Apache ou a saída de docker.info), não se deve consultar a fonte múltiplas vezes. A arquitetura correta utiliza um Item Mestre e Itens Dependentes.
Fluxo de Configuração no YAML:
1. Item Mestre: Coleta o JSON bruto.
* type: ZABBIX_AGENT (ou HTTP_AGENT).
* history: 0 (Se o JSON bruto for muito grande e não for necessário armazená-lo, apenas processá-lo).
2. Item Dependente:
* type: DEPENDENT.
* master_item: Referencia a chave do item mestre.
* preprocessing: Usa JSONPATH para extrair o campo específico.
Exemplo Prático (Conexões Nginx):
Item Mestre coleta http://localhost/status. Item Dependente "Active Connections" usa JSONPath $.active. Isso reduz a carga HTTP no serviço monitorado de N requisições para 1 requisição por ciclo.3
4.3 Itens Calculados: Métricas Virtuais
Itens calculados derivam valores de outros itens existentes, executando a lógica no Zabbix Server. Eles são essenciais para agregar dados ou normalizar percentuais quando o dispositivo não fornece essa métrica diretamente.
Sintaxe da Fórmula no YAML:
A fórmula utiliza a sintaxe funcional func(/host/key, param). No contexto de templates, o host é frequentemente omitido (//key) para indicar "o host atual onde o template está aplicado".
Tabela de Funções Comuns para Itens Calculados:
Função
Descrição
Exemplo de Fórmula
last
Último valor coletado
100 * (last(//vm.memory.size[used]) / last(//vm.memory.size[total]))
avg
Média em um período
avg(//net.if.in[eth0], 1h)
sum
Soma de múltiplos itens
last(//net.if.in[eth0]) + last(//net.if.out[eth0])
Implementação YAML:
YAML
- uuid: <UUID>
name: 'Utilização Total de Memória (%)'
type: CALCULATED
key: 'vm.memory.utilization_calc'
params: '100 * last(//vm.memory.size[used]) / last(//vm.memory.size[total])'
units: '%'
value_type: FLOAT
Nota: O campo params no YAML armazena a fórmula matemática.16
________________
5. Engenharia de Eventos Avançada: Triggers e Predição
O motor de triggers do Zabbix 7.0 transcende a simples verificação de limiares (last() > N). Com funções de tendência e preditivas, é possível criar alertas que avisam antes que o problema ocorra ou que analisam anomalias baseadas em comportamento histórico.
5.1 Funções de Tendência (Trend functions)
O Zabbix mantém duas tabelas principais de dados: history (dados brutos, retidos por curto prazo, ex: 7 dias) e trends (médias/máximos/mínimos horários, retidos por longo prazo, ex: 1 ano).
Funções normais como avg(1M) tentariam ler milhões de linhas da tabela history, o que é performaticamente inviável. As funções de tendência (trendavg, trendmax, trendmin) acessam a tabela trends, permitindo cálculos leves sobre períodos longos.17
Cenário de Uso: Detecção de Anomalia de Linha de Base.
"Alertar se a carga de CPU atual for 50% maior que a média da mesma hora na semana passada."
Expressão no YAML:
YAML
expression: 'last(/host/system.cpu.load) > 1.5 * trendavg(/host/system.cpu.load, 1h:now-1w)'
* 1h:now-1w: Esta sintaxe de deslocamento temporal (time shift) instrui o Zabbix a olhar para uma janela de 1 hora, mas deslocada 1 semana para o passado.
* Insight de Segunda Ordem: O uso de funções de tendência é ideal para monitoramento de capacidade e desvios de padrão (SLA), mas elas são avaliadas com menos frequência (geralmente a cada hora, coincidindo com a geração da tendência) ou quando o item recebe dados, dependendo da configuração. Elas não substituem alertas de tempo real.17
5.2 Funções Preditivas: timeleft e forecast
Estas funções aplicam modelos matemáticos (regressão linear ou polinomial) aos dados históricos para projetar valores futuros.
5.2.1 timeleft: O Cronômetro para a Falha
A função timeleft(/host/key, period, threshold) calcula quantos segundos restam até que o item atinja o threshold, baseando-se na taxa de variação durante o period.
Aplicação Crítica: Planejamento de Capacidade de Disco.
Em vez de alertar quando o disco está 95% cheio (o que pode ser tarde demais se a taxa de gravação for alta), alertamos quando o tempo restante para 0% livre for menor que um intervalo de segurança.
Expressão YAML e Tratamento de Erros:
YAML
expression: 'timeleft(/host/vfs.fs.size[/,free],1h,0) < 3h'
* O Problema do -1: Se o disco estiver sendo esvaziado ou estiver estático, a regressão linear nunca interceptará o zero no futuro. Nesses casos, a função retorna números extremamente grandes (indicando infinito) ou códigos de erro específicos dependendo da versão (1.79E+308 no Zabbix 7.0 para "sem intersecção").
* Robustez: A expressão deve ser composta para evitar falsos positivos se a previsão for irrelevante. No entanto, para alertas de "falta de espaço iminente", a condição simples < 3h é geralmente segura porque valores de erro/infinito serão maiores que 3h (10800 segundos).18
5.2.2 forecast: Previsão de Valor
A função forecast(/host/key, period, time) retorna qual será o valor do item daqui a time segundos.
Cenário: A temperatura do servidor atingirá níveis críticos na próxima hora?
Expressão: forecast(/host/sensor.temp, 30m, 1h) > 80
Isso permite ações preventivas (como ligar ventilação auxiliar) antes que o incidente de superaquecimento ocorra.
Sintaxe e Escaping no YAML:
Ao escrever expressões de trigger complexas no YAML, cuidado especial deve ser tomado com as aspas. Se a chave do item contém colchetes e aspas (ex: tags LLD), a string inteira da expressão deve ser encapsulada corretamente.
YAML
triggers:
- uuid: <UUID>
expression: 'timeleft(/host/vfs.fs.size,1h,0)<1h'
name: 'O disco {#FSNAME} ficará cheio em menos de 1 hora'
priority: HIGH
________________
6. Visualização como Código: Dashboards em Templates
O Zabbix 7.0 permite que dashboards sejam definidos dentro do próprio template. Quando o template é vinculado a um host, o dashboard torna-se disponível no contexto desse host, preenchido automaticamente com os dados dele. Isso é um recurso poderoso para padronização visual.7
6.1 Estrutura do Objeto Dashboard no YAML
O elemento dashboards reside na raiz do objeto template. A estrutura é hierárquica: Dashboard -> Pages -> Widgets -> Fields.
Desafio de Mapeamento de Campos:
A configuração de widgets no YAML não usa nomes de parâmetros amigáveis, mas uma estrutura genérica de fields contendo pares nome-valor.
Exemplo de Configuração de Widget Gráfico:
YAML
dashboards:
- uuid: <UUID>
name: 'Performance do Sistema'
pages:
- widgets:
- type: graph
name: 'Carga de CPU'
width: 12
height: 5
fields:
- type: GRAPH
name: graphid
value: 0 # 0 indica criação dinâmica ou referência interna
- type: ITEM
name: itemid
value: 'system.cpu.load[all,avg1]' # Referência pela CHAVE
Nota Crítica sobre Referências:
Em um dashboard global exportado, o campo value para um itemid seria um número inteiro (o ID do banco de dados). Em um Template Dashboard, a referência deve ser feita pela CHAVE do item (key), pois o ID do item ainda não existe no momento da importação em um novo host. O Zabbix resolve essa referência dinamicamente.20
6.2 Novos Widgets do Zabbix 7.0
O Zabbix 7.0 introduz widgets modernos como o Honeycomb e o Gauge, que oferecem visualizações mais densas e interativas.
* Honeycomb (Favo de Mel): Ideal para visualizar grupos de itens (como todos os núcleos de CPU ou todos os filesystems descobertos via LLD) com mudança de cor baseada em limiares. No YAML, sua configuração envolve definir os item_patterns e as regras de thresholds.
* Gauge (Manômetro): Perfeito para itens percentuais únicos (ex: vm.memory.utilization).
Incluir esses widgets no template YAML garante que, ao implantar o monitoramento, a equipe de operações tenha visualização imediata sem configuração manual extra.
________________
7. Taxonomia e Governança: Tags e Alertas
O sistema de Tags (etiquetas) no Zabbix 7.0 substitui completamente o antigo conceito de "Applications". As tags são pares chave-valor que permitem uma categorização multidimensional, essencial para filtragem de alertas, correlação de eventos e relatórios gerenciais.3
7.1 Estratégia de Tagging para Relatórios Úteis
Para que os relatórios (SLA, Top 100 Triggers) sejam úteis, as tags devem seguir uma taxonomia rigorosa definida no template.
Níveis de Tagging no YAML:
1. Tags de Template: Aplicadas a todos os hosts que usam o template.
* target: os, class: linux.
2. Tags de Item: Classificam a métrica.
* component: cpu, component: memory, layer: hardware.
3. Tags de Trigger: Classificam o incidente.
* scope: availability, scope: performance, security: cve.
Integração com Alertas (Actions):
As "Ações" do Zabbix podem ser configuradas para rotear alertas com base nessas tags.
* Regra de Ação: "Se Tag component igual a database E Tag severity igual a High -> Enviar para Equipe de DBA".
* Benefício: Ao definir essas tags no Template YAML, você garante que qualquer novo host monitorado já nasça integrado corretamente às políticas de roteamento de incidentes da empresa, sem configuração manual na ação.
Exemplo YAML de Trigger com Tags:
YAML
tags:
- tag: scope
value: capacity
- tag: service
value: storage
________________
8. Guia Passo a Passo: Construindo o Template Mestre
Sintetizando os conceitos, apresentamos o fluxo lógico para a construção do arquivo.
8.1 Passo 1: O Cabeçalho e Grupos
Defina o arquivo UTF-8. Declare version: '7.0'. Crie o template_group obrigatório (ex: Templates/Operating Systems).
8.2 Passo 2: Definição dos Itens Nativos
Liste os itens do Agent 2 (docker, system). Aplique UUIDs gerados externamente. Configure o preprocessing para conversão de unidades (Multiplier) e descarte de duplicatas (Discard unchanged).
8.3 Passo 3: Regras de Descoberta (LLD)
Configure vfs.fs.discovery e net.if.discovery. Crie os item_prototypes e, crucialmente, os trigger_prototypes preditivos (timeleft) para cada entidade descoberta. Utilize tags dinâmicas nos protótipos (ex: filesystem: {#FSNAME}).
8.4 Passo 4: Dashboards e Visualização
Insira o bloco dashboards referenciando as chaves dos itens criados. Configure um widget Honeycomb para exibir o status de todos os filesystems descobertos.
8.5 Exemplo de Artefato YAML (Trecho Consolidado)
YAML
zabbix_export:
version: '7.0'
template_groups:
- uuid: 576c953372c8427aa214271822762276
name: 'Templates/OS'
templates:
- uuid: 91409940733543169822606822606822
template: 'Linux Agent 2 Native'
name: 'Linux Agent 2 Native'
groups:
- name: 'Templates/OS'
items:
- uuid: 12519512951295129512951295129512
name: 'Memória Disponível'
key: 'vm.memory.size[available]'
units: B
preprocessing:
- type: DISCARD_UNCHANGED_HEARTBEAT
parameters:
- 10m
tags:
- tag: component
value: memory
discovery_rules:
- uuid: 61261261261261261261261261261261
name: 'Descoberta de FS'
key: vfs.fs.discovery
filter:
evaltype: AND
conditions:
- macro: '{#FSTYPE}'
value: 'ext|xfs'
operator: MATCHES_REGEX
trigger_prototypes:
- uuid: 73473473473473473473473473473473
expression: 'timeleft(/host/vfs.fs.size,1h,0)<1h'
name: 'Disco {#FSNAME} saturando em < 1h'
priority: HIGH
tags:
- tag: scope
value: capacity
9. Conclusão
A engenharia de templates Zabbix 7.0 em YAML exige uma mudança de mentalidade: de operador de interface para arquiteto de código. A adesão estrita às regras de persistência de UUID garante a integridade histórica dos dados. O uso preferencial de itens nativos do Agent 2 e a aplicação de pré-processamento inteligente (Master/Dependent items) otimizam o desempenho da coleta. Finalmente, a incorporação de funções preditivas e dashboards no código do template eleva o nível de maturidade do monitoramento, transformando dados reativos em inteligência proativa. Este relatório serve como a base técnica para a implementação de pipelines de observabilidade modernos e escaláveis no ecossistema Zabbix.
Referências citadas
1. 3 Templates - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/web_interface/frontend_sections/data_collection/templates
2. configuration.export - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/api/reference/configuration/export
3. Template guidelines - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/guidelines/en/template_guidelines
4. zabbix-prusa/template/7.0/Prusa_by_Prom.yaml at main · smejdil, acessado em janeiro 4, 2026, https://github.com/smejdil/zabbix-prusa/blob/main/template/7.0/Prusa_by_Prom.yaml
5. UUID when importing new items - ZABBIX Forums, acessado em janeiro 4, 2026, https://www.zabbix.com/forum/zabbix-troubleshooting-and-problems/450493-uuid-when-importing-new-items
6. 14 Configuration export/import - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/xml_export_import
7. 1 Configuring a template - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/templates/template
8. 3 Agent 2 - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/5.2/manual/concepts/agent2
9. 1 Zabbix agent, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/items/itemtypes/zabbix_agent
10. 2 Item value preprocessing - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/items/preprocessing
11. 1 Zabbix agent 2, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/items/itemtypes/zabbix_agent/zabbix_agent2
12. Source of template_app_docker.yaml - Zabbix - ZABBIX GIT, acessado em janeiro 4, 2026, https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/app/docker/template_app_docker.yaml?at=release%2F7.0
13. 3 Templates - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/xml_export_import/templates
14. 3 Preprocessing examples - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/items/preprocessing/examples
15. 15 Dependent items - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/items/itemtypes/dependent_items
16. 7 Calculated items - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/items/itemtypes/calculated
17. 5 Trend functions - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/appendix/functions/trends
18. 7 Predictive trigger functions - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/config/triggers/prediction
19. 1 Dashboards - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/web_interface/frontend_sections/dashboards
20. 8 Graph - Zabbix, acessado em janeiro 4, 2026, https://www.zabbix.com/documentation/current/en/manual/web_interface/frontend_sections/dashboards/widgets/graph

View File

@ -709,6 +709,115 @@ zabbix_export:
- tag: scope
value: availability
discovery_rules:
- uuid: 34ed656ffcf845b0b5598870de258002
name: Descoberta de Usuários OpenVPN
type: ZABBIX_ACTIVE
key: openvpn.discovery
delay: 5m
description: |
Descobre usuários conectados ao OpenVPN através do script openvpn-discovery.sh.
Requisito: Zabbix Agent ativo com UserParameter configurado.
item_prototypes:
- uuid: a8a060a8e0494d3d99a71cd4f2b6a7c8
name: 'OpenVPN [{#VPN.USER}]: Download Total (Bytes)'
type: ZABBIX_ACTIVE
key: 'openvpn.user.bytes_recv.cached[{#VPN.USER}]'
delay: 1m
history: 30d
trends: 365d
units: B
description: Total de bytes recebidos (download) pelo usuário VPN.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 36362e120e9445a1bbdc750afc0f6a1f
name: 'OpenVPN [{#VPN.USER}]: Upload Total (Bytes)'
type: ZABBIX_ACTIVE
key: 'openvpn.user.bytes_sent.cached[{#VPN.USER}]'
delay: 1m
history: 30d
trends: 365d
units: B
description: Total de bytes enviados (upload) pelo usuário VPN.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 7eee5d914f0346c8a2b1c3d4e5f6a7b8
name: 'OpenVPN [{#VPN.USER}]: Tempo Online (Segundos)'
type: ZABBIX_ACTIVE
key: 'openvpn.user.time_online[{#VPN.USER}]'
delay: 1m
history: 30d
trends: 365d
units: s
description: Tempo de conexão do usuário VPN em segundos.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: c3a4b5c6d7e84f0991a2b3c4d5e6f7a8
name: 'OpenVPN [{#VPN.USER}]: Status'
type: ZABBIX_ACTIVE
key: 'openvpn.user.status[{#VPN.USER}]'
delay: 1m
history: 30d
trends: '0'
valuemap:
name: VPN User Status
description: Status de conexão do usuário VPN (1=conectado, 0=desconectado).
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 1f2a3b4c5d6e4f8a9b0c1d2e3f4a5b6c
name: 'OpenVPN [{#VPN.USER}]: IP Real'
type: ZABBIX_ACTIVE
key: 'openvpn.user.real_address.new[{#VPN.USER}]'
delay: 1m
history: 30d
trends: '0'
value_type: TEXT
description: Endereço IP real (público) do usuário VPN.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 9e8d7c6b5a4941f2bccd1e2f3a4b5c6d
name: 'OpenVPN [{#VPN.USER}]: Destinos Acessados'
type: ZABBIX_ACTIVE
key: 'openvpn.access.destinations[{#VPN.USER}]'
delay: 5m
history: 30d
trends: '0'
value_type: TEXT
description: Lista de destinos únicos acessados pelo usuário VPN (para replay).
tags:
- tag: component
value: vpn
- tag: component
value: audit
- tag: vpn_user
value: '{#VPN.USER}'
graph_prototypes:
- uuid: 2b3c4d5e6f7a4892abcd1e2f3a4b5c6d
name: 'OpenVPN [{#VPN.USER}]: Tráfego'
graph_items:
- color: 199C0D
item:
host: 'PFSense by SNMP'
key: 'openvpn.user.bytes_recv.cached[{#VPN.USER}]'
- sortorder: '1'
color: F63100
item:
host: 'PFSense by SNMP'
key: 'openvpn.user.bytes_sent.cached[{#VPN.USER}]'
- uuid: e9fa3f6d8d864df8b0132f690ae54a1b
name: Descoberta de interfaces de rede
type: DEPENDENT
@ -2762,116 +2871,7 @@ zabbix_export:
newvalue: Desconectado
- value: '1'
newvalue: Conectado
discovery_rules_vpn:
- uuid: 34ed656ffcf845b0b5598870de258002
name: Descoberta de Usuários OpenVPN
type: ZABBIX_ACTIVE
key: openvpn.discovery
delay: 5m
description: |
Descobre usuários conectados ao OpenVPN através do script openvpn-discovery.sh.
Requisito: Zabbix Agent ativo com UserParameter configurado.
item_prototypes:
- uuid: a8a060a8e0494d3d99a71cd4f2b6a7c8
name: 'OpenVPN [{#VPN.USER}]: Download Total (Bytes)'
type: ZABBIX_ACTIVE
key: 'openvpn.user.bytes_recv.cached[{#VPN.USER}]'
delay: 1m
history: 30d
trends: 365d
units: B
description: Total de bytes recebidos (download) pelo usuário VPN.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 36362e120e9445a1bbdc750afc0f6a1f
name: 'OpenVPN [{#VPN.USER}]: Upload Total (Bytes)'
type: ZABBIX_ACTIVE
key: 'openvpn.user.bytes_sent.cached[{#VPN.USER}]'
delay: 1m
history: 30d
trends: 365d
units: B
description: Total de bytes enviados (upload) pelo usuário VPN.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 7eee5d914f0346c8a2b1c3d4e5f6a7b8
name: 'OpenVPN [{#VPN.USER}]: Tempo Online (Segundos)'
type: ZABBIX_ACTIVE
key: 'openvpn.user.time_online[{#VPN.USER}]'
delay: 1m
history: 30d
trends: 365d
units: s
description: Tempo de conexão do usuário VPN em segundos.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: c3a4b5c6d7e84f0991a2b3c4d5e6f7a8
name: 'OpenVPN [{#VPN.USER}]: Status'
type: ZABBIX_ACTIVE
key: 'openvpn.user.status[{#VPN.USER}]'
delay: 1m
history: 30d
trends: '0'
valuemap:
name: VPN User Status
description: Status de conexão do usuário VPN (1=conectado, 0=desconectado).
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 1f2a3b4c5d6e4f8a9b0c1d2e3f4a5b6c
name: 'OpenVPN [{#VPN.USER}]: IP Real'
type: ZABBIX_ACTIVE
key: 'openvpn.user.real_address.new[{#VPN.USER}]'
delay: 1m
history: 30d
trends: '0'
value_type: TEXT
description: Endereço IP real (público) do usuário VPN.
tags:
- tag: component
value: vpn
- tag: vpn_user
value: '{#VPN.USER}'
- uuid: 9e8d7c6b5a4941f2bccd1e2f3a4b5c6d
name: 'OpenVPN [{#VPN.USER}]: Destinos Acessados'
type: ZABBIX_ACTIVE
key: 'openvpn.access.destinations[{#VPN.USER}]'
delay: 5m
history: 30d
trends: '0'
value_type: TEXT
description: Lista de destinos únicos acessados pelo usuário VPN (para replay).
tags:
- tag: component
value: vpn
- tag: component
value: audit
- tag: vpn_user
value: '{#VPN.USER}'
graph_prototypes:
- uuid: 2b3c4d5e6f7a4892abcd1e2f3a4b5c6d
name: 'OpenVPN [{#VPN.USER}]: Tráfego'
graph_items:
- color: 199C0D
item:
host: 'PFSense by SNMP'
key: 'openvpn.user.bytes_recv.cached[{#VPN.USER}]'
- sortorder: '1'
color: F63100
item:
host: 'PFSense by SNMP'
key: 'openvpn.user.bytes_sent.cached[{#VPN.USER}]'
graphs:
- uuid: 18b72f3eafe54206a574f431e7bb563a
name: 'PFSense: Códigos de Motivo (Packet Filter)'

View File

@ -42,6 +42,14 @@ Gerado originalmente pela ferramenta oficial "Templator", Otimizado para Padrão
### Regras de Descoberta (LLD)
#### Descoberta de Usuários OpenVPN (`openvpn.discovery`)
- **Protótipos de Itens:**
- OpenVPN [{#VPN.USER}]: Download Total (Bytes) (`openvpn.user.bytes_recv.cached[{#VPN.USER}]`)
- OpenVPN [{#VPN.USER}]: Upload Total (Bytes) (`openvpn.user.bytes_sent.cached[{#VPN.USER}]`)
- OpenVPN [{#VPN.USER}]: Tempo Online (Segundos) (`openvpn.user.time_online[{#VPN.USER}]`)
- OpenVPN [{#VPN.USER}]: Status (`openvpn.user.status[{#VPN.USER}]`)
- OpenVPN [{#VPN.USER}]: IP Real (`openvpn.user.real_address.new[{#VPN.USER}]`)
- OpenVPN [{#VPN.USER}]: Destinos Acessados (`openvpn.access.destinations[{#VPN.USER}]`)
#### Descoberta de interfaces de rede (`pfsense.net.if.discovery`)
- **Protótipos de Itens:**
- Interface [{#IFNAME}({#IFALIAS})]: Tráfego IPv4 de entrada bloqueado (`net.if.in.block.v4.bps[{#SNMPINDEX}]`)
@ -97,6 +105,8 @@ Gerado originalmente pela ferramenta oficial "Templator", Otimizado para Padrão
### Protótipos de Triggers (LLD)
**Regra: Descoberta de Usuários OpenVPN**
**Regra: Descoberta de interfaces de rede**
- [WARNING] **🐢 Congestionamento: Descartes na interface {#IFNAME}**
- [WARNING] **⚠️ PFSense: Interface [{#IFNAME}({#IFALIAS})]: Alta taxa de erros de entrada**

View File

@ -0,0 +1,13 @@
{
"folders": [
{
"name": "minions-da-itguys",
"path": "../minions-da-itguys"
},
{
"name": "zabbix-itguys",
"path": "."
}
],
"settings": {}
}