Repository navigation
Merged
Conversation
…ificação e indexação (#310) ## 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`
Benevanio
approved these changes
Oct 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Release
Promove para produção as alterações da PAV-126 já aprovadas e mergeadas em
develop.Conteúdo
PAV-126 — Observabilidade completa do scraper, classificação e indexação.
Principais entregas:
Validações realizadas
go test ./...go test -race ./...go vet ./...promtoolgit diff --checkaprovadoProdução
Após o deploy, validar:
/jobs/search;A meta de p95 < 500 ms deverá ser validada com carga representativa em produção/staging.
Origem
develop→masterPR de implementação:
PAV-126: [Observabilidade] Expor métricas completas do scraper, classificação e indexação (#310)