Registro de rastreabilidade dos fluxos de trabalho

O registro de rastreabilidade dos fluxos de trabalho grava estado durável para automações longas. Ele responde perguntas operacionais que um log de console não responde de forma confiável:

• Qual execução está ativa?
• Quais itens estão em fila, em execução, concluídos, ignorados, prontos para nova tentativa, cancelados, com falha ou mortos?
• Qual item tem reserva de execução expirada?
• Qual histórico de eventos levou ao estado atual?
• Qual item de fila está vinculado a este item de fluxo de trabalho?
• Este item pode ser tentado novamente, recolocado na fila, cancelado ou movido para a fila de rejeitos?

Conceitos do registro

Conceito	Significado
Execução	Uma execução de um fluxo de trabalho, com status, origem, timestamps de início/fim, metadados e estado de erro
Item	Uma unidade durável de trabalho do fluxo, como portal, URL, documento ou registro
Estágio	A etapa do fluxo à qual o item pertence, como discovery, fetch, parse ou review
Estado	O status do item dentro do estágio, como queued, running, completed, retry-ready, dead ou cancelled
Evento	Entrada append-only de histórico explicando o que aconteceu com uma execução ou item
Saída vinculada	Saída ou referência vinculada, como instantâneo, listagem, arquivo ou documento de pesquisa
Reserva de execução	Reivindicação de um processo de trabalho que marca um item como em execução até um prazo

Estados e estágios são strings definidas pelo fluxo, não conceitos fixos do produto. O registro é genérico o suficiente para muitos fluxos de trabalho, enquanto cada fluxo pode fornecer metadados de exibição para tornar os itens legíveis.

Painel do registro

O painel do registro na janela principal é uma superfície compacta de status e abertura. Ele mostra contagens de execuções, contagens de itens, contagens que exigem atenção e uma lista curta de execuções.

O painel é intencionalmente leve. Use-o para verificar status e abrir o console completo.

Console do registro

O console do registro é a interface principal do operador. Ele abre em janela própria e usa painéis dedicados para execuções, itens da execução selecionada, detalhes do item, eventos, saídas vinculadas, metadados, estado de recuperação e visões de grafo/depuração.

O console serve para gerenciamento sério de execuções e recuperação de itens, não apenas para observar registros.

Use-o para:

• Gerenciar execuções e inspecionar o estado da execução selecionada.
• Pesquisar e filtrar itens por texto e status operacional.
• Paginar grandes conjuntos de itens sem carregar uma execução inteira na interface.
• Ler contagens de estágio/estado computadas sobre toda a execução selecionada, não apenas a página visível.
• Selecionar um ou muitos itens para nova tentativa, cancelamento, fila de rejeitos ou recuperação de fila.
• Inspecionar detalhes, IDs brutos, chaves de item, tentativas, estado da reserva de execução, erros e metadados.
• Seguir timelines de itens por eventos e saídas vinculadas.
• Ver se um item do registro tem metadados de fila suficientes para ser recolocado na fila.
• Copiar conteúdos, IDs e detalhes diagnósticos de itens.

Execuções grandes e paginação

O console foi projetado para execuções com milhares de itens. O painel Items usa paginação do lado do servidor com tamanhos de página limitados, enquanto resumos e a matriz estágio/estado usam consultas agregadas do repositório sobre toda a execução selecionada.

Essa distinção importa: virtualização controla apenas renderização; paginação e agregados controlam correção e carga do banco. Uma página pode mostrar 250 linhas, mas totais de execução, contagens de estágio/estado, contagens prontas para nova tentativa, contagens de reserva de execução e resumos de atenção vêm da verdade do repositório.

Filtros rápidos como Problems, Retry Ready, Running, Leased e Terminal são aplicados do lado do servidor à lista paginada de itens.

Vocabulário de retry

O Guida separa estado durável do registro de trabalho executável em fila:

• Mark Retry Ready altera o estado do registro para que o item possa ser reivindicado pela lógica do fluxo. Isso não cria trabalho de fila por si só.
• Requeue and Retry cria trabalho executável em fila quando o item do registro gravou metadados de fila, depois move o item do registro de volta para um estado reivindicável.

Se os metadados de fila estiverem ausentes, o Guida deve mostrar uma mensagem de recuperação voltada ao operador. A correção usual é regenerar o item reexecutando o processo de trabalho de origem ou enfileirando um item corrigido, não adivinhar o conteúdo antigo.

Vínculo com filas

Itens de fila podem incluir um envelope de fluxo:

{
  "workflow": {
    "workflowName": "careers-crawl",
    "runId": "abc123",
    "itemId": "def456",
    "itemKey": "portal:example"
  }
}

Quando esses metadados existem, o Queue Console pode abrir o item de registro relacionado, e o console do registro pode explicar se existe trabalho executável em fila para um item.

Metadados de exibição

Fluxos de trabalho podem definir apresentação de itens com workflow-ledger.display.json ao lado de workflow-ledger.schema.json. Regras de exibição permitem que um fluxo escolha rótulos, subtítulos e campos de contexto a partir de campos ou metadados do item sem codificar interface específica de domínio no Guida.

A chave bruta do item, ID do item, ID da execução, metadados, eventos e saídas vinculadas continuam disponíveis nos detalhes e ações de cópia mesmo quando um fluxo fornece rótulos amigáveis.

Atenção e recuperação

O console destaca atenção da execução selecionada, como:

• reservas de execução expiradas
• itens prontos para nova tentativa
• itens mortos ou com falha
• problemas de vínculo com filas
• itens que não podem ser recolocados na fila automaticamente

Atenção entre execuções pertence às visões de gerenciamento de execuções. A operação da execução selecionada deve permanecer no escopo dessa execução para que o operador não se distraia com falhas não relacionadas.

Reconciliação de execução

Ferramentas MCP do registro de rastreabilidade e a API do painel operacional incluem resumos compactos de reconciliação para uma execução selecionada. Eles ajudam em verificações de fluxo, como transferência de fetch para parse:

• contagens de fetch processado, ignorado, morto, pronto para nova tentativa, em execução e com reserva
• contagens de parse/index em fila e concluído
• contagens agrupadas completas por estágio/estado

Esses resumos servem para diagnóstico operacional e agentes remotos. Eles não substituem o console, mas dão a scripts e clientes MCP uma forma limitada de responder “para onde foi o trabalho?”

Para espaços de trabalho com muitos rastreadores, use o Workflow Control Console para agrupar estágios do registro, filas, módulos e passagens em operações no nível do operador. Use o console do registro quando precisar da verdade detalhada dos itens por trás de uma dessas linhas de operação.

Próximos passos

• Filas e revisão — opere trabalho executável em fila
• Processos de trabalho das filas — execute processos baseados em fila
• Workflow Control Console — modele operações, mapas de fluxo, módulos e passagens
• API do painel operacional — monitore contagens de execuções, filas, processos de trabalho, falhas, atenção e reconciliação por HTTP/SSE somente leitura
• Fluxos de trabalho — organize automação do espaço de trabalho em pastas de fluxo