Create a root span with client-generated conversation IDs

Applies to:

Plan - Any
Deployment - Any
Use case - Grouping multi-turn conversation spans under a single trace using client-generated UUIDs while retaining root-span UI features like the Playground button

Configuration steps

Step 1: Understand the impact of a missing root span

When parentSpanIds references a UUID that has no corresponding logged span, Braintrust still groups child spans by root_span_id. However, the following features require a real root span row:

+ Playground button

Root-span scoring and automation targets

Trace-level input, output, metadata, and tags display

Filters and custom columns that reference root-span fields

Step 2: Create a lightweight root span with a client-generated UUID

Log a root span first using spanId set to your pre-generated UUID. Then pass that UUID as both rootSpanId and spanId in parentSpanIds for all child spans.

const conversationTraceId = crypto.randomUUID();

// Log the root span
await logger.traced(
  async (span) => {
    span.log({ metadata: { conversationTraceId } });
  },
  {
    name: "conversation",
    spanId: conversationTraceId,
  }
);

// Log child spans referencing the root
await logger.traced(
  async (span) => {
    // message handling logic
  },
  {
    parentSpanIds: {
      rootSpanId: conversationTraceId,
      spanId: conversationTraceId,
    },
  }
);

This preserves a stable, human-readable conversation ID while giving Braintrust a real root row to attach UI features to.

All troubleshooting guides

Create a root span with client-generated conversation IDs

Summary

Configuration steps

Step 1: Understand the impact of a missing root span

Step 2: Create a lightweight root span with a client-generated UUID

​Summary

​Configuration steps

​Step 1: Understand the impact of a missing root span

​Step 2: Create a lightweight root span with a client-generated UUID

Summary

Configuration steps

Step 1: Understand the impact of a missing root span

Step 2: Create a lightweight root span with a client-generated UUID