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

# Create a root span with client-generated conversation IDs

> [!NOTE]
>
> **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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.