Dashboard de Monitorização de Ingestão

Sistema de monitorização simples para acompanhar o estado das sincronizações de dados e dos jobs que escrevem em job_execution_logs.

Endpoints

GET /admin/ingestion-status

Retorna o status consolidado de todas as ingestões.

Autenticação: Requer token JWT

Resposta:

{
  "timestamp": "2025-12-24T16:05:00.000Z",
  "jobs": [
    {
      "jobType": "sync-radios",
      "lastExecution": {
        "status": "completed",
        "startedAt": "2025-12-24T03:00:00.000Z",
        "completedAt": "2025-12-24T03:05:32.000Z",
        "duration": 332000,
        "stats": {
          "total": 150,
          "created": 5,
          "updated": 145,
          "failed": 0,
          "skipped": 0
        },
        "warnings": 0,
        "errors": 0
      },
      "summary": {
        "totalExecutions": 42,
        "successRate": 98.5,
        "averageDuration": 315000,
        "last24h": 1
      }
    },
    // ... outros jobs
  ],
  "overallHealth": "healthy" // ou "warning" ou "critical"
}

GET /admin/ingestion-status/history

Retorna as últimas 50 execuções de todos os jobs.

Autenticação: Requer token JWT

Resposta:

{
  "total": 50,
  "executions": [
    {
      "id": "67ab123...",
      "jobType": "sync-episodes",
      "status": "completed",
      "startedAt": "2025-12-24T06:00:00.000Z",
      "completedAt": "2025-12-24T06:15:22.000Z",
      "duration": 922000,
      "stats": {
        "total": 50,
        "created": 120,
        "updated": 45,
        "failed": 2,
        "skipped": 5
      },
      "warnings": 1,
      "errors": 2,
      "hasDetails": true
    },
    // ... mais execuções
  ]
}

Status de Health

O sistema calcula automaticamente o health geral baseado em:

• healthy (90-100%): Todas as sincronizações executaram recentemente (< 24h) com sucesso e mínimos erros (< 5)
• warning (70-89%): Algumas sincronizações falharam ou estão desatualizadas
• critical (< 70%): Múltiplas sincronizações falharam ou não executaram

Armazenamento de Logs

• Logs são salvos automaticamente em cada execução de job
• Retenção: 7 dias (TTL automático via MongoDB)
• Collection: job_execution_logs

Estrutura do Log

{
  jobType: 'sync-episodes',
  status: 'completed', // started | completed | failed | partial
  startedAt: Date,
  completedAt: Date,
  duration: 922000, // milissegundos
  stats: {
    total: 50,
    created: 120,
    updated: 45,
    failed: 2,
    skipped: 5
  },
  warnings: ['Podcast X não respondeu'],
  errors: [
    {
      message: 'Failed to fetch RSS',
      context: 'podcast-id-123',
      timestamp: Date
    }
  ],
  metadata: {
    jobId: 'bull-job-id',
    triggeredBy: 'cron' // ou 'manual' ou 'api'
  }
}

Tipos de Jobs

1. sync-radios: Sincronização de rádios do Radio Browser
2. sync-programs: Sincronização de programação/EPG (placeholder)
3. sync-podcasts: Sincronização de metadados de podcasts
4. sync-episodes: Sincronização de episódios de todos os podcasts
5. stream-health-check: Verificação periódica da disponibilidade dos streams
6. sync-myradioonline: Ingestão semanal via MyRadioOnline
7. enrich-radios: Enriquecimento encadeado dos metadados das rádios

Jobs agendados que não escrevem em job_execution_logs continuam fora deste dashboard e são acompanhados na página Jobs & Crons. A matriz completa está em docs/features/JOBS_MONITORING_MATRIX.md.

Exemplo de Uso

# Obter status atual (requer autenticação)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3000/api/admin/ingestion-status

# Obter histórico
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:3000/api/admin/ingestion-status/history

Implementação

Backend (API)

• Module: AdminModule
• Controller: AdminController
• Service: IngestionStatusService
• Schema: JobExecutionLog

Worker

• Logger Service: JobExecutionLoggerService
• Schema: JobExecutionLog

Todos os processadores (SyncEpisodesProcessor, etc.) foram atualizados para registrar logs automaticamente.

Segurança

• Todos os endpoints estão protegidos por JwtAuthGuard
• Apenas usuários autenticados podem acessar os dados de monitorização
• Não há exposição pública de informações internas do sistema

Manutenção

A limpeza de logs antigos (> 7 dias) é feita automaticamente pelo MongoDB através do índice TTL:

JobExecutionLogSchema.index(
  { createdAt: 1 }, 
  { expireAfterSeconds: 604800 } // 7 dias
);

Não é necessária intervenção manual.