Normaliza métricas de uso e organiza índices do OpenSearch

[pitangainnovare]

O que esse PR faz?

Reestrutura o armazenamento das métricas de uso no OpenSearch para reduzir a duplicação de dados e manter consultas eficientes:

• normaliza os fatos mensais COUNTER, preservando métricas diárias, totais e únicas;
• cria a projeção analítica anual por país e idioma;
• separa metadados de fontes e documentos em índices próprios, sincronizados incrementalmente por outbox;
• introduz aliases estáveis e rollover por tamanho;
• permite que coleções maiores usem aliases de escrita separados por ano, mantendo um alias global de leitura;
• mantém coleções menores em índices contínuos com rollover;
• usa a data validada do log para selecionar a fronteira anual;
• configura quantidade de shards e estratégia de particionamento por coleção no Wagtail;
• atualiza scielo_log_validator para 2.0.3, scielo_usage_counter para 2.2.2 e a versão do usage para 2.4.0.

As migrations incluídas são exclusivamente de esquema. O povoamento das políticas por coleção permanece no mecanismo de seed da aplicação.

Onde a revisão poderia começar?

A revisão pode começar por:

1. metrics/opensearch/mappings.py, que define os novos fatos e índices de metadados;
2. metrics/counter/indexing/converter.py e metrics/counter/indexing/engines/, que fazem a conversão;
3. metrics/services/export.py e metrics/opensearch/client.py, que implementam roteamento, aliases, idempotência e rollover;
4. metrics/services/metadata_sync.py, metrics/signals.py e metrics/models.py, responsáveis pela sincronização incremental de metadados;
5. log_manager_config/models.py e config/collections.py, que definem as políticas por coleção.

Como este poderia ser testado manualmente?

1. Atualizar a aplicação e executar:

python manage.py migrate

2. Recarregar as configurações das coleções pelo mecanismo de seed já utilizado pelo projeto.

3. Usar um prefixo isolado em OPENSEARCH_INDEX_NAME e processar um log validado de uma coleção pequena, como Books.

4. Confirmar a criação do alias e do primeiro índice físico:

usage_monthly_books
usage_monthly_books-000001
usage_yearly_analytics_books
usage_yearly_analytics_books-000001

5. Reprocessar o mesmo dia e confirmar que as métricas não são duplicadas.

6. Para uma coleção com estratégia anual, confirmar que datas em 2025 e 2026 são direcionadas a aliases de escrita distintos, mantendo o mesmo alias global de leitura.

7. Configurar temporariamente um limite de rollover pequeno, inserir dados suficientes e confirmar que documentos existentes continuam no índice físico original enquanto documentos novos seguem para a geração seguinte.

Validações executadas nesta branch:

• suíte completa: 236 testes passaram e 2 foram ignorados;
• black --check: 43 arquivos verificados;
• flake8: sem erros;
• python manage.py makemigrations --check --dry-run: nenhuma mudança pendente;
• teste com o log Books de 06/05/2026 e metadados reais: 24.066 fatos mensais e 67.441 fatos analíticos, com os mesmos totais do código-base quando utilizadas as mesmas bibliotecas;
• duas exportações consecutivas no OpenSearch isolado mantiveram os mesmos totais;
• rollover real de -000001 para -000002, atualização de documento no índice físico original e criação de documento novo na geração atual;
• fronteira anual real entre 2025 e 2026 no OpenSearch isolado.

Algum cenário de contexto que queira dar?

Os índices anteriores repetiam metadados e dimensões em grande volume, especialmente para SCL. Além do custo de armazenamento, isso dificultava consultas por período, país, idioma, coleção, periódico e área temática. A nova organização mantém fatos compactos e referencia metadados por chaves estáveis.

Para coleções grandes, a separação anual evita índices excessivamente extensos sem impedir rollover antes do fim do ano. Para coleções menores, índices contínuos evitam fragmentação desnecessária. O limite padrão permanece configurável e inicia em 50 GB, com uma réplica igual a zero e um shard primário por padrão.

Screenshots

Não aplicável. A alteração afeta o pipeline e a estrutura dos índices, sem mudanças visuais.

Quais são os tickets relevantes?

Não há ticket diretamente associado a este PR.

Referências

• Project COUNTER Code of Practice Release 5.1;
• documentação de aliases, rollover e Bulk API do OpenSearch.

---

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

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

• Sim — o pipeline lê logs de acesso, mas não persiste IP, sessão ou User-Agent nos novos índices. São gravadas somente métricas agregadas e dimensões necessárias, como país e idioma.
• 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 — atualiza duas bibliotecas SciELO mantidas pela organização.
  • Verificado e aprovado
  • Pendente — a verificação do SBOM/Trivy deverá ser confirmada pelo pipeline do PR.
• Não

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

• Sim — link do job:
• Não aplicável nesta etapa — a validação automatizada será executada após a abertura do PR.

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)