Initial commit

doc/zabbix_integration.md

@@ -0,0 +1,120 @@
+# 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**:
+        ```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**:
+        ```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](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.