portalweb-api/monitoring-implementation.md

Implementação de Monitoramento e Alertas

Visão Geral

Este documento descreve a implementação de um sistema completo de monitoramento e alertas para o Portal Jurunense API, baseado em Prometheus, Grafana e AlertManager. O sistema permite visualizar métricas de performance, configurar dashboards personalizados e receber alertas automáticos quando ocorrerem problemas.

Componentes Implementados

1. Coleta de Métricas

Métricas da API

• HTTP: Requisições, duração, códigos de status
• Recursos: Uso de CPU, memória, disco
• Banco de Dados: Conexões de pool, duração de queries
• Negócio: Métricas específicas do domínio (pedidos, pagamentos, etc.)

Implementação

• Integração com @willsoto/nestjs-prometheus
• Endpoint /metrics exposto para scraping do Prometheus
• Interceptor para coleta automática de métricas HTTP
• Serviço personalizado para métricas de negócio

2. Dashboards Grafana

Dashboard Principal

Painéis Incluídos:

• Visão geral da saúde da aplicação
• Taxa de requisições por segundo
• Latência das requisições (percentis)
• Uso de recursos (CPU, memória, disco)
• Taxa de erros HTTP

Dashboard de Banco de Dados

![Dashboard de Banco de Dados](

Painéis Incluídos:

• Uso do pool de conexões
• Tempo de resposta de queries
• Queries em execução
• Erros de banco de dados
• Saúde das conexões

Dashboard de Negócio

![Dashboard de Negócio]

Painéis Incluídos:

• Pedidos por hora/dia
• Taxa de conversão de pagamentos
• Erros de processamento
• Tempo de resposta de APIs externas
• Alertas ativos

3. Sistema de Alertas

Alertas Implementados

• Disponibilidade: Serviço fora do ar
• Performance: Tempo de resposta elevado
• Recursos: Uso elevado de memória, CPU ou disco
• Banco de Dados: Pool de conexões quase esgotado
• Negócio: Erros de integração com serviços externos

Canais de Notificação

• Email: Para alertas não críticos e relatórios diários
• Slack: Para alertas em tempo real, com cores baseadas na severidade
• Microsoft Teams: Alternativa para organizações que usam Teams
• SMS/Chamada (opcional): Para alertas críticos fora do horário comercial

4. Arquitetura de Monitoramento

┌─────────────┐    ┌────────────┐    ┌─────────────┐
│ API         │    │ Prometheus │    │ Grafana     │
│ (/metrics)  │───▶│ (Coleta)   │───▶│ (Dashboards)│
└─────────────┘    └────────────┘    └─────────────┘
                         │                  ▲
                         ▼                  │
                   ┌────────────┐    ┌─────────────┐
                   │AlertManager│───▶│ Notificações│
                   │ (Alertas)  │    │ (Email/Slack)│
                   └────────────┘    └─────────────┘

Configuração e Uso

Iniciando o Sistema de Monitoramento

# Iniciar todos os serviços de monitoramento
docker-compose -f docker-compose.monitoring.yml up -d

# Verificar status dos serviços
docker-compose -f docker-compose.monitoring.yml ps

# Visualizar logs
docker-compose -f docker-compose.monitoring.yml logs -f

Acessando as Interfaces

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)
• AlertManager: http://localhost:9093

Customizando Alertas

1. Edite o arquivo monitoring/prometheus/rules/portaljuru_alerts.yml
2. Adicione ou modifique regras de alerta usando a sintaxe PromQL
3. Recarregue a configuração: curl -X POST http://localhost:9090/-/reload

Customizando Dashboards

1. Acesse o Grafana: http://localhost:3000
2. Faça login com as credenciais padrão (admin/admin)
3. Navegue até Dashboards > Browse
4. Clone um dashboard existente ou crie um novo
5. Use o editor visual para adicionar painéis e consultas

Integração com APM (Application Performance Monitoring)

Além do monitoramento baseado em métricas, implementamos integração com ferramentas de APM para rastreamento distribuído e profiling:

Jaeger para Rastreamento Distribuído

• Endpoint: http://localhost:16686
• Features:
  • Visualização de traces completos de requisições
  • Análise de gargalos em calls entre serviços
  • Rastreamento de erros e exceções

Configuração de Rastreamento Distribuído

O código abaixo foi adicionado para habilitar o rastreamento:

// Trecho simplificado. O código completo está no módulo de saúde.
import { TracingModule } from './tracing.module';

@Module({
  imports: [
    TracingModule.forRoot({
      serviceName: 'portaljuru-api',
      samplingRate: 0.3, 
    }),
    // ...
  ],
})
export class AppModule {}

Monitoramento Proativo

Implementamos monitoramento proativo através de:

1. Health Checks Periódicos: Verificações automáticas a cada 5 minutos
2. Alertas Preditivos: Baseados em tendências anômalas de métricas
3. Relatórios Diários: Resumo automático enviado diariamente por email
4. Página de Status: Disponível em /health/status para usuários finais

Boas Práticas

1. Métricas Relevantes: Foco em métricas que refletem a experiência do usuário
2. Alertas Acionáveis: Somente alertar em situações que precisam de ação humana
3. Redução de Ruído: Agrupamento e correlação de alertas para evitar fadiga
4. Documentation as Code: Dashboards e regras de alerta versionadas no git
5. Runbooks: Documentação de resposta para cada tipo de alerta

Próximos Passos

1. Expandir Métricas de Negócio: Adicionar KPIs específicos para cada domínio
2. Machine Learning: Implementar detecção de anomalias baseada em ML
3. Logs Centralizados: Integrar com ELK Stack para correlação logs-métricas
4. SLOs e SLIs: Definir e monitorar objetivos de nível de serviço
5. Automação de Remediação: Scripts para resposta automática a problemas comuns

Conclusão

O sistema de monitoramento implementado proporciona visibilidade completa sobre a saúde e performance do Portal Jurunense API. Com dashboards intuitivos e alertas precisos, a equipe pode detectar e resolver problemas rapidamente, reduzindo o tempo médio de recuperação (MTTR) e melhorando a confiabilidade do serviço.