Coleta e Métricas de Eventos

A Coleta de Eventos e Métricas é o mecanismo da plataforma responsável por registrar, empacotar e consolidadar os dados de telemetria de cada transação, sessão e execução atômica de motor (runner).

Projetado para operar de forma totalmente não-bloqueante, o subsistema de telemetria utiliza o envio assíncrono de eventos para garantir rastreabilidade em tempo real e monitoramento de performance sem adicionar latência ao tempo de resposta do cliente.

Arquitetura de Coleta Assíncrona

A captura de dados estatísticos é executada em segundo plano pela Engine ao término do processamento de cada etapa. A classe base de orquestração constrói a estrutura de métricas e delega o envio para o serviço especializado de coleta (ServicoColetorEstatisticaDeExecucaoDeMotor):

┌────────────────────────────────────────────────────────────────────────┐
│                     CICLO DE PROCESSAMENTO (ENGINE)                    │
│   1. Executa a Etapa (Motor Core ou Plugin)                            │
│   2. Consolida Tempo em ms, Status, Sessão e Interrupções              │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼ (finally / managedExecutor.runAsync)
┌────────────────────────────────────────────────────────────────────────┐
│       SERVIÇO COLETOR DE ESTATÍSTICAS (ExecucaoDeMotorStats)           │
│   - Captura modelo da etapa (Fluxo, Versão, Tag, CoEtapa)              │
│   - Captura contexto de sessão (idSessao, idTransacao, idExecucao)     │
│   - Grava tempos de execução e extras de telemetria                    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   BANCO DE ESTATÍSTICAS / ARMAZENAMENTO                │
│             (Agregação de métricas para dashboards e consultas)        │
└────────────────────────────────────────────────────────────────────────┘

Estrutura do Evento de Telemetria (`ExecucaoDeMotorStats`)

Para cada nó processado no diagrama visual, um registro de execução de motor é gerado contendo métricas essenciais de observabilidade:

1. Identificadores de Execução e Rastreabilidade

idExecucaoDeMotor: Identificador único gerado via chave aleatória (UniqueKey) para correlacionar a chamada específica no log de rastreabilidade.
sessao: Objeto com metadados do ciclo de vida da chamada (idSessao, idTransacao, identificador do fluxo e da versão ativa).

2. Metadados do Modelo e Motor

modelo: Informações sobre o nó executado, incluindo o código da etapa (coEtapa), o nome amigável (alias) e o tipo do motor acionado (motor).
sucesso: Indicador booleano sinalizando se a etapa foi concluída com sucesso (TRUE) ou se sofreu interrupção por exceção (FALSE).

3. Métricas de Performance e Tempo

tempo: Duração exata do processamento da etapa em milissegundos, calculado entre a entrada no método e o encerramento do runner.
sessaoInterrupcao: Registra o carimbo de data/hora (timestamp) de encerramento prematuro caso o fluxo tenha sido interrompido durante aquela etapa.

4. Atributos Extras e Detalhes

extras: Mapa de metadados customizados devolvido especificamente por runners de integração (ex: códigos de status HTTP externos, tamanho de payloads trafegados ou quantidade de linhas afetadas no banco de dados).
erro: Em caso de falha, armazena o objeto estruturado de exceção extraído do container de erro.

Processamento Não-Bloqueante

A gravação de estatísticas é executada de forma assíncrona, operando em segundo plano e totalmente desacoplada do fluxo principal. Esse isolamento garante que eventuais oscilações ou falhas no banco de telemetria não impactem o tempo de resposta retornado ao cliente.

Identificadores e Rastreabilidade

idExecucaoDeMotor, sessao com idSessao, idTransacao, fluxo e versão ativa.

Modelo e Motor

modelo com coEtapa, alias e motor; sucesso indicando TRUE ou FALSE.

Performance e Tempo

tempo em milissegundos e sessaoInterrupcao com timestamp de encerramento prematuro.

Extras e Detalhes

extras com metadados customizados de integração e erro com o objeto estruturado de exceção.