QrRapido/INSTRUMENTATION_SETUP.md

# QRRapido - Instrumentação Completa com Serilog + Seq + Monitoramento

Este documento descreve a implementação completa de observabilidade para a aplicação QRRapido, incluindo logging estruturado, monitoramento de recursos e health checks.

## 📋 Resumo da Implementação

✅ **Serilog com múltiplos sinks** (Console + Seq com fallback resiliente)  
✅ **Monitoramento de recursos** (CPU, Memória, GC)  
✅ **Monitoramento MongoDB** (Tamanho, crescimento, collections)  
✅ **Health checks completos** (MongoDB, Seq, Resources, External Services)  
✅ **Logging estruturado** nos controllers críticos  
✅ **Configuração multi-ambiente** (Development, Production)  

## 🚀 Instalação dos Pacotes

Execute o comando completo para instalar todos os pacotes necessários:

```bash
cd /mnt/c/vscode/qrrapido

dotnet add package Serilog.AspNetCore --version 8.0.0 && \
dotnet add package Serilog.Sinks.Console --version 5.0.1 && \
dotnet add package Serilog.Sinks.Seq --version 6.0.0 && \
dotnet add package Serilog.Sinks.Async --version 1.5.0 && \
dotnet add package Serilog.Enrichers.Environment --version 2.3.0 && \
dotnet add package Serilog.Enrichers.Thread --version 3.1.0 && \
dotnet add package Serilog.Enrichers.Process --version 2.0.2 && \
dotnet add package Serilog.Enrichers.AssemblyName --version 1.0.9 && \
dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks --version 8.0.0 && \
dotnet add package AspNetCore.HealthChecks.MongoDb --version 7.0.0 && \
dotnet add package System.Diagnostics.PerformanceCounter --version 8.0.0
```

Depois verifique a instalação:
```bash
dotnet build
dotnet list package
```

## 🔧 Configuração do Seq

### Instalação Local (Desenvolvimento)
```bash
# Via Docker
docker run --name seq -d --restart unless-stopped -e ACCEPT_EULA=Y -p 5341:80 datalust/seq:latest

# Via Chocolatey (Windows)
choco install seq

# Via HomeBrew (macOS)
brew install --cask seq
```

### Configuração de Produção
1. Configure o Seq em um servidor dedicado
2. Configure túnel SSH se necessário:
```bash
ssh -L 5341:localhost:5341 user@seq-server
```
3. Atualize `appsettings.Production.json` com a URL e API Key do Seq

## 📊 Endpoints de Health Check

A aplicação agora possui vários endpoints para monitoramento:

### 🔍 Health Check Detalhado (Uptime Kuma)
```
GET /health/detailed
```

**Resposta estruturada:**
```json
{
  "applicationName": "QRRapido",
  "status": "healthy|degraded|unhealthy",
  "timestamp": "2025-07-28T10:30:00Z",
  "uptime": "2d 4h 15m",
  "checks": {
    "mongodb": {
      "status": "ok",
      "latency": "45ms",
      "databaseSizeMB": 245.7,
      "documentCount": 15420,
      "version": "7.0.5"
    },
    "seq": {
      "status": "ok",
      "reachable": true,
      "lastLog": "2025-07-28T10:29:45Z"
    },
    "resources": {
      "status": "ok",
      "cpu": "23%",
      "memory": "245MB",
      "gcPressure": "low"
    },
    "externalServices": {
      "status": "ok",
      "services": [
        {"service": "stripe", "status": "ok", "latencyMs": 250},
        {"service": "google_auth", "status": "ok", "latencyMs": 150}
      ]
    }
  },
  "version": "1.0.0"
}
```

### 🎯 Endpoints Específicos
```
GET /health/mongodb        - MongoDB específico
GET /health/seq           - Seq específico  
GET /health/resources     - Recursos do sistema
GET /health/external      - Serviços externos
GET /health/simple        - Status geral simples
GET /health/uptime-kuma   - Otimizado para Uptime Kuma
```

## 📈 Configuração do Uptime Kuma

1. **Criar Monitor HTTP(s)**:
   - URL: `https://seu-dominio.com/health/detailed`
   - Method: `GET`
   - Interval: `60 segundos`

2. **Configurar JSON Query** (opcional):
   - JSON Path: `$.status`
   - Expected Value: `healthy`

3. **Alertas Avançados**:
   - JSON Path para CPU: `$.checks.resources.cpu`
   - JSON Path para DB Size: `$.checks.mongodb.databaseSizeMB`

## 🎛️ Dashboard do Seq

### Queries Essenciais para Dashboards

#### 1. QR Generation Performance
```sql
ApplicationName = 'QRRapido' 
and QRGeneration = true 
and @Level = 'Information'
| summarize AvgTime = avg(TotalRequestTimeMs), 
           Count = count() by bin(@Timestamp, 5m)
```

#### 2. MongoDB Growth Monitoring  
```sql
ApplicationName = 'QRRapido' 
and MongoDbMonitoring = true
| project @Timestamp, DatabaseSizeMB, GrowthRateMBPerHour
```

#### 3. Resource Alerts
```sql
ApplicationName = 'QRRapido' 
and (CpuUsagePercent > 80 or WorkingSetMB > 512)
and @Level in ['Warning', 'Error']
```

#### 4. Error Analysis
```sql
ApplicationName = 'QRRapido' 
and @Level = 'Error'
| summarize Count = count() 
  by @Message, bin(@Timestamp, 1h)
```

## 🔔 Alertas Configurados

### MongoDB
- **Database > 1GB**: Warning
- **Database > 5GB**: Error  
- **Growth > 100MB/hour**: Warning
- **Collections > 100MB**: Information

### Recursos do Sistema
- **CPU > 80% por 2 minutos**: Warning
- **CPU > 80% por 4+ minutos**: Error
- **Memory > 512MB**: Warning
- **Memory > 768MB**: Error
- **GC Pressure alta**: Warning

### QR Generation
- **Response time > 2s**: Warning
- **Rate limiting ativado**: Information
- **Generation failures**: Error
- **Cache miss ratio > 50%**: Warning

## 📁 Estrutura de Arquivos Criados

```
QRRapidoApp/
├── Services/
│   ├── Monitoring/
│   │   ├── ResourceMonitoringService.cs      # Monitor CPU/Memory/GC
│   │   └── MongoDbMonitoringService.cs       # Monitor MongoDB
│   └── HealthChecks/
│       ├── MongoDbHealthCheck.cs             # Health check MongoDB
│       ├── SeqHealthCheck.cs                 # Health check Seq
│       ├── ResourceHealthCheck.cs            # Health check Recursos
│       └── ExternalServicesHealthCheck.cs    # Health check APIs
├── Controllers/
│   └── HealthController.cs                   # Endpoints health check
├── appsettings.json                          # Config base
├── appsettings.Development.json              # Config desenvolvimento
├── appsettings.Production.json               # Config produção
├── Program.cs                                # Serilog + Services
├── PACKAGES_TO_INSTALL.md                   # Lista de pacotes
└── INSTRUMENTATION_SETUP.md                 # Esta documentação
```

## 🛠️ Personalização por Ambiente

### Development
- Logs mais verbosos (Debug level)
- Thresholds mais relaxados
- Intervalos de monitoramento maiores
- Health checks com timeout maior

### Production  
- Logs otimizados (Information level)
- Thresholds rigorosos para alertas
- Intervalos de monitoramento menores
- Health checks com timeout menor
- Integração com serviços externos habilitada

## 🔍 Logs Estruturados Implementados

### QR Generation (Controller mais crítico)
```json
{
  "@t": "2025-07-28T10:30:00.123Z",
  "@l": "Information", 
  "@m": "QR generation completed",
  "ApplicationName": "QRRapido",
  "RequestId": "abc12345",
  "UserId": "user123",
  "QRType": "url",
  "TotalRequestTimeMs": 450,
  "QRGenerationTimeMs": 320,
  "FromCache": false,
  "UserType": "premium",
  "Success": true
}
```

### Resource Monitoring
```json
{
  "@t": "2025-07-28T10:30:00.123Z",
  "@l": "Information",
  "@m": "Resource monitoring",
  "ApplicationName": "QRRapido", 
  "ResourceMonitoring": true,
  "CpuUsagePercent": 23.5,
  "WorkingSetMB": 245,
  "GcPressure": 3,
  "ThreadCount": 45,
  "Status": "Healthy"
}
```

### MongoDB Monitoring
```json
{
  "@t": "2025-07-28T10:30:00.123Z", 
  "@l": "Information",
  "@m": "MongoDB monitoring",
  "ApplicationName": "QRRapido",
  "MongoDbMonitoring": true,
  "DatabaseName": "qrrapido",
  "DatabaseSizeMB": 245.7,
  "GrowthRateMBPerHour": 12.3,
  "DocumentCount": 15420,
  "Collections": [
    {"name": "Users", "documentCount": 1250, "sizeMB": 15.4},
    {"name": "QRCodeHistory", "documentCount": 14000, "sizeMB": 215.2}
  ],
  "Status": "Healthy"
}
```

## 🚦 Próximos Passos

1. **Instalar os pacotes** usando o comando fornecido
2. **Configurar o Seq** localmente ou em produção
3. **Compilar a aplicação** com `dotnet build`
4. **Testar os health checks** acessando `/health/detailed`
5. **Configurar o Uptime Kuma** com os endpoints fornecidos
6. **Criar dashboards no Seq** usando as queries sugeridas
7. **Configurar alertas** baseados nos logs estruturados

## 🔧 Troubleshooting

### Seq não conecta
- Verificar se Seq está rodando: `http://localhost:5341`
- Verificar firewall/portas
- Aplicação continua funcionando (logs só no console)

### MongoDB health check falha
- Verificar connection string
- Verificar permissões de banco
- Health check retorna "degraded" mas aplicação continua

### Performance degradada
- Verificar logs de resource monitoring
- Ajustar intervalos nos `appsettings.json`
- Monitorar CPU/Memory via health checks

### Alertas muito frequentes
- Ajustar thresholds em `appsettings.json`
- Aumentar `ConsecutiveAlertsBeforeError`
- Configurar níveis de log apropriados

---

A aplicação QRRapido agora possui observabilidade completa, mantendo toda a funcionalidade existente intacta! 🎉