Add to dataset captures root span only

Applies to:

Plan - Any
Deployment - Braintrust-hosted, Self-hosted
Use case - Adding full traces to datasets via UI

Summary

The Add to dataset action adds the span you selected, not every span in the trace tree. Which approach you need depends on the row shape you want:

To capture the whole trace as a single dataset row, use Add full trace to dataset from project logs. The row’s input stores a reference to the trace rather than a copy of its spans.

To create one dataset row per span, insert the spans with the SDK, carrying span_id, root_span_id, and span_parents in each row’s metadata.

Resolution steps

Option 1: Add the full trace by reference

Go to Logs and select the trace or span.

Click Add to > Add full trace to dataset, then choose the dataset.

Braintrust creates one row per trace, so selecting several spans from the same trace does not produce duplicate rows. The row renders with the read-only Trace viewer, which shows the trace’s metrics, input, and output inline.

Because the row holds a reference rather than a copy, it depends on the trace remaining available. If the trace is deleted or ages out of your retention window, the row shows Referenced trace not found. For details, see Promote traces from logs.

Option 2: Add one row per span programmatically

Use this approach when you need each span to become its own dataset row.

Step 1: Initialize dataset

Import the SDK and initialize your target dataset.

from braintrust import init_dataset

dataset = init_dataset(project="project-name", name="dataset-name")

Step 2: Insert all spans with trace metadata

Iterate through each span in the trace and insert it with span_id, root_span_id, and span_parents fields.

for span in trace_spans:
    dataset.insert(
        input=span.input,
        expected=span.expected,
        metadata={
            "span_id": span.id,
            "root_span_id": trace_root_id,
            "span_parents": span.parent_ids
        }
    )

​Summary

​Resolution steps

​Option 1: Add the full trace by reference

​Option 2: Add one row per span programmatically

​Step 1: Initialize dataset

​Step 2: Insert all spans with trace metadata

Summary

Resolution steps

Option 1: Add the full trace by reference

Option 2: Add one row per span programmatically

Step 1: Initialize dataset

Step 2: Insert all spans with trace metadata