Zabbix e Grafana: dashboard de tráfego para provedor

Zabbix e Grafana formam a dupla mais comum nos NOCs de provedor que já cresceram além da tela de problemas. O Zabbix coleta SNMP, guarda o histórico e dispara os alertas. O Grafana pega esses dados pela API e monta um painel que cabe na TV da parede: trânsito por link, CPU da borda, ONUs online por PON e a lista de problemas abertos, tudo filtrado por grupo e por host.

Este guia monta o painel de Zabbix e Grafana do zero em cima de um Zabbix 7.0 que já monitora os equipamentos. Você vai instalar o Grafana, ativar o plugin do Zabbix, criar um usuário só de leitura com token de API, configurar o datasource (pela tela ou por arquivo) e construir os painéis com variáveis. No fim, um resumo do que costuma dar errado.

Resposta rápida

O caminho para ligar Zabbix e Grafana, em cinco passos:

1. Instale o Grafana OSS 11.6 ou mais novo e o plugin alexanderzobnin-zabbix-app. Depois, ative o app em Administration > Plugins and data > Plugins.
2. No Zabbix, crie um usuário de leitura só com os grupos que o NOC precisa ver e gere um token em Users > API tokens.
3. No Grafana, crie o datasource Zabbix com a URL terminando em api_jsonrpc.php, Auth type API Token e trends ligado.
4. Crie as variáveis $group e $host e use regex no campo Item para pegar as interfaces de trânsito.
5. Deixe os alertas no Zabbix. O Grafana mostra os problemas, mas quem manda o aviso continua sendo o Zabbix.

Por que usar Zabbix e Grafana juntos

O Zabbix já tem gráficos e dashboards, e para muita coisa eles bastam. O problema aparece quando o provedor cresce: dez roteadores, trinta OLTs, uma tela por equipamento. Montar uma visão única, com o trânsito de todas as bordas somado e um seletor de host no topo, é trabalhoso no Zabbix e simples no Grafana.

A divisão de papéis que funciona entre Zabbix e Grafana é esta: o Zabbix continua sendo a fonte da verdade e o Grafana vira só a camada de visualização. Nada de coletar SNMP pelo Grafana ou duplicar alertas. A tabela resume quem faz o quê:

Com Zabbix e Grafana separados assim, se o Grafana cair, o monitoramento continua. Você perde a TV bonita, não perde alerta nem histórico.

Instalando o Grafana e o plugin do Zabbix

O plugin atual exige Grafana 11.6.0 ou mais novo. Em Debian ou Ubuntu, o caminho mais limpo é o repositório APT oficial da Grafana Labs. Rode numa máquina separada do Zabbix, ou ao menos numa VM separada, para que um painel pesado não dispute CPU com o servidor de coleta:

sudo apt-get install -y apt-transport-https wget gnupg
sudo mkdir -p /etc/apt/keyrings
sudo wget -O /etc/apt/keyrings/grafana.asc \
  https://apt.grafana.com/gpg-full.key
sudo chmod 644 /etc/apt/keyrings/grafana.asc
echo "deb [signed-by=/etc/apt/keyrings/grafana.asc] \
https://apt.grafana.com stable main" | \
  sudo tee -a /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install grafana
sudo systemctl enable grafana-server
sudo systemctl start grafana-server

Linha a linha: as três primeiras preparam o diretório de chaves e baixam a chave GPG do repositório. O echo cria o arquivo de fonte do APT com a chave amarrada ao repositório (signed-by), o que evita que outro repositório assine pacotes do Grafana. Depois vêm a instalação, o enable para subir no boot e o start.

O Grafana sobe na porta 3000. No primeiro acesso, o usuário e a senha são admin, e ele pede para trocar a senha. Troque, e se o painel vai ficar exposto fora da rede de gerência, coloque um proxy com HTTPS na frente.

O plugin do Zabbix

O Grafana não fala com o Zabbix sem o plugin. Ele pode ser instalado pela tela, em Administration > Plugins and data > Plugins, buscando por Zabbix. Pela linha de comando:

sudo grafana cli plugins install alexanderzobnin-zabbix-app
sudo systemctl restart grafana-server

Em versões que ainda trazem o binário separado, o comando é grafana-cli plugins install com o mesmo nome. O reinício é obrigatório. Depois dele, volte à tela de plugins, abra o Zabbix e clique em Enable. Esse passo é o que mais se esquece: o plugin instalado e desativado não aparece na lista de datasources.

Usuário de leitura e token de API no Zabbix

Não use o usuário Admin do Zabbix no Grafana. Um token com poder de administrador, salvo em outro servidor, é um risco desnecessário. Crie um usuário que só enxerga os grupos de host que o NOC precisa ver:

1. Users > User groups > Create user group
     Nome:              Grafana leitura
     Host permissions:  Borda = Read, OLT = Read
2. Users > Users > Create user
     Username:  grafana
     Grupo:     Grafana leitura
     Role:      User role
3. Users > API tokens > Create API token
     Name:      grafana-noc
     User:      grafana
     Set expiration date and time: marcado (12 meses)
     Enabled:   marcado
   Copie o Auth token antes de fechar a página.

O grupo de usuários é quem dá a permissão de leitura nos grupos de host. O papel User role basta para ler dados pela API. O token aparece uma vez só, logo depois de criado. Se perder, gere outro e apague o antigo. A data de expiração obriga alguém a revisar o acesso uma vez por ano, o que é melhor do que um token eterno esquecido.

Testando o token antes do Grafana

Antes de abrir o Grafana, confirme que o token funciona. Assim, se algo falhar depois, você sabe que o problema está do lado do Grafana. Rode a partir do servidor do Grafana, que é de onde as consultas vão sair:

export ZBX_TOKEN='cole-o-token-aqui'
curl -s http://192.0.2.5/zabbix/api_jsonrpc.php \
  -H 'Content-Type: application/json-rpc' \
  -H "Authorization: Bearer $ZBX_TOKEN" \
  -d '{"jsonrpc":"2.0","method":"host.get",
       "params":{"output":["host"],"limit":3},"id":1}'

No Zabbix 7.0 o token vai no cabeçalho Authorization: Bearer, não no corpo da chamada. O host.get com limit 3 traz três hosts que o usuário enxerga. Uma resposta de exemplo:

{"jsonrpc":"2.0","result":[{"hostid":"10601","host":"borda-01"},
{"hostid":"10602","host":"borda-02"},{"hostid":"10655","host":"olt-01"}],
"id":1}

Lista vazia significa que o usuário não tem permissão em nenhum grupo com hosts. Erro de autorização significa token errado, expirado ou desativado. Erro de conexão é firewall ou URL.

O datasource: onde Zabbix e Grafana se conectam

Em Connections > Data sources > Add new data source, escolha Zabbix. Os campos que importam:

• URL: o endereço completo da API, terminando em api_jsonrpc.php. No exemplo, http://192.0.2.5/zabbix/api_jsonrpc.php. Sem o caminho do arquivo, o teste falha.
• Auth type: API Token, colando o token criado no passo anterior. Usuário e senha também funcionam, mas o token é revogável sem trocar senha de ninguém.
• Trends: ligado. Com After em 7d e Range em 4d, consultas de mais de alguns dias leem as médias horárias em vez do histórico bruto.
• Cache TTL: 1h é o padrão. É o tempo que o plugin guarda a lista de grupos, hosts e itens. Se você criar um host novo e ele não aparecer, é o cache.

Clique em Save & test e espere a mensagem de sucesso. Ajuste o After do trends para bater com o histórico configurado nos itens: se você guarda 14 dias de histórico, 7d é seguro.

O mesmo datasource por arquivo

Se você recria o servidor com Ansible ou mantém mais de um Grafana, use o provisionamento. O Grafana lê os arquivos em /etc/grafana/provisioning/datasources/ na inicialização:

# /etc/grafana/provisioning/datasources/zabbix.yaml
apiVersion: 1

datasources:
  - name: Zabbix
    type: alexanderzobnin-zabbix-datasource
    url: http://192.0.2.5/zabbix/api_jsonrpc.php
    jsonData:
      authType: token
      trends: true
      trendsFrom: '7d'
      trendsRange: '4d'
      cacheTTL: '1h'
    secureJsonData:
      apiToken: cole-o-token-aqui
    editable: false

O type é o nome interno do datasource do plugin. O authType: token troca o login por token, e o token vai em secureJsonData, que o Grafana guarda criptografado no banco dele. O editable: false impede que alguém altere o datasource pela tela e crie diferença entre o arquivo e o que está rodando. Proteja o arquivo, porque ele tem o token em texto:

F=/etc/grafana/provisioning/datasources/zabbix.yaml
sudo chown root:grafana $F
sudo chmod 640 $F
sudo systemctl restart grafana-server

Variáveis: um painel para todos os hosts

As variáveis são o que faz a combinação de Zabbix e Grafana valer o esforço. Em vez de um dashboard por roteador, você cria um só, com seletores no topo. Em Dashboard settings > Variables, crie duas variáveis do tipo Query usando o datasource Zabbix:

Variável 1
  Name:        group
  Query type:  Group
  Group:       /Borda|OLT/
  Multi-value: marcado    Include All option: marcado

Variável 2
  Name:        host
  Query type:  Host
  Group:       $group
  Host:        /.*/
  Multi-value: marcado    Include All option: marcado

A primeira lista os grupos que batem com a regex, Borda e OLT. A segunda lista os hosts do grupo escolhido, porque o campo Group dela aponta para $group. É o encadeamento: troque o grupo e a lista de hosts muda junto. No plugin, regex vai entre barras, como /.*/.

Com Multi-value, o plugin transforma a seleção em uma regex do tipo (borda-01|borda-02) e consulta tudo de uma vez. Com Include All, aparece a opção All no seletor. Cuidado com All em grupos grandes: trinta OLTs com centenas de itens cada deixam o painel lento.

Painéis do NOC com Zabbix e Grafana

Com o datasource e as variáveis prontos, falta o que aparece na tela. Os exemplos usam os nomes de item dos templates oficiais do Zabbix 7.0 para rede, no formato Interface Gi0/0/1(TRANSITO-A): Bits received. O texto entre parênteses vem da descrição da interface. Se as portas de trânsito têm TRANSITO na descrição, uma regex separa essas portas de todas as outras.

Trânsito IP por link

Painel: Trânsito IP (Time series)
  Query type:  Metrics
  Group:       Borda
  Host:        $host
  Item:        /TRANSITO.*Bits (received|sent)/
  Functions:   setAlias($__zbx_host_name: $__zbx_item)
  Unit:        bits/sec(SI)

O campo Item aceita regex e pega entrada e saída de todas as interfaces com TRANSITO na descrição. O setAlias troca o nome longo do item por algo como borda-01: Interface Gi0/0/1(TRANSITO-A): Bits received, usando as macros do plugin para o nome visível do host e o nome do item. A unidade bits/sec(SI) mostra Mbps e Gbps em base 1000, a mesma da operadora.

Entrada total e comparação com a semana passada

Painel: Entrada total do trânsito (Stat)
  Query type:  Metrics
  Group:       Borda
  Host:        /.*/
  Item:        /TRANSITO.*Bits received/
  Functions:   sumSeries()
               setAlias(Entrada total)
  Unit:        bits/sec(SI)
  Calculation: Last *

Painel: Mesma hora, semana passada (Time series)
  (mesma consulta acima, em uma segunda query)
  Functions:   sumSeries()
               timeShift(7d)
               setAlias(Semana passada)

O sumSeries soma todas as séries ponto a ponto e entrega o tráfego de entrada somado de todas as bordas. No painel Stat, o cálculo Last * mostra o último valor não vazio. Na segunda consulta, o timeShift(7d) desenha a mesma curva deslocada uma semana. Ver as duas linhas juntas responde rápido se o pico de hoje é normal para o dia da semana.

Esse painel ajuda a enxergar a tendência, mas não substitui a conta de cobrança. Para conferir a fatura de trânsito, use o método do guia de percentil 95 no Zabbix.

Interfaces mais carregadas

Painel: Interfaces mais carregadas (Bar gauge)
  Query type:  Metrics
  Group:       $group
  Host:        $host
  Item:        /Bits received/
  Functions:   top(10, avg)
               setAlias($__zbx_host_name: $__zbx_item)
  Unit:        bits/sec(SI)

O top(10, avg) ordena as séries pela média no período da tela e mantém as dez maiores. Num Bar gauge horizontal, vira um ranking que mostra de cara qual porta está apertada. Como o grupo e o host vêm das variáveis, o mesmo painel serve para as bordas e para as OLTs.

CPU dos equipamentos

Painel: CPU dos equipamentos (Time series)
  Query type:  Metrics
  Group:       $group
  Host:        $host
  Item:        /CPU utilization/
  Functions:   setAlias($__zbx_host_name)
  Unit:        Percent (0-100)
  Thresholds:  70 (amarelo), 90 (vermelho)

Os limites de cor ficam no próprio painel: amarelo em 70%, vermelho em 90%. Isso é só visual. O alerta de CPU alta continua sendo um trigger do Zabbix, com histerese e tempo mínimo, que o painel não tem.

PON e problemas abertos

Painel: ONUs online por PON (Time series)
  Query type:  Metrics
  Group:       OLT
  Host:        $host
  Item:        /ONUs online/
  Functions:   setAlias($__zbx_item)

Painel: Problemas abertos (Problems ou Table)
  Query type:  Problems
  Group:       $group
  Host:        $host

Para o painel de PON, os itens têm de existir no Zabbix. O guia para monitorar OLT Huawei no Zabbix via SNMP cria itens de ONUs online por PON com descoberta. No exemplo, o protótipo foi nomeado com ONUs online no fim, e a regex pega todos. Uma queda brusca numa linha é PON caindo inteira, o que quase sempre é fibra ou splitter, como no diagnóstico de ONU com LOS ou offline na OLT Huawei.

O tipo de consulta Problems traz os problemas abertos do Zabbix em formato de tabela, para o painel Problems do próprio plugin ou uma tabela comum. Nas opções da consulta dá para filtrar por severidade, esconder os já reconhecidos e limitar a quantidade.

Como os dados fluem entre Zabbix e Grafana

O desenho mostra o caminho de um dado até a TV do NOC. Repare que o Grafana nunca fala com o roteador:

Alertas com Zabbix e Grafana: ficam no Zabbix

O Grafana tem um sistema de alertas próprio, e o plugin consegue alimentá-lo. Mesmo assim, num provedor que já tem triggers, ações e escalonamento no Zabbix, duplicar essa lógica cria dois lugares para manter e duas fontes de aviso para o mesmo evento. Quando o Grafana estiver fora do ar, você continua recebendo alerta.

O que funciona melhor é usar o Grafana para mostrar o estado dos alertas: o painel de problemas, cores nos limites e anotações de eventos no gráfico. O trigger, a mensagem no Telegram e o plantão continuam no Zabbix.

Erros comuns com Zabbix e Grafana

Dois detalhes que custam tempo. Primeiro, a partir do Zabbix 7.2 a API não aceita mais o token no campo auth do corpo da chamada, só no cabeçalho Authorization: Bearer. Scripts antigos e versões antigas do plugin param de funcionar depois da atualização, então mantenha o plugin atualizado. Segundo, regex no plugin precisa das barras: TRANSITO sem barras procura um item com esse nome exato e não acha nada.

Se o painel de sinal das ONUs mostrar valores estranhos, confira primeiro a escala do item no Zabbix. As faixas de referência estão no guia de valores ideais de sinal da ONU GPON.

Perguntas frequentes

Preciso de Grafana Enterprise para usar o plugin do Zabbix?

Não. O plugin funciona no Grafana OSS, que é gratuito. Ele exige Grafana 11.6.0 ou mais novo e um usuário do Zabbix com permissão de leitura nos hosts que você quer consultar.

Token de API ou usuário e senha no datasource?

Token, quando o Zabbix é 5.4 ou mais novo. Ele pode ter data de expiração e ser revogado sem trocar a senha de ninguém. A partir do Zabbix 6.4, a API aceita o token no cabeçalho Authorization: Bearer, e no 7.2 essa passou a ser a única forma.

O Grafana pesa no servidor do Zabbix?

Num conjunto Zabbix e Grafana, quem sente a carga é o Zabbix, na medida das consultas. Painéis com períodos longos e muitos hosts geram muitas chamadas à API. Ligue trends no datasource, evite All em grupos grandes e use atualização de 1 minuto ou mais na TV.

Dá para usar Zabbix e Grafana com dados de OLT?

Sim. Qualquer item que o Zabbix coleta pode virar painel no Grafana, incluindo ONUs online por PON e sinal das ONUs. O trabalho está em criar bons itens no Zabbix. O Grafana só mostra.

Zabbix e Grafana podem rodar no mesmo servidor?

Podem, e em provedor pequeno é o comum. Separar em duas VMs evita que um dashboard pesado dispute CPU e memória com a coleta. Se ficarem juntos, limite o período padrão dos painéis e o número de hosts com All.

Posso tirar os alertas do Zabbix e passar para o Grafana?

Pode, mas não compensa num provedor que já tem triggers e ações prontas. Manter os alertas no Zabbix deixa o aviso independente do Grafana, e o painel só mostra o estado.

Conclusão

Montar Zabbix e Grafana no provedor é mais configuração do que código: um usuário de leitura com token, um datasource bem ajustado e meia dúzia de painéis com variáveis. O Zabbix continua fazendo o trabalho pesado de coletar e alertar, e o Grafana entrega a visão única que o NOC precisa. Comece pelo painel de trânsito, que é o que todo mundo olha primeiro, e vá acrescentando CPU, PON e problemas.