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: Understand which spans appear in the trace Thread view and how the preprocessor selection affects extraction.

​
Thread view preprocessor modes

The Thread tab’s preprocessor picker controls how spans become a conversation:
  • None (default): The Thread view walks the trace and shows the root span, LLM-typed spans, and facet-typed spans inline. Score-typed spans render in a separate block. No preprocessor function runs and no cross-span deduplication happens.
  • Thread: The built-in Thread preprocessor runs across every non-scorer span in the trace, extracts messages from input and output, and deduplicates across spans. This is the same preprocessor Topics uses by default.
  • Custom preprocessor: A saved JavaScript function runs on each span and returns the message array the Thread view renders. See Write a custom preprocessor.

​
Span type attribution (None mode)

To make a span appear in None mode, set span_attributes.type to "llm" or "facet": 
import braintrust

with braintrust.start_span(span_attributes={"type": "llm"}):
    result = client.chat.completions.create(...)
Score-typed spans (type="score") render in a separate scorer block, not inline with the conversation.

​
Format requirements

Both modes extract messages from each span’s input and output. The fields must match a recognized shape: OpenAI-style role/content arrays, single message objects, content-parts arrays, plain strings, provider payloads (OpenAI, Anthropic, Google Gemini, Bedrock), framework formats (Vercel AI SDK, Pydantic AI, LangChain), or one of the wrapper keys messages, prompt, input, output, choices, result, response. For the full list and how to adapt traces that don’t render, see When traces don’t work.

​
Custom trace views

For span selection beyond what preprocessors can do, build a custom trace view. Custom views receive the full trace JSON and can extract fields from any span.