Braintrust

Braintrust is an AI evaluation and observability platform for experiments, spans, scores, and datasets. Respan’s Braintrust instrumentation registers as Braintrust’s background logger, translates Braintrust records into Respan’s tracing model, and sends them through the standard Respan OTLP pipeline.

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Setup

1

Install packages

$pip install respan-ai respan-instrumentation-braintrust braintrust
2

Set environment variables

$export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$export BRAINTRUST_API_KEY="YOUR_BRAINTRUST_API_KEY"

RESPAN_API_KEY exports traces to Respan. BRAINTRUST_API_KEY is used by Braintrust when you initialize a Braintrust project.

3

Initialize and run

1import braintrust
2from respan import Respan
3from respan_instrumentation_braintrust import BraintrustInstrumentor
4
5WORKFLOW_NAME = "Braintrust Support Evaluation"
6
7respan = Respan(
8 app_name="braintrust-support-eval",
9 instrumentations=[BraintrustInstrumentor()],
10)
11
12logger = braintrust.init_logger(
13 project="Support Evaluation",
14 async_flush=False,
15)
16
17try:
18 with respan.propagate_attributes(
19 group_identifier=WORKFLOW_NAME,
20 custom_identifier="support-eval-001",
21 metadata={"workflow_name": WORKFLOW_NAME, "framework": "braintrust"},
22 ):
23 with logger.start_span(name=f"{WORKFLOW_NAME}.workflow", type="eval") as root:
24 with root.start_span(name="draft_answer", type="llm") as span:
25 span.log(
26 input=[{
27 "role": "user",
28 "content": "Can I get a refund after 21 days?",
29 }],
30 output="Yes. Refunds are available within 30 days with a receipt.",
31 metadata={"model": "gpt-4o-mini"},
32 metrics={"prompt_tokens": 15, "completion_tokens": 16},
33 scores={"helpfulness": 0.95},
34 )
35
36 root.log(
37 input={"case_id": "case-1024"},
38 output={"decision": "eligible"},
39 metadata={"workflow_name": WORKFLOW_NAME},
40 )
41
42 logger.flush()
43finally:
44 respan.flush()
45 respan.shutdown()
4

View your trace

Open the Traces page to see your Braintrust workflow, child spans, scores, token usage, and metadata.

Workflow names

For traces that are easy to find in Respan, use a readable root span name and propagate the same workflow name:

1WORKFLOW_NAME = "Braintrust Scored Evaluation Workflow"
2
3with respan.propagate_attributes(
4 group_identifier=WORKFLOW_NAME,
5 metadata={"workflow_name": WORKFLOW_NAME},
6):
7 with logger.start_span(name=f"{WORKFLOW_NAME}.workflow", type="eval") as root:
8 ...

The instrumentation maps that value to trace_group_identifier and span_workflow_name, so root and child spans are recognizable by workflow name.

Span mapping

Braintrust span typeRespan log type
llm, chatchat
tool, functiontool
eval, automationworkflow
task, score, facet, preprocessortask

LLM spans include prompt messages, completion messages, model, and token usage when those fields are present in the Braintrust record.

Configuration

ParameterTypeDefaultDescription
instrumentationslist[]Pass [BraintrustInstrumentor()] to activate Braintrust tracing.
api_keystr | NoneNoneRespan API key. Falls back to RESPAN_API_KEY.
base_urlstr | NoneNoneRespan base URL. Falls back to RESPAN_BASE_URL.
customer_identifierstr | NoneNoneDefault customer identifier for all Braintrust spans.
metadatadict | NoneNoneDefault metadata attached to all spans.
environmentstr | NoneNoneEnvironment tag, such as "production".

Notes

  • BraintrustInstrumentor captures Braintrust records when they are logged and exports them when Braintrust flushes.
  • Use logger.flush() before respan.flush() so buffered Braintrust spans reach the Respan pipeline.
  • The older respan-exporter-braintrust package sends legacy payloads directly. Use respan-instrumentation-braintrust for the current tracing pipeline.