Skip to main content

Traces

The Traces component runs in the casa-runtime namespace. It records all domain events generated by the runtime — token issuances, exchanges, tool check decisions — and correlates them with eBPF flow data from the kernel layer.

Responsibilities​

  • State persistence — stores trace records in PostgreSQL, keyed by MAS ID and user session
  • eBPF instrumentation — receives JWT/flow events forwarded from the eBPF layer and correlates them with token metadata
  • Query API — exposes trace data via the /trace REST endpoint, consumed by the Explorer UI

Architecture position​

Traces sits between the eBPF enforcement layer and the Explorer UI:

eBPF Layer  ──►  Traces  ──►  PostgreSQL
                    ▲
            Auth Service (writes events on token operations)
                    ▼
            Explorer UI (reads for display)

Data stored​

Each trace record captures:

  • Event type (token issuance, exchange, introspection, tool check)
  • Token hash (SHA256 — never the raw token)
  • MAS ID and agent identity
  • Tool name and check outcome (ALLOW / BLOCK / ABSTAIN)
  • Timestamp and correlation IDs

eBPF correlation​

eBPF programs extract JWT hashes from HTTP Authorization headers at the kernel level. Traces receives these flow events and correlates them with the token records stored by the Auth Service, enabling cross-layer observability without logging raw tokens.

See eBPF Enforcement for how flow events are generated.