Estatísticas (Pulse)

"Pulse" é o retrato agregado em tempo real de uma definição de processo — quantas instâncias estão ativas, quantas falharam, e o mesmo detalhamento por nó do diagrama. É a base de dashboards/monitores; para a técnica completa de montar telas com esses dados, veja o Guia de Integração do Monitor.

Operação	Endpoint
Snapshot de uma definição	GET /pulse/process-definition/{processDefinitionId}/snapshot
Stream (SSE) do mesmo snapshot	GET /pulse/process-definition/{processDefinitionId}/snapshot/stream

Ambos requerem QueryRepository. O snapshot não tem flag de opt-in própria — fica disponível sempre que houver QueryRepository no contexto. O stream é controlado por kikwiflow.pulse.sse-endpoints.enabled (default true):

kikwiflow:
  pulse:
    sse-endpoints:
      enabled: true   # default — desligue para remover só o endpoint /stream, mantendo o snapshot avulso
      interval: 5000  # ms entre reenvios enquanto a conexão SSE estiver aberta

Snapshot

GET /pulse/process-definition/{processDefinitionId}/snapshot

processDefinitionId é o id de uma versão específica (o mesmo de GET /process-definitions/{id}). 404 (NOT_FOUND) se não existir.

Resposta 200 OK (KKFProcessStats):

{
  "id": "fc451f6f-a944-4dbb-b2ba-b5fb6433f40a",
  "key": "intermediacao-veiculos",
  "name": "Intermediação de Veículos",
  "description": "",
  "sla": "",
  "checksum": "a1b2c3...",
  "metrics": { "running": 42, "sla": 100.0, "fail": 3 },
  "defaultStartPoint": "INICIO",
  "extensionProperties": {},
  "flowNodes": {
    "AGUARDANDO_CONTATO": {
      "type": "EXTERNAL_TASK",
      "id": "AGUARDANDO_CONTATO",
      "name": "Aguardando contato do vendedor",
      "metrics": { "running": 18, "sla": 100.0, "fail": 2 }
    },
    "GATEWAY_APROVACAO": {
      "type": "EXCLUSIVE_GATEWAY",
      "id": "GATEWAY_APROVACAO",
      "metrics": null
    }
  }
}

metrics (macro, topo do objeto)

Campo	Significado
running	Instâncias com status: ACTIVE agora — não é o total histórico. Para o total histórico (inclui COMPLETED/CANCELLED), use GET /process-instances/count.
fail	Incidentes com status: OPEN agora, para essa definição.
sla	Sempre 100.0, hardcoded — StatsService ainda não calcula SLA real. Não use para nada além de um placeholder visual.

flowNodes[nodeId].metrics (por nó)

Preenchido só para os cinco tipos de nó materializados como ExecutableTask/ExternalTask, onde "quantas instâncias estão paradas aqui" é um conceito que existe: EXECUTABLE_TASK, EXTERNAL_TASK, EVENT_CATCHER, CALL_ACTIVITY_COORDINATOR e TIMER_TASK. Para os demais tipos (gateways, boundary events, start/end events), metrics vem sempre null — não é um bug, é que não existe "fila" nesses tipos de nó. Onde preenchido:

• running — ExecutableTask/ExternalTask ativas naquele taskDefinitionId agora.
• fail — as que estão com ExecutableTaskStatus.ERROR.
• sla — mesmo placeholder fixo 100.0 do nível macro.

O type de cada entrada de flowNodes é o discriminador polimórfico — usa o mesmo catálogo de tipos de nó de Anatomia de um Processo, e determina quais campos extras esperar (ex.: iterationMode em CALL_ACTIVITY_COORDINATOR, catchType/matchPolicy em EVENT_CATCHER).

Stream (SSE)

GET /pulse/process-definition/{processDefinitionId}/snapshot/stream

Abre uma conexão Server-Sent Events (text/event-stream) que reenvia o mesmo KKFProcessStats a cada kikwiflow.pulse.sse-endpoints.interval (default 5000ms) enquanto a conexão estiver aberta — troque polling manual por só manter a conexão viva e atualizar a UI a cada evento recebido.

Detalhe de implementação relevante para dimensionar carga: existe um único loop de polling por processDefinitionId, compartilhado entre todos os assinantes conectados àquela definição — abrir 50 abas olhando o mesmo processo não gera 50 consultas ao repositório a cada intervalo, gera uma. O loop nasce quando o primeiro assinante conecta e é cancelado quando o último desconecta (onCompletion/onTimeout/onError).