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:

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:

dotnet build
dotnet list package

🔧 Configuração do Seq

Instalação Local (Desenvolvimento)

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

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:

{
  "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

ApplicationName = 'QRRapido' 
and QRGeneration = true 
and @Level = 'Information'
| summarize AvgTime = avg(TotalRequestTimeMs), 
           Count = count() by bin(@Timestamp, 5m)

2. MongoDB Growth Monitoring

ApplicationName = 'QRRapido' 
and MongoDbMonitoring = true
| project @Timestamp, DatabaseSizeMB, GrowthRateMBPerHour

3. Resource Alerts

ApplicationName = 'QRRapido' 
and (CpuUsagePercent > 80 or WorkingSetMB > 512)
and @Level in ['Warning', 'Error']

4. Error Analysis

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)

{
  "@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

{
  "@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

{
  "@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! 🎉