Skip to content

fix: alertar agências ativas sem nenhuma execução (DagRun zumbi) - #67

Merged
nitaibezerra merged 1 commit into
mainfrom
fix/monitor-agencias-sem-execucao
Oct 22, 2026
Merged

nitaibezerra merged 1 commit into
mainfrom
fix/monitor-agencias-sem-execucao

Conversation

@nitaibezerra

@nitaibezerra nitaibezerra commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Resumo

Adiciona ao monitor_scraping_health um alerta para agência ativa sem nenhuma execução: a agência está ativa no site_urls.yaml, mas não tem nenhum scrape_run (sucesso ou erro) nas últimas scraper_silent_hours (default 2h). É o único sinal de que a DAG scrape_* parou de chamar a API. Hoje nenhuma checagem vê esse caso, porque todas partem de scrape_runs.

O PR não destrava as 4 DAGs travadas. Para isso é preciso uma ação mutante no Airflow, que precisa de aprovação humana (ver "Ação operacional pendente", abaixo). O PR passa a detectar o problema e documenta no runbook como corrigir.

Diagnóstico

Contexto: incidente "500 em /scrape/agencies desde ~18h UTC de 21/10". Diagnóstico e verificação independente, os dois somente leitura:

  1. Não houve nova onda de 500. A taxa ficou estável em ~11–12% nos últimos dias (18/10 12,3%, 21/10 11,5%, 22/10 11,9%), com 89–113 respostas 500 por hora, sem degrau às 18h. A revisão do scraper-api é a mesma desde 06/10 (00045-7hb). Os 500 vêm de 22 agências cuja seção de notícias saiu do ar no defeso eleitoral: 401, 404 ou 302 para require_login. O único fato novo é o memp: dá 401 desde 21/10 17:02Z, e a home do órgão publica um comunicado de defeso. Nada disso é tratado aqui. O plano já existente é reverter o scraper#61 depois de 25/10.
  2. DagRuns zumbis (alvo deste PR). scrape_inma, scrape_inpe, scrape_aids e scrape_patrimonio têm um único DagRun em running, sem task instances, há meses. Com max_active_runs=1, nenhum run novo é criado, e o scheduler gera ~650 linhas por hora por DAG com DAG 'scrape_X' not found in serialized_dag table.
    • Mecanismo, confirmado pela REST API (só GET) e pelo código do Airflow 3.1.0: a DagVersion mais recente de cada uma dessas DAGs foi gravada sem serialized_dag e sem dag_code. São elas aids v4, inma v5, inpe v6 e patrimonio v6, e dagSources?version_number=N responde 404 para todas. Cada uma foi criada de 15 s a 6 min depois do início do respectivo run, logo após um deploy. O bundle dags-folder não é versionado, então o scheduler resolve qualquer run para essa versão órfã.
DAG Run preso Última notícia no banco O site publica hoje?
scrape_inma scheduled__2026-04-13T16:09 24/03 sim (05, 08 e 20/10)
scrape_inpe scheduled__2026-06-11T20:56 03/06 200
scrape_aids scheduled__2026-08-21T11:27 20/08 sim (06, 07 e 08/10)
scrape_patrimonio scheduled__2026-08-21T11:33 27/01 401 (defeso)

Evidências de que o alerta pega o caso real

  • A query nova, rodada em produção em 22/10 às 04:44Z (transação read-only; EXPLAIN ANALYZE em ~6 ms, Index Only Scan em idx_scrape_runs_agency_scraped, top-1 por agência), devolve exatamente as 4 agências: aids (última execução 2026-08-21 11:32:46Z), inma (nenhuma), inpe (nenhuma) e patrimonio (2026-08-21 11:43:24Z). As 22 agências do defeso não aparecem, porque gravam scrape_run de erro a cada tentativa: são falhas, não silêncio.
  • Os alertas de hoje são só logados (as Variables de Telegram não existem no Composer) e já chegam cortados: as linhas Alert (log-only) de 22/10 01:37Z a 04:10Z têm exatamente 4096 caracteres, com 55 itens. Uma seção nova no fim da mensagem seria perdida. Por isso, a seção nova vem primeiro, cada seção lista no máximo 25 agências e a mensagem é cortada em fim de linha em 4000 caracteres.

Mudanças

  • src/govbr_scraper/monitoring/health_checks.py: SILENT_AGENCIES_QUERY e find_silent_agencies(conn, active_agencies, silent_hours=2).
  • dags/monitor_scraping_health.py:
    • nova task check_silent_agencies, que lê as agências ativas do mesmo config/site_urls.yaml usado por scrape_agencies.py;
    • send_alerts(failures, stale, silent);
    • _build_alert_message, que gera a seção "Agencias Sem Execucao" em primeiro lugar, limita cada seção a 25 linhas (... e mais N) e corta a mensagem em fim de linha em 4000 caracteres, sem quebrar o <b>.
    • Fica igual: o formato das seções já existentes, com teste garantindo isso.
  • Nova Variable opcional scraper_silent_hours (default 2, mínimo 1). Não precisa criar: o default basta.
  • docs/runbook.md: nova seção "DAG de Agência Travada (DagRun zumbi)", com diagnóstico somente leitura, correção, validação e recuperação do período perdido. Também explica como ler os alertas log-only.
  • CLAUDE.md e .secrets.baseline: atualizações de documentação. No .secrets.baseline só muda o line_number 500→501, que é o mesmo segredo de exemplo do CLAUDE.md, deslocado uma linha.

Testes (TDD: red → green)

  • Red: os testes novos falharam antes da implementação (ImportError: cannot import name 'SILENT_AGENCIES_QUERY'). Depois de implementar o health_checks, 19 testes da DAG ainda falhavam.
  • Green: pytest -m "not integration" 699 passed (eram 674 no origin/main, são 25 novos). pytest -m postgres em pgvector descartável na porta 55478: 22 passed (6 novos em tests/integration/test_postgres_health_checks.py). ruff check e ruff format limpos. Hooks do pre-commit (detect-secrets, bandit, ruff) passando.
  • Airflow 3.1.0 real, com as DAGs no layout do Composer (dags/scraper/): dags reserialize sem import errors, 159 DAGs (155 scrape_* de agência). airflow dags test monitor_scraping_health contra um Postgres local semeado com o estado de produção terminou com as 4 tasks em success, e o send_alert logou a seção "Agencias Sem Execucao" com aids, inma, inpe e patrimonio, seguida da seção de falhas consecutivas.

Deploy

O merge em main dispara "Deploy Scraper DAGs to Composer" (dags/** → gs://…/dags/scraper/). Só dags/monitor_scraping_health.py muda. scrape_agencies.py e site_urls.yaml ficam iguais, então as DAGs scrape_* não ganham versão nova, e a única DagVersion criada é a do monitor_scraping_health. Não há Terraform. Como src/govbr_scraper/monitoring/health_checks.py também muda, o merge dispara ainda "Deploy Scraper API" (src/govbr_scraper/**): uma revisão nova do destaquesgovbr-scraper-api a partir do main (hoje 00045-7hb, imagem c9e9eaa). A mudança em health_checks.py é só aditiva (função e query novas), e a API não passa a se comportar de outro jeito.

Como validar depois do deploy (somente leitura)

COMPOSER=(destaquesgovbr-composer --location southamerica-east1 --project inspire-7-finep)
# 1. Parse OK e a versão nova do monitor serializada
gcloud composer environments run "${COMPOSER[@]}" dags list-import-errors
gcloud composer environments run "${COMPOSER[@]}" dags list-runs -- monitor_scraping_health
# 2. A task nova roda e acha as 4 agências travadas (até elas serem destravadas)
gcloud logging read 'resource.type="cloud_composer_environment" AND textPayload:"Agencias ativas sem nenhuma execucao"' \
  --project=inspire-7-finep --freshness=1h --limit=3 --format='value(timestamp,textPayload)'
# 3. O alerta começa pela seção nova e não passa de 4096 caracteres
gcloud logging read 'resource.type="cloud_composer_environment" AND textPayload:"Alert (log-only)"' \
  --project=inspire-7-finep --freshness=1h --limit=1 --format='value(textPayload)' | head -8

O resultado esperado é 4 de 155 (aids, inma, inpe, patrimonio) até a ação operacional abaixo. Depois dela, a lista deve ficar vazia.

Rollback

Fazer git revert do commit e mergear. O workflow republica a versão anterior do monitor_scraping_health.py. A mudança não tem estado: não cria tabela, não exige Variable e não mexe nas DAGs de scraping.

Ação operacional pendente (fora deste PR, precisa de aprovação humana)

Destravar as 4 DAGs. Marcar o run como failed não resolve: o próximo run nasce com created_dag_version = a versão órfã e trava de novo. O que resolve é airflow dags delete, que no 3.1 apaga também dag_version e serialized_dag. Em seguida, o reparse cria uma v1 nova, já serializada:

for d in scrape_inma scrape_inpe scrape_aids scrape_patrimonio; do
  gcloud composer environments run "${COMPOSER[@]}" dags delete -- "$d" --yes
done

Depois, fazer um re-scrape dirigido (seção "Forçar Re-scrape Completo" do runbook) de aids desde 21/08, inma desde 13/04 e inpe desde 11/06. patrimonio hoje dá 401 (defeso).

Fora do escopo (risco médio ou dependente de data)

  • Reverter as URLs do defeso (scraper#61) e revalidar as 22 agências e o memp. Isso vem depois de 25/10, conforme o plano.
  • Fazer o scraper-api responder source_unavailable (sem 500 e sem retry na DAG) para 401, 404 e require_login. Isso muda o contrato com a DAG e com os relatórios.
  • Atualizar o Composer para um build 3.1.x que corrija a race de serialização. Isso vai por GitOps no infra.

🤖 Generated with Claude Code

O monitor_scraping_health só olhava scrape_runs (falhas consecutivas e
agências sem notícias), então não via uma DAG scrape_* que parou de chamar
a API. Foi o que aconteceu com scrape_inma (desde 13/04), scrape_inpe
(11/06), scrape_aids e scrape_patrimonio (21/08): um DagRun preso em
'running', sem task instances, numa DagVersion sem serialized_dag, com
max_active_runs=1. Ficaram meses sem raspar e sem nenhum alerta.

- health_checks.find_silent_agencies e task check_silent_agencies: agência
  ativa no site_urls.yaml sem nenhum scrape_run (sucesso ou erro) nas
  últimas scraper_silent_hours (default 2h, mínimo 1). Agência que falha
  grava scrape_run de erro e não entra.
- A seção "Agencias Sem Execucao" vem primeiro no alerta. Cada seção lista
  no máximo 25 agências, e a mensagem é cortada em fim de linha em 4000
  caracteres: o alerta atual já passava de 4096 e o Cloud Logging cortava
  o fim da linha "Alert (log-only)".
- Runbook "DAG de Agência Travada": diagnóstico só leitura e correção
  (dags delete; marcar o run como failed não resolve).
@nitaibezerra
nitaibezerra marked this pull request as ready for review October 22, 2026 13:57
@nitaibezerra
nitaibezerra merged commit 1504826 into main Oct 22, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant