RFC: Trace attribution & lookup — dimensions, Session/Message mapping, nested parent stitching

[susheem-k]

Context

When an agent fails in production, a developer needs to look up the right Chronicle trace from product context (user, session, message, feedback). Today Chronicle records a Trace as an ordered set of Envelopes with linear parent_envelope_id linkage and runtime-only ChronicleSession — there is no first-class product attribution surface for filtering, multi-turn message→trace mapping, or true nested agent/waterfall stitching.

Whiteboard framing (growth/design session):

• Indexing for filtering: how does a user look up traces?
• Trace 1:N Envelope; both need dimensions (Map<string,string>)
• Multi-turn: Session → Messages → each Message drives one agent graph run → one Chronicle TraceID
• Session→Message mapping is not Chronicle’s job; MessageID→TraceID (and SessionID-only for S2S) is
• Nested agents: child runs (e.g. Researcher) must attribute under the parent tool call / span (Orchestrator), not a flat chain

Problem

1. Lookup / filtering — No stable, queryable dimension taxonomy on Trace (and optionally Envelope). ContextMetadata.extra exists but is unstructured and not an indexing contract. Stores index mainly by trace_id / sequence.

2. Product ID ↔ Chronicle ID — No mandated way to attach:

   • session_id (mandatory for product correlation)
   • message_id (optional; multi-turn)
   • caller_id / caller_type (optional; S2S / cross-agent)
     Feedback / “thumbs down at time X” needs MessageID (or SessionID) → TraceID without Chronicle owning the session store.

3. Nested attribution — record_envelope parents to _last_envelope_id (linear chain). _envelope_stack / current_parent_id() exist but are unused for nesting. Parallel / nested tool→sub-agent graphs cannot rebuild a waterfall (TRACE > SPAN > RUN).

Goals

• Define where dimensions live (Trace-level vs Envelope-level) and a minimal schema for product correlation.
• Define the attribution contract:
  • Multi-turn: session_id + message_id → one trace_id per message turn
  • S2S / single-shot: session_id (and optional caller fields) alone
• Stitch child envelopes to true parents so nested agent runs attribute under the invoking tool/LLM boundary (waterfall-ready graph).
• Keep Chronicle a record/replay library — not a full tracing UI — but make production lookup and OTel/export nesting sound.

Non-goals

• Owning Session↔Message storage or chat history
• Building a full observability dashboard
• Changing Layer-2 judge rubrics / feedback semantics

Proposed direction (open for debate)

1. Dimensions

   • Trace-level: session_id (required when set by caller), optional message_id, caller_id, caller_type, plus free-form dimensions
   • Envelope-level: optional override/tags for filtering within a run
   • Pass via record() / session begin args (and/or first envelope), not inferred from chat state

2. Parent stitching

   • Use nest stack (_push_envelope / _pop_envelope) so parent_envelope_id = current_parent_id() instead of last-written
   • Document parallel-tool semantics (multiple children under one parent)

3. Lookup POC

   • Store/API: filter traces by session_id and/or message_id (+ dimensions)
   • Document “tightly coupled feedback → resolve MessageID → TraceID”

Acceptance criteria

• Written RFC section: Trace vs Envelope metadata placement + dimension keys
• Working POC: attach session_id/message_id at record time; query by them
• Nested parent attribution: child agent boundaries parent under the invoking envelope (test covering Orchestrator tool → Researcher sub-run)
• Waterfall/graph export (ExecutionGraph / OTel) reflects nest parents, not only linear sequence
• Docs: multi-turn vs S2S attribution patterns + what Chronicle does not own
• (Follow-up) Blog/notes on attribution strategies for production failure lookup

Related

• chronicle/session.py (_last_envelope_id vs unused _envelope_stack)
• chronicle/envelope/schema.py (ContextMetadata, parent_envelope_id)
• chronicle/execution_graph.py, chronicle/otel.py
• Paper limitations: parallel nesting not represented
• Open: LangGraph: auto-instrument a compiled graph and capture routing decisions #22 (LangGraph auto-instrument), RFC: Chronicle depends on shared control plane; TokenOps stays above Chronicle #30 (control plane RFC)

[susheem-k]

Design decisions (locked)

Dims = flat metadata

dims: dict[str, str] on both Trace and Envelope. Same shape; different meaning by level.

Level	Role	Examples
Trace dims	Universal for the run	user_id, session_id, message_id, env, run start time
Envelope dims	Span-specific	model_version, tool name, node tags

Not nested objects — a flat string→string map end to end. Can be surfaced as OTel attributes on export.

Storage for this work

Files only (JSONL / fixture export). Do not add SQL indexes in this RFC.

Note: SqliteStore and the control-plane example already exist as optional backends; they are out of scope here. Lookup POC = scan/filter JSONL (or in-memory recorded envelopes).

OTel Trace / Span mapping

OTel	Chronicle (runtime)	On disk / export
Trace	One run (trace_id)	Trace + shared trace_id
Span	One Envelope (boundary crossing)	Span record
Attributes	Trace/envelope dims	Flat string map

Internally keep “envelope”; persisted/exported shape should read as trace + spans.

OTel parent→child (what we implement)

1. Shared trace_id for the whole run.
2. Each span has span_id (envelope_id); non-root sets parent_span_id (= parent_envelope_id).
3. Parent comes from active Context / call stack at span start — not “last finished span.”
4. Export rebuilds the tree from (trace_id, span_id, parent_span_id).

Implementation fix: push parent onto the nest stack before the boundary body runs; pop after record. parent_envelope_id = current_parent_id().

Orchestrator LLM (open)
  └─ tool (open)
       └─ Researcher LLM   parent = tool
  tool ends
Orchestrator ends