# 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
![Dashboard Principal](https://via.placeholder.com/800x400?text=Portal+Jurunense+Main+Dashboard)

**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

```bash
# 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:

```typescript
// 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.