Integração com Grafana - Alertas de infraestrutura

O Grafana é uma solução popular de análise e monitoramento de código aberto usada por milhares de organizações para visualizar métricas, logs e traces. Ao integrar o Grafana com o Echobell, você pode receber notificações instantâneas quando suas métricas acionarem alertas - seja uso alto de CPU, pressão de memória, serviços com falha ou qualquer outra condição monitorada.

Este guia completo mostra como configurar alertas do Grafana com o Echobell, da configuração básica até estratégias avançadas de gerenciamento de alertas.

Pré-requisitos

Antes de começar, verifique se você tem:

• Uma conta do Echobell com pelo menos um canal criado (Comece por aqui)
• Acesso a uma instância do Grafana (recomendamos a versão 8.0 ou posterior; versão 9.0+ para melhor compatibilidade)
• Acesso administrativo para configurar notificações de alerta no Grafana (normalmente exige a função Admin ou Editor)
• Conhecimento básico de dashboards e métricas do Grafana
• Familiaridade com sua infraestrutura de monitoramento e seus requisitos de alerta

Visão geral da configuração

O processo de integração envolve cinco etapas principais que costumam levar de 10 a 15 minutos:

1. Criar um canal no Echobell - Configure um canal dedicado aos alertas do Grafana
2. Configurar modelos de notificação - Defina como os alertas aparecerão no seu dispositivo
3. Obter a URL do webhook - Obtenha o endpoint de webhook exclusivo do seu canal
4. Configurar o ponto de contato do Grafana - Configure o Grafana para enviar alertas ao Echobell
5. Criar regras de alerta no Grafana - Defina quais condições acionam notificações

Depois de configurado, os alertas fluem automaticamente do Grafana para o seu dispositivo em tempo real.

Guia passo a passo

{{alertName}} - {{status}}

🔔 Alert: {{alertName}}
📊 Metric: {{metric}}
📈 Value: {{value}}
⏰ Time: {{time}}
ℹ️ Message: {{message}}

{
  "alertName": "{{ .alertName }}",
  "status": "{{ .status }}",
  "metric": "{{ .metric }}",
  "value": "{{ .value }}",
  "time": "{{ .time }}",
  "message": "{{ .message }}",
  "externalLink": "{{ .dashboardURL }}"
}

Testando a integração

Para verificar sua configuração:

1. Crie uma regra de alerta de teste com uma condição que seja acionada rapidamente
2. Aguarde até a condição ser atendida
3. Verifique a notificação de alerta no app Echobell
4. Confirme se todas as variáveis do alerta aparecem corretamente
5. Toque na notificação para acessar o dashboard do Grafana vinculado

Tipos de notificação de alerta

Ao se inscrever no canal de alertas do Grafana, configure estes tipos de notificação essenciais:

• Use Urgente para alertas críticos de sistema e notificações de emergência
• Use Chamada para quedas graves, violações críticas de limite ou alertas de emergência
• Use Normal para alertas informativos padrão e notificações de rotina

Boas práticas de gerenciamento de alertas

Organização dos modelos de alerta

Mantenha os modelos de alerta claros e consistentes entre os canais:

Title: {{alertName}} - {{status}}
Body: 
Server: {{instance}}
Metric: {{metric}}  
Current: {{value}}
Threshold: {{threshold}}

• Use formatação estruturada - Organize as informações com rótulos claros
• Inclua as informações críticas - Nome da métrica, valor, limite e sistema afetado
• Use emojis com moderação - 🚨 para crítico, ⚠️ para avisos, ✅ para resolvido
• Mantenha os títulos concisos - Busque de 5 a 8 palavras que transmitam o problema de imediato
• Teste os modelos - Envie alertas de teste para conferir a formatação antes de colocar em produção

Configuração de alertas críticos

Defina limites de alerta adequados para evitar fadiga de notificações:

• Evite alertar demais - Defina limites em níveis acionáveis, não em níveis apenas interessantes
• Use histerese - Configure limites diferentes para o alerta e para a recuperação
• Agrupe alertas relacionados - Combine condições relacionadas em uma única regra de alerta
• Defina intervalos de avaliação adequados - Equilibre a capacidade de resposta com a redução de ruído
• Considere janelas de tempo - Faça várias verificações da condição antes de alertar

Exemplo de estratégia de limites:

# Bad: Alert at 50% CPU (too sensitive)
cpu_usage > 50

# Better: Alert at 80% for 5 minutes
avg_over_time(cpu_usage[5m]) > 80

# Best: Progressive alerts
# Warning at 70% sustained, Critical at 90%

Use nomes de alerta significativos

Dê aos alertas nomes descritivos que transmitam de imediato:

• O que está sendo monitorado (CPU, memória, disco)
• Onde está acontecendo (produção, staging, instância específica)
• Por que isso importa (serviço voltado ao usuário, banco de dados crítico)

Bons exemplos:

• "Banco de dados de produção - Uso alto do pool de conexões"
• "API Gateway - Degradação do tempo de resposta"
• "Worker node 3 - Espaço em disco crítico"

Evite:

• "Alerta 1", "Alerta de teste", "CPU alta"

Inclua contexto suficiente

Sua mensagem de alerta deve responder:

• O que aconteceu? A condição específica que foi acionada
• Onde? Qual sistema, serviço ou instância
• Qual a gravidade? Valor atual em relação ao limite
• Quando? A data e a hora do alerta
• E agora? Link para o dashboard ou runbook relevante

Configure níveis de prioridade

Use os tipos de notificação do Echobell de forma estratégica:

• Normal: alertas informativos, notificações de resolução, avisos não urgentes
• Urgente: alertas importantes que exigem atenção em algumas horas
• Chamada: problemas críticos em produção que exigem resposta imediata

Mapeie os níveis de severidade do Grafana para os tipos de notificação:

Critical + Production → Calling
High + Production → Time Sensitive  
Medium → Time Sensitive
Low → Normal
Info/Resolved → Normal

Segurança dos alertas

Proteja sua infraestrutura de monitoramento:

• Mantenha as URLs de webhook em segredo - Elas permitem enviar notificações sem autenticação
• Use variáveis de ambiente - Não deixe URLs fixas nos arquivos de provisionamento do Grafana
• Rotacione os webhooks periodicamente - Principalmente quando alguém sai do time
• Monitore a entrega dos webhooks - Acompanhe as entregas com falha e investigue anomalias
• Audite as configurações de alerta - Revise regularmente quem tem acesso para modificar alertas
• Valide as origens dos alertas - Use a autenticação nativa do Grafana para os pontos de contato

Gerenciamento do ciclo de vida dos alertas

Mantenha uma boa higiene de alertas:

1. Revisão periódica - Audite os alertas a cada trimestre para remover regras obsoletas
2. Documente os alertas - Adicione descrições explicando por que cada alerta existe
3. Acompanhe o histórico - Monitore quais alertas disparam com mais frequência
4. Ajuste os limites - Use dados históricos e a taxa de falsos positivos como base
5. Arquive alertas antigos - Desative, mas preserve as regras dos serviços que serão descontinuados
6. Controle de versão - Use o provisionamento do Grafana para rastrear mudanças nos alertas

Considerações de desempenho

• Evite tempestades de alertas - Configure agrupamento e temporização adequados
• Use políticas de notificação - Direcione severidades diferentes para os canais apropriados
• Defina intervalos de espera e repetição - Evite notificações duplicadas
• Agrupe alertas semelhantes - Reduza o volume de notificações com agregação
• Considere o horário do dia - Use condições para filtrar por horário comercial

Exemplos do mundo real

Alerta de CPU alta

Title: {{instance}} CPU Critical
Body: CPU usage: {{cpu_percent}}%
Duration: {{duration}}
Time: {{time}}
Dashboard: {{dashboard_url}}

Pressão de memória

Title: Memory Warning - {{hostname}}
Body: Available: {{available_mb}}MB ({{percent_free}}%)
Threshold: {{threshold_mb}}MB
Action: Check memory-intensive processes

Serviço fora do ar

Title: 🚨 {{service_name}} Unreachable
Body: Health check failed
Last success: {{last_successful_check}}
Impact: {{affected_users}} users affected
Runbook: {{runbook_url}}

Casos de uso comuns

Monitoramento de infraestrutura

• Limites de uso de CPU, memória e disco
• Throughput de rede e perda de pacotes
• Disponibilidade de serviços e verificações de integridade
• Monitoramento do status de containers e pods

Desempenho de aplicações

• Degradação do tempo de resposta
• Aumento da taxa de erros
• Esgotamento do pool de conexões do banco de dados
• Profundidade da fila e atraso no processamento

Métricas de negócio

• Anomalias no volume de transações
• Quedas na receita por minuto
• Mudanças na contagem de usuários ativos
• Aproximação do limite de requisições da API

Monitoramento de segurança

• Tentativas de autenticação com falha
• Padrões de acesso incomuns
• Avisos de expiração de certificados
• Violações de regras de firewall

Conheça mais estratégias de integração no nosso post do blog sobre notificações em chamada do Grafana.

Solução de problemas

Se você não está recebendo alertas, siga estas etapas de diagnóstico:

O webhook não aciona notificações

1. Confira se a URL do webhook foi copiada corretamente

   • Vá até o seu canal do Echobell → Gatilhos → Webhook
   • Copie a URL completa, incluindo https://hook.echobell.one/t/
   • Verifique se nenhum espaço ou caractere extra foi adicionado ao colar no Grafana

2. Verifique se o canal está ativo

   • Abra o app Echobell
   • Vá até o seu canal de alertas do Grafana
   • Confirme que ele não foi excluído ou arquivado por engano

3. Garanta que existam inscritos ativos

   • Pelo menos uma pessoa precisa estar inscrita para receber notificações
   • Confira a lista de inscrições do canal
   • Confirme que a sua própria inscrição está ativa

4. Verifique a configuração do ponto de contato do Grafana

   • No Grafana, vá em Alerting → Contact points
   • Abra o seu ponto de contato do Echobell
   • Confirme que a URL corresponde ao webhook do seu canal
   • Verifique se o HTTP Method está definido como POST
   • Confirme que o Content-Type é application/json

5. Verifique a configuração da regra de alerta do Grafana

   • Navegue até Alerting → Alert rules
   • Abra a regra específica que deveria disparar
   • Confirme que a regra está vinculada ao seu ponto de contato do Echobell
   • Verifique se a política de notificação encaminha para o ponto de contato correto

6. Revise o histórico de alertas do Grafana

   • Vá em Alerting → Alert rules
   • Clique na sua regra → Show history
   • Confirme que o alerta está mesmo disparando (e não em estado pendente)
   • Verifique se há erros de avaliação

Os alertas disparam, mas não chegam

1. Teste o webhook diretamente

   curl -X POST https://hook.echobell.one/t/<channel-token> \
     -H "Content-Type: application/json" \
     -d '{"alertName": "Test", "status": "firing"}'

   Se você receber uma notificação por aqui, mas não pelo Grafana, o problema está na configuração do Grafana.

2. Confira as políticas de notificação do Grafana

   • Vá em Alerting → Notification policies
   • Confirme que os labels da sua regra correspondem às regras de roteamento da política
   • Procure problemas de temporização (tempo de espera do agrupamento, intervalos de repetição)

3. Revise os logs do Grafana

   • Procure erros de entrega de webhook nos logs do Grafana
   • Verifique os códigos de status HTTP (o esperado é 200)
   • Investigue erros de timeout ou de conexão

As notificações aparecem incorretas

1. As variáveis do modelo não correspondem ao payload do Grafana

   • O Grafana envia nomes de campo específicos, como .alertName, .status etc.
   • Confirme que as variáveis do seu modelo correspondem à estrutura do payload
   • Teste com o botão "Test" do Grafana para ver o payload real

2. Faltam informações nas notificações

   • Algumas variáveis do Grafana podem vir vazias, dependendo da configuração do alerta
   • Adicione valores padrão nos modelos: {{alertName || "Unknown Alert"}}
   • Consulte a documentação do Grafana para ver as variáveis de modelo disponíveis

3. Erros de leitura do JSON

   • Confirme que o modelo de mensagem do Grafana é um JSON válido
   • Procure aspas ou caracteres especiais sem escape
   • Use validadores de JSON online para conferir a estrutura do payload

Problemas de temporização dos alertas

1. Atrasos para receber os alertas

   • Verifique a sua conexão de rede
   • Confirme que o Grafana consegue alcançar os servidores do Echobell
   • Revise o intervalo de avaliação do Grafana (ele pode causar atrasos)
   • Confira as configurações de temporização da política de notificação

2. Notificações duplicadas

   • Revise as configurações de intervalo de repetição nas políticas de notificação
   • Verifique se várias regras estão disparando para a mesma condição
   • Confirme que apenas um ponto de contato está configurado para o canal

3. Notificações durante períodos de silêncio

   • Os modos de Foco do iOS podem afetar a entrega das notificações
   • Notificações Urgentes e de Chamada conseguem contornar alguns modos de Foco
   • Revise as configurações de notificação do seu dispositivo

Ainda com problemas?

Se você já tentou tudo isso e o problema continua:

1. Ative o log de depuração do Grafana

   • Adicione a seção [log] ao grafana.ini com level = debug
   • Procure nos logs as tentativas de entrega do webhook e as respostas

2. Use o recurso de teste nativo do Grafana

   • Nas configurações do ponto de contato, use "Test" para enviar um alerta de exemplo
   • Isso ajuda a isolar se o problema está nas regras ou na entrega

3. Teste com outra regra de alerta

   • Crie uma regra de teste simples com condições que certamente vão disparar
   • Se o teste funcionar mas as regras de produção não, o problema está na configuração da regra

4. Fale com o suporte

   • Acesse a nossa Central de Suporte
   • Envie um e-mail para echobell@weelone.com com:
     • A versão do Grafana
     • Um payload de alerta de exemplo (sem dados sensíveis)
     • A URL do webhook (com o token ocultado)
     • As etapas que você já tentou
     • O comportamento esperado e o comportamento real

Documentação e recursos relacionados

Documentação do Echobell

• Guia de integração com webhook - Entenda a fundo como os webhooks funcionam
• Sistema de modelos - Domine a sintaxe dos modelos de notificação
• Condições - Filtre alertas com base em critérios
• Tipos de notificação - Entenda as prioridades dos alertas
• Primeiros passos - Fundamentos e configuração do Echobell

Recursos do Grafana

• Documentação de alertas do Grafana - Guia oficial de alertas do Grafana
• Pontos de contato - Configuração de pontos de contato no Grafana
• Políticas de notificação - Roteamento e agrupamento de alertas
• Regras de alerta - Como criar e gerenciar regras de alerta

Integrações relacionadas

• Integração com Prometheus - Alertas direto do Prometheus
• Uptime Kuma - Monitoramento de uptime de sites
• GitHub Actions - Alertas de pipelines de CI/CD
• Home Assistant - Notificações de casa inteligente

Posts do blog

• Ative notificações por chamada telefônica para alertas do Grafana - Estratégias avançadas de integração com o Grafana
• Nunca perca uma falha do GitHub Actions - Boas práticas de alertas de CI/CD
• Notificações por janela de tempo usando condições UTC - Filtragem por horário comercial

Próximos passos

Agora que o Grafana está integrado ao Echobell:

1. Refine seus alertas - Ajuste os limites com base nos padrões de uso reais
2. Crie canais adicionais - Separe canais por nível de severidade
3. Explore outras integrações - Conecte mais ferramentas ao Echobell (veja todas as integrações)
4. Compartilhe com seu time - Adicione os membros do time aos seus canais de alerta
5. Documente sua configuração - Crie runbooks para responder a alertas específicos
6. Meça a eficácia dos alertas - Acompanhe as taxas de falsos positivos e os tempos de resposta

Quer monitorar mais sistemas? Confira o nosso guia completo de integrações para conhecer outras ferramentas e plataformas populares de monitoramento.