PAV-126: [Observabilidade] Expor métricas completas do scraper, classificação e indexação

[hltav]

Resumo

Implementa a PAV-126 adicionando observabilidade operacional completa para o Jobs Processor e backend, cobrindo execução, concorrência, lock distribuído, classificação, persistência, indexação, cache e métricas HTTP.

A implementação preserva os contratos entregues pelas PAV-123, PAV-124 e PAV-125 e evita duplicação de métricas já existentes.

Principais mudanças

Processor / Go

• adiciona métricas operacionais do pipeline;
• adiciona estado de execução e progresso;
• instrumenta concorrência global e por provider;
• instrumenta lock distribuído;
• adiciona métricas de classificação;
• adiciona métricas de persistência;
• adiciona métricas de indexação;
• adiciona métricas de rebuild e reconciliação;
• adiciona métricas de manutenção;
• normaliza labels de provider e tipos de erro;
• controla cardinalidade de métricas;
• mantém runId, jobId, títulos, URLs e outros dados de alta cardinalidade fora das labels Prometheus;
• preserva PostgreSQL como fonte de verdade e Valkey como camada derivada de índice/cache.

Backend

• adiciona métricas operacionais de cache e busca;
• melhora métricas HTTP usando rotas normalizadas;
• evita labels com IDs ou caminhos dinâmicos;
• adiciona endpoint administrativo de observabilidade;
• adiciona suporte a disponibilidade parcial do snapshot operacional;
• adiciona timeout dedicado para consultas administrativas ao Processor;
• mantém o endpoint administrativo protegido pela estrutura existente de autenticação/RBAC;
• documenta o contrato no Swagger reutilizando o schema Zod.

Observabilidade

• adiciona 14 recording rules;
• adiciona 16 alertas;
• conecta recording rules e alert rules ao Prometheus;
• adiciona testes das regras;
• adiciona métricas e alertas para CPU, memória, lock, progresso, erros, timeouts, persistência, indexação, reconciliação e latência;
• utiliza períodos sustentados para evitar alertas por picos curtos.

Cache e indexação

• adiciona métricas de hit, miss, stale e error;
• instrumenta get, set e invalidation;
• diferencia corretamente resultados stale;
• registra invalidações por motivo controlado;
• mantém cache keys fora das labels Prometheus.

Manutenção

• rebuild e reconciliação passam a gerar telemetria operacional;
• resumos de manutenção são persistidos em chaves fixas para continuarem disponíveis após a execução do comando;
• telemetria não bloqueia persistência nem publicação do catálogo;
• nenhuma operação destrutiva global foi adicionada.

Endpoint administrativo

Foi adicionado suporte a snapshot operacional administrativo para consumo futuro pelo front_admin.

O endpoint:

• retorna estado atual da execução;
• expõe progresso;
• expõe lock;
• expõe concorrência;
• expõe recursos;
• expõe estado de indexação/manutenção;
• suporta disponibilidade parcial;
• possui timeout;
• não consulta Prometheus individualmente para montar o payload;
• não expõe secrets, tokens ou dados sensíveis.

Quando não existe execução ativa, o estado permanece compatível com idle.

Cardinalidade

A implementação evita labels com alta cardinalidade.

Não são utilizadas como labels:

• runId;
• jobId;
• URL;
• título da vaga;
• descrição;
• erro bruto;
• keyword livre;
• cache key completa;
• e-mail;
• user ID;
• company arbitrária.

São utilizados conjuntos controlados para:

• provider;
• family;
• source;
• status;
• stage;
• result;
• reason;
• error type;
• operation;
• route template.

Validações executadas

Go

• go test ./...
• go test -race ./...
• go vet ./...

Backend

• 848 testes aprovados;
• TypeScript validado com tsc --noEmit;
• Swagger validado.

Prometheus

• configuração validada com promtool;
• recording rules validadas;
• alert rules validadas;
• testes das regras aprovados.

Projeto

• Docker Compose validado;
• git diff --check aprovado;
• working tree limpa antes do commit.

Escopo

Alterações concentradas em:

• scraper-go/**
• backend/**
• observability/**
• docker-compose*.yml
• .env.example
• SCRAPER.md
• BACKEND.md
• .gitignore

Não houve alterações em:

• frontend/**
• front_admin/**
• package-lock.json

Limitações e validação em staging/produção

Ainda é necessário validar em ambiente representativo:

• p95 de /jobs/search;
• p95 do endpoint administrativo;
• ciclo completo do cron;
• consumo de CPU;
• consumo de memória;
• cardinalidade total;
• custo de scrape;
• comportamento de alertas;
• entrega de notificações do Alertmanager.

A meta de p95 < 500 ms não é declarada como comprovada nesta PAV.

Rollback

Em caso de problema:

• desabilitar recording rule ou alerta problemático;
• reverter a imagem da aplicação;
• preservar logs e séries para análise;
• evitar limpeza global de Valkey;
• remover métricas específicas apenas de forma controlada.

Commit

611cdd4 feat(PAV-126): adiciona observabilidade operacional completa

[Victor-Sarris]

eita bixo sabido