--- title: "Integração com Grafana - Alertas de infraestrutura" sidebarTitle: Grafana description: Envie alertas do Grafana para o Echobell via webhook e receba notificações push instantâneas ou chamadas telefônicas. Configuração passo a passo com modelos de alerta. --- import { Step, Steps } from "fumadocs-ui/components/steps"; # Integração com Grafana 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](/docs)) - 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 ### Criar um canal no Echobell 1. Abra o app Echobell 2. Crie um novo canal (por exemplo, "Alertas do Grafana") 3. Escolha uma cor marcante para identificá-lo com facilidade ### Configurar modelos de notificação Configure modelos que formatem seus alertas do Grafana de forma eficaz: **Modelo de título:** ``` {{alertName}} - {{status}} ``` **Modelo de corpo:** ``` 🔔 Alert: {{alertName}} 📊 Metric: {{metric}} 📈 Value: {{value}} ⏰ Time: {{time}} ℹ️ Message: {{message}} ``` Esses modelos funcionam com a estrutura do payload de alertas do Grafana. ### Obter a URL do webhook 1. Nas configurações do seu canal, localize a seção **Gatilhos** 2. Copie a URL do webhook exibida 3. Mantenha essa URL em segurança, porque ela será usada na configuração do Grafana ### Configurar o ponto de contato do Grafana 1. No Grafana, vá em **Alerting** → **Contact points** 2. Clique em **New contact point** 3. Defina o seguinte: - Nome: "Echobell" - Tipo: "Webhook" - URL: a URL do webhook do seu Echobell - Método HTTP: POST - Tipo de conteúdo: application/json 4. Configure o modelo de mensagem: ```json { "alertName": "{{ .alertName }}", "status": "{{ .status }}", "metric": "{{ .metric }}", "value": "{{ .value }}", "time": "{{ .time }}", "message": "{{ .message }}", "externalLink": "{{ .dashboardURL }}" } ``` ### Criar regras de alerta 1. Navegue até **Alerting** → **Alert rules** 2. Crie uma nova regra de alerta ou edite uma existente 3. Na configuração da regra: - Defina condições adequadas para suas métricas - Selecione o ponto de contato "Echobell" - Configure os critérios de avaliação do alerta ## 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](/docs/notification) 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](/docs/conditions) 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](/blog/grafana-call-notification). ## 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** ```bash curl -X POST https://hook.echobell.one/t/ \ -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](/docs/support) - 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](/docs/webhook)** - Entenda a fundo como os webhooks funcionam - **[Sistema de modelos](/docs/template)** - Domine a sintaxe dos modelos de notificação - **[Condições](/docs/conditions)** - Filtre alertas com base em critérios - **[Tipos de notificação](/docs/notification)** - Entenda as prioridades dos alertas - **[Primeiros passos](/docs)** - Fundamentos e configuração do Echobell ### Recursos do Grafana - **[Documentação de alertas do Grafana](https://grafana.com/docs/grafana/latest/alerting/)** - Guia oficial de alertas do Grafana - **[Pontos de contato](https://grafana.com/docs/grafana/latest/alerting/fundamentals/contact-points/)** - Configuração de pontos de contato no Grafana - **[Políticas de notificação](https://grafana.com/docs/grafana/latest/alerting/fundamentals/notification-policies/)** - Roteamento e agrupamento de alertas - **[Regras de alerta](https://grafana.com/docs/grafana/latest/alerting/fundamentals/alert-rules/)** - Como criar e gerenciar regras de alerta ### Integrações relacionadas - **[Integração com Prometheus](/docs/developer/prometheus)** - Alertas direto do Prometheus - **[Uptime Kuma](/docs/developer/uptime-kuma)** - Monitoramento de uptime de sites - **[GitHub Actions](/docs/developer/github)** - Alertas de pipelines de CI/CD - **[Home Assistant](/docs/developer/home-assistant)** - Notificações de casa inteligente ### Posts do blog - **[Ative notificações por chamada telefônica para alertas do Grafana](/blog/grafana-call-notification)** - Estratégias avançadas de integração com o Grafana - **[Nunca perca uma falha do GitHub Actions](/blog/github-actions-notifications)** - Boas práticas de alertas de CI/CD - **[Notificações por janela de tempo usando condições UTC](/blog/time-window-notifications-using-utc-conditions)** - 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](/docs/features)) 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](/docs/features) para conhecer outras ferramentas e plataformas populares de monitoramento.