Skip to main content

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.

Applies to:
  • Plan -
  • Deployment -

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