> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a root span with client-generated conversation IDs

export const plans_0 = "Any"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = "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"

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

## Summary

**Goal:** Create a real root span with a client-generated UUID so child spans are grouped correctly and root-only UI features remain available.

**Features:** `logger.traced()`, `parentSpanIds`, `spanId`, `rootSpanId`

## 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.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.