# 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.