olt-api/doc/zabbix_integration.md

Guia Técnico de Integração Zabbix

Este documento descreve como construir templates Zabbix para consumir a IPv0 OLT API. Ele detalha os Headers, Regras de Descoberta (LLD), Pré-processamentos Java Script e estrutura dos itens.

1. Visão Geral (Master Item)

Toda a coleta de dados de uma OLT deve ser centralizada em um único Master Item (HTTP Agent). Isso aproveita o cache da API e evita sobrecarga de conexões.

Configuração do Master Item

• Nome: OLT API Stats
• Type: HTTP agent
• Key: olt.api.stats
• URL: http://{$API_IP}:{$API_PORT}/api/v1/olt_stats
• Query Fields:
  • host: {HOST.CONN} ou {HOST.IP}
• Headers:
  • Content-Type: application/json
• Timeout: 30s (ou mais, dependendo do tamanho da OLT)
• History: 1h (NÃO guarde histórico longo do JSON bruto se for muito grande)
• Trends: 0 (Texto não tem trend)

---

2. Padrão de Descoberta (Low Level Discovery - LLD)

A API retorna um JSON estruturado hierarquicamente (NGFC, FGLT, etc). Para criar itens no Zabbix, precisamos "achatar" essa estrutura usando LLD Dependent Rules.

2.1 LLD de Cards (Placas)

Para descobrir as placas (FGLT, FANT, etc):

• Type: Dependent item
• Master Item: OLT API Stats
• Key: olt.card.discovery
• Preprocessing:
  1. JavaScript:

     var data = JSON.parse(value);
     var output = [];
     // Itera sobre tipos de cards conhecidos
     ['FGLT', 'FANT', 'NGFC'].forEach(function(type) {
         if (data[type]) {
             data[type].forEach(function(card) {
                 output.push({
                     "{#CARD_INDEX}": card.cardIndex,
                     "{#CARD_NAME}": card.cardName,
                     "{#CARD_TYPE}": card.cardType,
                     "{#CARD_SLOT}": card.cardSlot || card.cardNumber // Ajuste conforme driver
                 });
             });
         }
     });
     return JSON.stringify(output);
     

2.2 LLD de PONs (Portas)

Para descobrir as portas PON e criar métricas de suporte (Total/Online/Offline):

• Type: Dependent item
• Master Item: OLT API Stats
• Key: olt.pon.discovery
• Preprocessing:
  1. JavaScript:

     var data = JSON.parse(value);
     var output = [];
     if (data.FGLT) {
         data.FGLT.forEach(function(card) {
             if (card.pons) {
                 card.pons.forEach(function(pon) {
                     output.push({
                         "{#PON_NAME}": pon.ponName,
                         "{#PON_INDEX}": pon.ponIndex,
                         "{#PON_CODE}": pon.ponCode, // Importante para SNMP
                         "{#CARD_INDEX}": card.cardIndex
                     });
                 });
             }
         });
     }
     return JSON.stringify(output);
     

---

3. Protótipos de Itens (Item Prototypes)

3.1 Métricas via JSON (Dependentes)

Métricas como "ONTs Online" vêm direto do JSON. Não use SNMP ou HTTP novo. Use Dependent Item.

• Name: PON {#PON_NAME}: ONTs Online
• Type: Dependent item
• Master Item: OLT API Stats
• Key: pon.online[{#PON_INDEX}]
• Preprocessing:
  1. JSONPath:

     $.FGLT[?(@.cardIndex=='{#CARD_INDEX}')].pons[?(@.ponIndex=='{#PON_INDEX}')].onuStats.up.first()
     

3.2 Métricas via SNMP (SNMP Agent)

Métricas físicas (Temperatura, Voltagem, Status Operacional) devem ser coletadas via SNMP direto da OLT, usando os índices descobertos.

• Name: PON {#PON_NAME}: Temperatura
• Type: SNMP agent
• Key: pon.temp[{#PON_INDEX}]
• SNMP OID:
  • Exemplo Nokia: 1.3.6.1.4.1.637.61.1.56.5.1.10.{#CARD_INDEX}.{#PON_INDEX}
  • Exemplo Interface Genérica: 1.3.6.1.2.1.2.2.1.8.{#PON_CODE}

---

4. Templates Disponíveis

Abaixo listamos os templates XML prontos para importação que seguem este padrão:

• OLT Nokia: doc/templates/template-nokia-api.xml
  • Suporta: 7360 ISAM, Placas FGLT/FANT, Métricas de ONTs, Status Físico (SFP).

---

Nota: Mantenha os templates versionados junto com o código da API para garantir compatibilidade com as estruturas JSON retornadas.