From cd5fa8e3d0324535659f862d09d93f887b3a3166 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Pedro=20Toledo?= Date: Thu, 8 Jan 2026 21:27:10 -0300 Subject: [PATCH] docs: Converte standard de Templates Zabbix para Markdown --- .../Zabbix 7.0 Templates YAML Avançados.txt | 457 ------------------ .../standards/zabbix_template_standards.md | 120 +++++ 2 files changed, 120 insertions(+), 457 deletions(-) delete mode 100644 src/knowledge/standards/Zabbix 7.0 Templates YAML Avançados.txt create mode 100644 src/knowledge/standards/zabbix_template_standards.md diff --git a/src/knowledge/standards/Zabbix 7.0 Templates YAML Avançados.txt b/src/knowledge/standards/Zabbix 7.0 Templates YAML Avançados.txt deleted file mode 100644 index 46bcd89..0000000 --- a/src/knowledge/standards/Zabbix 7.0 Templates YAML Avançados.txt +++ /dev/null @@ -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: - 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[,,] -* 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: - 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: - 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: - 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 \ No newline at end of file diff --git a/src/knowledge/standards/zabbix_template_standards.md b/src/knowledge/standards/zabbix_template_standards.md new file mode 100644 index 0000000..1c14b3b --- /dev/null +++ b/src/knowledge/standards/zabbix_template_standards.md @@ -0,0 +1,120 @@ +# 📊 Padrões de Templates Zabbix 7.0 (O Protocolo "MaC") + +**Público:** Engenheiros de Observabilidade, DevOps, Arquitetos de Sistemas. +**Objetivo:** Monitoramento como Código (MaC), Idempotência, Performance e Integridade Histórica. + +> [!CRITICAL] +> **O Imperativo do UUID:** +> "A persistência do UUID é sagrada. A rotatividade de UUIDs destrói a continuidade dos dados e inviabiliza análises de SLA. Gere uma vez, mantenha para sempre." + +## 1. 🏗️ Fundamentos Arquiteturais (O Schema 7.0) + +A transição para o Zabbix 7.0 consolida a metodologia de **Monitoramento como Código**. Templates devem ser definidos, versionados e geridos via YAML. + +### Estrutura Raiz Canônica +O schema 7.0 exige a separação entre grupos de templates e templates. + +* **Versão:** Explicitamente `'7.0'`. +* **Grupos:** Definir `template_groups` na raiz. + +```yaml +zabbix_export: + version: '7.0' + template_groups: + - uuid: a571c0d144b14fd4a87a9d9b2aa9fcd6 + name: Templates/Applications + templates: + - uuid: ... # UUID Estático gerado externamente +``` + +**⚠️ Atenção:** O parser YAML é estrito. Indentação incorreta invalida o arquivo. + +## 2. 🆔 O Mandato GitOps: UUIDs Estáticos + +Engenheiros são responsáveis pela geração e manutenção dos UUIDs. + +* **Proibido:** Alterar UUIDs de itens existentes. Isso causa perda de histórico (Delete/Create atômico). +* **Proibido:** Inventar UUIDs manuais (`1111...`). Risco de colisão. +* **Exigido:** Gerar UUIDs seguros (32 chars hex, lowercase). + +```bash +# Geração segura +uuidgen | tr -d '-' | tr '[:upper:]' '[:lower:]' +``` + +## 3. ⚡ Estratégia de Aquisição (Native First) + +Priorize itens nativos ("baked-in") do **Zabbix Agent 2**. Eles eliminam a necessidade de forks de processo e scripts externos. + +### Telemetria do Sistema (Namespace `system`) + +* **CPU:** Distinguir Carga (`system.cpu.load`) de Utilização (`system.cpu.util`). + * Prefira `system.cpu.util[all,iowait,avg1]` para diagnosticar gargalos de I/O. +* **Memória:** Use `vm.memory.size[available]` para alertas reais de capacidade. + +### Docker Nativo +Não use scripts Python/Bash se o Agent 2 fala nativamente com o docker socket. + +```yaml +- uuid: + name: 'Docker: Containers Running' + key: 'docker.containers[,,running]' # Plugin nativo Golang + type: ZABBIX_ACTIVE +``` + +### Certificados Web +Use `web.certificate.get` para validar expiração SSL/TLS sem invocar OpenSSL externo. + +## 4. 🔄 Pipeline ETL: Pré-processamento + +Transforme dados brutos em informação acionável *antes* de gravar no banco. + +### Descarte de Dados (Throttling) +Para métricas estáticas (versão de OS, Serial Number), reduza massivamente o I/O do DB. + +* **Regra:** Use `DISCARD_UNCHANGED_HEARTBEAT` (ex: 1d). + +### Itens Dependentes (Master Item) +Para APIs ou JSONs complexos, faça **uma coletas** e **N extrações**. + +1. **Item Mestre:** Coleta o JSON (History: 0). +2. **Item Dependente:** Usa JSONPath para extrair o valor. + +## 5. 🔮 Engenharia de Triggers: Predição e Tendência + +Saia do básico "threshold estático". Use a matemática do Zabbix. + +### Funções de Tendência (`trend*`) +Use para baselines de longo prazo sem onerar o banco de dados (lê da tabela `trends`, não `history`). + +```yaml +# Alerta de desvio de padrão (50% acima da média da semana passada) +expression: 'last(/host/key) > 1.5 * trendavg(/host/key, 1h:now-1w)' +``` + +### Funções Preditivas (`timeleft`) +Alerta *antes* de acabar o disco. + +```yaml +# Alerta: Disco cheio em menos de 3h baseado na taxa de gravação atual +expression: 'timeleft(/host/vfs.fs.size[/,free],1h,0) < 3h' +``` + +## 6. 📊 Visualização como Código (Dashboards) + +Dashboards devem residir DENTRO do template. Padronização visual imediata. + +* **Referência:** Use a CHAVE do item (`key`), não ID numérico, para ligar widgets aos itens no YAML. +* **Widgets Modernos:** Use `Honeycomb` para coleções LLD e `Gauge` para percentuais. + +## 7. 🏷️ Taxonomia (Tags) + +Tags governam o roteamento de alertas e relatórios. + +1. **Tags de Template:** `target: os`, `class: linux`. +2. **Tags de Item:** `component: cpu`, `layer: hardware`. +3. **Tags de Trigger:** `scope: capacity`, `severity: high`. + +--- + +**Conclusão:** O engenheiro de Zabbix 7.0 não é um operador de GUI. Ele é um arquiteto de código que constrói resiliência, performance e inteligência proativa.