Histórico Completo de Execuções

"A triagem de ontem terminou? Quantos deram erro? Quem disparou?" — sem um histórico durável, responder exige caçar registros técnicos. O DATTA consolida todas as tarefas de fundo (uploads, regras, ETL, streams, triagem) em um painel único de acompanhamento ao vivo e em um histórico permanente com filtro por período, que sobrevive a reinícios e atualizações da plataforma. Você audita o que já rodou, quando, por quem e com que resultado — em segundos.

Este guia complementa o painel de execuções em segundo plano, que descreve o painel lateral e o trecho "Histórico (últimas 10)" do ponto de vista do usuário final. Aqui o foco é a camada durável, o filtro por período e a operação pela própria interface.

Dois níveis de histórico

O painel "Execuções em segundo plano" mistura dados de duas naturezas distintas, e entender a diferença evita sustos:

A seção "Histórico (últimas 10)" do painel lateral é apenas a janela mais recente do histórico durável. O histórico completo com filtro por período fica na página dedicada (screens/historico-execucoes.html), acessível a partir do próprio painel, pelo link de abrir o histórico completo ao lado de "Histórico (últimas 10)".

O que cada registro guarda

Cada execução terminal vira um documento no índice de sistema datta_bg_executions — regravar a mesma execução atualiza o registro em vez de duplicá-lo, porque a chave é o campo id.

Hoje o produtor já integrado é a triagem processual em lote, que grava o registro ao concluir, falhar ou ser cancelada — em melhor-esforço, com limite de 8 s, de modo que uma falha na gravação do histórico nunca derruba a triagem em si. Os demais tipos (uploads, regras, ETL, embeddings) entram no mesmo contrato à medida que são integrados.

A gravação é reservada a serviços internos da plataforma, autenticada servidor-a-servidor: o usuário comum nunca escreve no histórico diretamente, só lê. As duas operações (gravar registro terminal e ler o histórico) estão na referência de API, com as permissões SEARCH_EXECUTE (gravar) e SEARCH_VIEW (ler).

Filtro por período

A leitura do histórico aceita três parâmetros: início do intervalo, fim do intervalo (ambos em epoch ms, comparados contra finalizadoEm) e um limite de registros — 10 por padrão, com teto de 1000.

• Sem intervalo: retorna as últimas execuções, até o limite pedido.
• Com início e/ou fim: aplica a faixa sobre finalizadoEm.
• A ordenação é sempre da mais recente para a mais antiga.

A página de histórico traduz as datas escolhidas no seletor (aaaa-mm-dd) para epoch ms — o início no primeiro instante do dia (00:00:00) e o fim no último (23:59:59.999) — e consulta com limite de 500 registros.

A página de histórico completo

A página dedicada (screens/historico-execucoes.html) segue o design system da plataforma: variáveis de tema, dark/light e layout responsivo a partir de 768px. Na telemetria, ela aparece com o nome de serviço datta-fe-historico-execucoes.

• Filtros: dois campos de data com rótulo — Data início e Data fim — mais os botões Limpar, atualizar e Aplicar filtro.
• Tabela: Status (selo Concluída, Falhou ou Cancelada), Tipo, Execução (título + contexto), Quando, Total, OK, Erros e Detalhe (mensagem).
• Enquanto carrega: um spinner ocupa a área da tabela — nunca tela em branco.
• Sem dados: "Nenhuma execução encontrada", com o sufixo "no período selecionado" quando há filtro ativo.
• Erro tratado: se a consulta falha, você vê "Não foi possível carregar o histórico." com o botão Tentar novamente — nunca um código de erro cru nem detalhe técnico.
• Trilha de navegação: DATTA › Execuções em segundo plano, com o último elo não-clicável.

O índice datta_bg_executions é criado de forma preguiçosa, na primeira gravação. Enquanto nenhuma execução terminal tiver sido registrada, a consulta trata o índice ausente como histórico vazio — não como erro. O painel e a página mostram o estado vazio, não uma mensagem de falha.

Exemplo prático — auditar as triagens da semana

1. Abra o painel "Execuções em segundo plano" e entre no histórico completo.
2. Preencha Data início com a segunda-feira e Data fim com a sexta-feira da semana desejada.
3. Clique em Aplicar filtro.
4. A tabela lista cada triagem do período com status, contagens e mensagem — por exemplo, uma linha Concluída · triagem · "Triagem em lote — Processos" · 120 total · 118 OK · 2 erros.
5. Use o atalho da linha para reabrir a tela da execução e inspecionar os erros.

Tarefas órfãs se resolvem sozinhas

O estado vivo das ingestões e uploads (seção "Ingestões e uploads" do painel) vive no hub de tarefas, mas o processamento real roda em memória do módulo de documentos. Se esse módulo reinicia no meio de um lote (atualização, falta de memória, queda da máquina), o registro fica RUNNING no hub enquanto o trabalho já morreu — uma tarefa órfã: o painel mostra "Executando", mas nada está acontecendo.

O DATTA comunica essa morte no momento do reinício, sem esperar staleness nem o tempo de expiração de 24 h. São dois caminhos complementares:

1. Desligamento controlado (atualização normal): ao receber o sinal de encerramento, o módulo percorre os lotes em andamento, marca cada um como falho e cancela o processamento, dentro do período de graça — em melhor-esforço, com limite de 3 s por lote. A mensagem gravada é "Interrompida: serviço reiniciado durante o processamento."
2. Mortes abruptas (falta de memória, encerramento forçado, queda da máquina): ao subir de novo, a plataforma varre as tarefas que constavam como ativas, marca toda tarefa ainda RUNNING/QUEUED como Falhou e a remove da lista de ativas. Cobre os casos em que o desligamento controlado não chegou a rodar.

Desligamento controlado          Falta de memória / queda da máquina
        │                                   │
        ▼                                   ▼
lotes em andamento marcados         (não roda)
como falhos, ainda no ar                    │
        │                                   ▼
        └──────────────► reinício ──► varredura na subida
                                      marca as órfãs como Falhou
                                      e as tira da lista de ativas

Resultado: uma tarefa presa em "Executando" se resolve sozinha no próximo reinício — reenvie o lote e siga em frente.

Por que isso é seguro

A varredura de subida pressupõe que qualquer tarefa ativa numa instância recém-iniciada é comprovadamente órfã. Isso vale porque o módulo de documentos:

• roda em instância única, sem sobreposição — a instância antiga é encerrada antes de a nova subir; e
• é o único produtor do hub de tarefas (todas as tarefas de fundo de ingestão nascem nele).

Atenção operacional: se algum dia o módulo de documentos passar a rodar em várias instâncias simultâneas, adotar atualização com sobreposição, ou outro serviço começar a gravar tarefas no mesmo hub, a varredura de subida deixa de ser segura — ela mataria a tarefa de uma instância coexistente. Nesse cenário, a varredura precisa ser escopada por dono/instância antes de marcar qualquer coisa como órfã. Trate isso como pré-requisito bloqueante de qualquer mudança nesse perfil de execução.

Robustez de leitura do hub

A leitura do hub é defensiva de ponta a ponta: ignora chaves auxiliares (task:cancel:*), tolera registros corrompidos (um registro inválido é descartado em vez de derrubar a consulta) e ordena de forma tolerante a campos ausentes. Um único registro estranho não pode esconder todo o histórico de uploads do painel.

Operação pela interface

A operação de rotina do histórico não exige linha de comando nem acesso à infraestrutura:

• Ver o que está rodando: painel "Execuções em segundo plano", que recebe o estado vivo em tempo real (atualização a cada 5 s).
• Ver o histórico recente: seção "Histórico (últimas 10)" do painel.
• Auditar por período: página de histórico completo, com o filtro de datas.
• Tarefa presa em "Executando": NÃO é necessário intervir manualmente — o próximo reinício do módulo de documentos reconcilia a órfã como Falhou, pelos dois caminhos descritos acima.

Diagnóstico

Verificação rápida: uma consulta ao histórico pedindo 1 registro que volte vazia indica índice vazio ou ainda inexistente; se voltar com documentos, o histórico está ativo. O datta_bg_executions é um índice de sistema — guarda metadados de execução, não dados de contexto — e por isso entra no Knowledge Catalog como tal.

Referências cruzadas

• Painel de execuções em segundo plano — perspectiva do usuário final.
• Roles e permissões — catálogo de permissões e mapeamento em roles (SEARCH_EXECUTE, SEARCH_VIEW).
• Referência de API — leitura e gravação do histórico para integrações de auditoria.