Append conversation to single trace

Summary

Goal: Continuously log conversations to a single trace for thread view

Configuration Steps

To update a trace after the fact, you must be able to call export() on the original parent span. This exported context allows new spans to be attached to the same trace later.

For background and implementation examples, see:

https://www.braintrust.dev/docs/instrument/advanced-tracing#trace-distributed-systems

Step 1: Export the Parent Span

When creating the root span for a trace, ensure that you export it and persist the exported context somewhere accessible to downstream processes or services.

This exported parent span is the anchor that allows additional spans to be added later.

Step 2: Attach New Spans to the Existing Trace

At any point after the original trace has started—potentially in another service or process—you can import the exported parent span and create new spans under it.

As long as all spans reference the same root span, they will be grouped into a single trace.

Step 3: Leverage Trace-Level Features

By attaching all related spans to one trace, you unlock several platform features:

• Automatic span colocation

  Conversation spans are colocated in Brainstore, improving performance when querying or rendering traces.

• Trace-level scoring

  Braintrust supports trace-level scoring. Any spans added to the trace are available to trace scorers, including an upcoming get_thread() method that pulls rendered thread information directly into the scorer.

• Custom trace views

  A single, unified trace enables highly customizable visualizations tailored to your application’s workflow.

Considerations

This approach requires an additional implementation step: all spans must be explicitly logged to the same root span. While this adds some complexity, it enables richer trace analysis and visualization.