Introduction
What we build:
A
TraceContextfactory that mints a globally-unique trace per user request and propagates it through every agent invocation via Python’sContextVar.A
@trace_stepdecorator that wraps any agent method, automatically capturing inputs, outputs, latency, token count, and decision metadata as a typedSpan.A dual-sink
AuditLogSinkpersisting spans to both SQLite (queryable) and JSONL (append-only, replay-safe).A
TraceQueryEnginethat reconstructs full waterfall timelines from trace IDs and supports diff/replay for debugging.A React dashboard with a waterfall view, risk heatmap, decision timeline, and live-tail stream.
Connection to L41: The
SynthesizerAgentwe built in L41 is the last node in our pipeline. Today, it becomes traceable — every CoT reasoning chain, every citation it emits, and the final confidence score all become queryable span attributes.
Enables L43: In the Agentic RAG end-to-end lesson, the traceability layer is the connective tissue. Without it, integration testing is blind. With it, every failed run becomes a replayable incident.
Dual-Sink Architecture
Spans are written to two sinks simultaneously:
SQLite — structured rows with indexed
trace_id,agent_name,risk_score. SupportsWHEREqueries and JOIN operations for post-hoc analysis.JSONL — append-only flat file, one JSON object per line. Immutable, regex-searchable, trivially shippable to S3/GCS. This is your compliance archive.
The sinks are written via an async queue — agents never block on storage I/O.
