04 — Observabilidade

OpenTelemetry. Sem reinventar a roda.

Spans, métricas e contexto W3C traceparent propagados pelos pods. Atributos SemConv para qualquer backend padrão. Custo monetário em séries temporais. Painel TUI ao vivo.

Hierarquia de spans

Do turno do usuário até cada commit.

O DEILE emite OpenTelemetry — não é log estruturado disfarçado. Os spans são hierárquicos e o contexto de trace W3C é propagado do pipeline para o worker, e do worker para cada operação git/forge. Sem segredos em atributos, com cardinalidade controlada.

pipeline.dispatch_request           ← origem (pipeline pod)
   │
   └─► deile.dispatch                  ← filho via W3C traceparent (worker pod)
        │
        ├─ deile.turn                   ← 1 por interação do agente
        │   ├─ deile.llm.call           ← 1 por chamada de provider
        │   ├─ deile.tool.<name>      ← 1 por execução de tool
        │   └─ deile.tool.<name>      ← (várias por turno)
        │
        ├─ git.commit                   ← atributos vcs.* SemConv dual-emit
        ├─ git.push
        ├─ forge.pr_open
        └─ forge.pr_review

W3C traceparent

O pipeline injeta o header; o worker continua o trace. Um único trace cobre todo o ciclo dispatch → commit.

SemConv dual-emit

Spans git.* e forge.* emitem atributos canônicos vcs.* além de custom, para entrar em qualquer backend padrão.

redação no exporter

Tokens GitHub/GitLab são redigidos automaticamente. session_id NÃO é label de métrica (cardinalidade).

Métricas CNCF

Onze métricas. Labels com cardinalidade fechada.

As métricas seguem o vocabulário OTel. Labels são enums fechadas (provider, tool name, stage) — nada de session_id, task_id ou hashes que explodam a série temporal.

por turno / tool

deile.turn.duration_ms	histogram	latência total do turno
deile.tokens.total	counter	tokens consumidos (entrada + saída)
deile.cost.usd.total	counter	custo monetário acumulado
deile.tool.duration_ms	histogram	latência por execução de tool
deile.errors.total	counter	erros por tipo (tipo é label fechado)

por dispatch / forge

deile.dispatch.total	counter	dispatches emitidos pelo pipeline
deile.dispatch.failed.total	counter	dispatches falhados
deile.dispatch.duration_ms	histogram	tempo de execução do dispatch
deile.dispatch.tool_burst.total	counter	rajadas de tool dentro de um dispatch
deile.forge.pr_review.total	counter	reviews de PR enviadas
deile.git.push.total	counter	pushes para o forge

Runtime registry

Cada processo publica seu próprio estado. O painel só lê.

Em vez de inferir o que cada processo está fazendo via log-tailing, o DEILE introduziu uma camada de runtime: cada processo grava um arquivo de estado JSON com heartbeat, expõe um socket UNIX para consulta direta, e o painel reúne tudo via um registry compartilhado protegido por flock POSIX.

state file

Snapshot atômico

Cada processo grava em ~/.deile/run/<id>.json com escrita atômica e heartbeat a cada 2 s. Sem secrets, sem tool_args, sem prompts — só ação corrente, métricas acumuladas e contadores.

status server

Unix socket por processo

Protocolo simples (STATUS / METRICS / FLUSH) sobre Unix socket com chmod 0600. O painel prefere o socket — estado mais fresco que o último flush em disco.

fleet registry

Visão de frota

Um registry.json compartilhado, com lock POSIX, lista todos os processos vivos. GC inline limpa PIDs mortos ou state files ausentes. Funciona local e remoto.

Cost ledger

Sua conta em USD não evapora junto com o pod.

Cada dispatch do claude-worker e da frota multi-CLI é registrado em duas vias: empurrado para o repositório central de uso (SQLite, longo prazo) e copiado para um JSONL no PVC do próprio worker. Quando o painel pergunta o custo, ele lê o central primeiro; se faltar, complementa com o JSONL.

dispatch concluído
   │
   ├─► push estruturado p/ UsageRepository (SQLite central)
   │       │
   │       └─ persiste mesmo com scale-to-zero / force-delete do worker
   │
   └─► harvest p/ cost-ledger.jsonl (PVC do worker)
           │
           └─ antes de qualquer prune de transcripts antigos
              (incidente real ensinou: nunca pode-se podar sem colher)

painel [T]kens
   ├─ lê do central primeiro
   ├─ se ausente, completa do JSONL
   └─ dedup por task_id

Painel TUI

Observabilidade navegável por teclado.

O painel é o substituto vivo do log-tailing. Lê o status server do pipeline, os endpoints estruturados de cada worker e o runtime registry. Cada view tem uma responsabilidade única e re-renderiza adaptando-se ao tamanho do terminal.

atalhos

1-4 navegar views

[d] matriz de despacho (workers × modelos × esforço)

[t] auditoria de tokens das sessões claude

[T] leitura do cost ledger central + JSONL

[M] vista do monitor e perguntas read-only

[L] alternar login OAuth do worker

[I] instalar worker da frota ausente

[s] escalar replicas (incluindo scale-to-zero)

[c] cleanup de workdirs órfãos (com confirmação)

[?] ajuda contextual

[q] sair