Architecture¶

codexlb2otel is a stateful archive tailer. It does not proxy traffic and does not call codex-lb; the only coupling is the conversation-archive directory on disk.

codex-lb websocket archive
          │
          ▼
 gzip member reader ──► frame decoder ──► turn reducer
                                              │
                        ┌─────────────────────┼────────────────────┐
                        ▼                     ▼                    ▼
                   OTLP metrics          Loki records        Tempo traces
                        │                                          │
                        └──────── checkpointed cumulative state ───┘
                                              │
                                   live view / generations

Archive reader¶

codex-lb appends complete gzip members. The reader can resume at a compressed byte offset and resynchronize at member boundaries, so it does not have to inflate every earlier record after each poll. Chunked reads bound memory use while a file is growing.

Frame and turn reduction¶

The frame layer normalizes websocket and response events. The turn reducer then joins continuations, tool calls and outputs, usage updates, rate limits, errors, and parent-agent references into one logical turn. The CLI tools, live view, logs, metrics, and traces use the same reducer rather than maintaining separate interpretations of the archive.

Checkpoint contract¶

The checkpoint stores archive offsets plus cumulative reducer state. It does not contain prompt or message bodies, but its map keys include conversation identifiers. Atomic writes and a clean-shutdown save keep it recoverable; the configured checkpoint interval bounds duplicate replay after a hard crash.

Sink isolation¶

Each sink has its own queue, timeout, batching, and rejection counters. Permanent input or delivery failures are counted and dropped rather than blocking the checkpoint forever. Retryable transport failures use bounded retry.

Loki is intentionally native rather than OTLP logs because Loki stream labels and structured metadata are part of the query contract. Metrics and traces share the OTLP gateway. Agent Observability generations use their product-specific export endpoint.

Drift detection¶

clbprobe compares archives with corpus.sig.json, a content-free schema signature. A sampled pass is fast and detects common new shapes; only a full pass can establish that a rare shape disappeared or safely update the baseline.