Reduz o pico de memória na conversão e exportação de métricas diárias

[pitangainnovare]

O que esse PR faz?

Reduz o pico de memória da geração de métricas diárias ao converter os documentos mensais e anuais em 64 partições determinísticas, sem materializar milhões de documentos simultaneamente.

O processamento passa a:

• liberar o cache de metadados antes da conversão de coleções extragrandes;
• agrupar registros por identificador métrico estável, mantendo livros e capítulos do mesmo título na mesma partição;
• converter e escrever uma partição por vez no payload incremental;
• consumir progressivamente o acumulador durante a geração anual;
• registrar RSS atual, pico de RSS e memória do cgroup nas etapas principais;
• permitir configurar por ambiente o tamanho dos lotes Bulk e a compressão HTTP do OpenSearch.

A versão da aplicação é atualizada para 2.3.4. Não há migrations nem alterações de mappings.

As novas configurações são:

OPENSEARCH_BULK_CHUNK_SIZE=500
OPENSEARCH_HTTP_COMPRESS=True

Os valores acima são também os padrões, preservando o comportamento atual quando as variáveis não forem definidas.

Onde a revisão poderia começar?

A revisão pode começar em metrics/counter/indexing/converter.py, onde está a conversão particionada. Em seguida:

• metrics/counter/access/daily_accumulator.py: exposição e consumo dos registros compactos;
• metrics/counter/indexing/engines/base.py e book.py: definição das chaves de partição;
• metrics/services/parsing/job_payloads.py: integração da conversão ao job diário e liberação do cache;
• metrics/services/daily_payloads.py: escrita incremental dos documentos;
• metrics/services/memory.py: telemetria de memória;
• metrics/opensearch/client.py: lote Bulk e compressão HTTP configuráveis.

Como este poderia ser testado manualmente?

1. Processar um log PRT completo sem escrever em índices canônicos.
2. Comparar identificadores, documentos e métricas mensais e anuais com a versão 2.3.3.
3. Processar um log SCL completo na fila parse_xlarge, com concorrência 1.
4. Conferir nos logs as medições após parsing, conversão mensal, conversão anual e exportação.
5. Repetir uma exportação em índice temporário com:

OPENSEARCH_BULK_CHUNK_SIZE=2000
OPENSEARCH_HTTP_COMPRESS=True

6. Comparar posteriormente com OPENSEARCH_HTTP_COMPRESS=False, alterando apenas essa variável.

Validações locais realizadas:

• PRT: mesmas assinaturas semânticas para 13.377 documentos mensais e 20.648 anuais;
• SCL: mesmas assinaturas semânticas para 409.085 documentos mensais e 2.095.029 anuais;
• pico SCL reduzido de 6.347,9 MiB para 2.585,1 MiB, aproximadamente 59,3%;
• tempo total de parsing e conversão SCL com aumento de aproximadamente 2,7%;
• 49 testes aprovados e 2 ignorados na seleção principal;
• 9 testes aprovados para cliente OpenSearch e exportação;
• black, isort, flake8, git diff --check e gitleaks aprovados;
• python manage.py makemigrations --check --dry-run: nenhuma alteração detectada.

Algum cenário de contexto que queira dar?

Um log SCL grande chegou a produzir aproximadamente 5,5 milhões de documentos anuais. A implementação anterior mantinha o acumulador, o dicionário mensal, o dicionário anual e partes do payload simultaneamente na memória, alcançando picos próximos do limite do worker em HML.

O particionamento limita o estado temporário da conversão sem alterar identificadores ou métricas. A ordem dos documentos no JSON passa a ser determinada pelas partições e pelos identificadores; por isso, o SHA bruto pode mudar em relação à versão anterior, embora o conteúdo aplicado ao OpenSearch seja semanticamente equivalente.

Durante a análise em HML, uma exportação com lotes de 500 documentos realizou mais de 12 mil requisições Bulk. As variáveis adicionadas permitem testar lotes maiores e compressão ligada ou desligada sem nova alteração de código.

Screenshots

Não aplicável.

Quais são os tickets relevantes?

Relacionado a #128.

Referências

• OpenSearch Python client: https://docs.opensearch.org/latest/clients/python-low-level/

---

Segurança da informação (NSI.04)

Este PR manipula dados sensíveis ou pessoais (LGPD)?

• Sim — descreva os controles de proteção aplicados (criptografia, mascaramento, anonimização, etc.):
• Não

Este PR altera autenticação, autorização, controle de acesso ou gerenciamento de sessão?

• Sim — descreva o que mudou e por quê:
• Não

Este PR introduz, atualiza ou remove dependências de terceiros?

• Sim — as novas dependências foram verificadas no SBOM/Trivy sem vulnerabilidades críticas/altas em aberto?
  • Verificado e aprovado
  • Pendente / vulnerabilidade aceita com justificativa:
• Não

Este PR foi validado pelo pipeline de segurança (SonarQube / Trivy)?

• Sim — link do job:
• Não aplicável a este PR (justifique): nenhuma dependência ou superfície externa foi adicionada; os commits foram verificados localmente pelo gitleaks e o pipeline do PR fará as demais verificações do repositório.

Este PR concatena, monta ou executa comandos SQL, HTML ou JavaScript a partir de entrada externa?

• Sim — confirme que há sanitização/parametrização (prepared statements, escaping, etc.):
• Não

Este PR expõe novos endpoints, telas ou serviços?

• Sim — HTTPS obrigatório está garantido e o acesso segue o princípio de menor privilégio?
• Não

Algum segredo, senha, chave ou token está sendo adicionado ao código-fonte?

• Não, nenhum segredo foi commitado
• Sim (bloquear merge e corrigir antes de prosseguir)