Skip to main content

Braintrust exporter

Braintrust is an evaluation and monitoring platform that helps you measure and improve LLM application quality. The Braintrust exporter sends your traces to Braintrust, enabling systematic evaluation, scoring, and experimentation.

Installation
Direct link to Installation

npm install @mastra/braintrust@latest

Configuration
Direct link to Configuration

Prerequisites
Direct link to Prerequisites

  1. Braintrust Account: Sign up at braintrust.dev
  2. Project: Create or select a project for your traces
  3. API Key: Generate in Braintrust Settings → API Keys
  4. Environment Variables: Set your credentials:
.env
BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx

# Optional
BRAINTRUST_ENDPOINT=https://api.braintrust.dev  # Custom endpoint if needed

Zero-Config Setup
Direct link to Zero-Config Setup

With environment variables set, use the exporter with no configuration:

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { BraintrustExporter } from '@mastra/braintrust'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: 'my-service',
        exporters: [new BraintrustExporter()],
      },
    },
  }),
})

Explicit Configuration
Direct link to Explicit Configuration

You can also pass credentials directly (takes precedence over environment variables):

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { BraintrustExporter } from '@mastra/braintrust'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      braintrust: {
        serviceName: 'my-service',
        exporters: [
          new BraintrustExporter({
            apiKey: process.env.BRAINTRUST_API_KEY,
            projectName: 'my-project',
          }),
        ],
      },
    },
  }),
})

Complete Configuration
Direct link to Complete Configuration

new BraintrustExporter({
  // Required
  apiKey: process.env.BRAINTRUST_API_KEY!,

  // Optional settings
  projectName: 'my-project', // Default: 'mastra-tracing'
  endpoint: 'https://api.braintrust.dev', // Custom endpoint if needed
  logLevel: 'info', // Diagnostic logging: debug | info | warn | error
})

Attach traces to Braintrust evals
Direct link to Attach traces to Braintrust evals

Install the Braintrust SDK directly when your application uses Eval(), logger.traced(), or currentSpan:

npm install braintrust@latest

When you run Mastra inside Braintrust Eval() or logger.traced(), pass the Braintrust logger and currentSpan resolver to the exporter. Import currentSpan from the same braintrust package instance that creates the eval or traced span.

This helps Mastra attach its spans under the active Braintrust span when your app and @mastra/braintrust resolve different installed copies of the Braintrust SDK.

The exporter accepts compatible logger and span objects from Braintrust SDK v2 and v3. Your application's Braintrust SDK version doesn't need to match the version installed by @mastra/braintrust.

src/mastra/index.ts
import { currentSpan, initLogger } from 'braintrust'
import { BraintrustExporter } from '@mastra/braintrust'

const logger = initLogger({
  projectName: 'my-project',
  apiKey: process.env.BRAINTRUST_API_KEY,
})

const exporter = new BraintrustExporter({
  braintrustLogger: logger,
  currentSpan,
})

Use the configured Mastra instance inside the Braintrust eval task. The currentSpan resolver above reads the active span created by Eval().

src/evals/braintrust.ts
import { Eval } from 'braintrust'
import { mastra } from '../mastra'

await Eval('my-project', {
  data: () => [{ input: 'Say hello', expected: 'Hello' }],
  task: async input => {
    const agent = mastra.getAgent('assistant')
    return (await agent.generate(input)).text
  },
  scores: [],
})

If your application upgrades its direct Braintrust dependency from v2 to v3 and uses Nunjucks prompt templates, follow the Braintrust v2 to v3 migration guide.

Querying Braintrust with returned spanId
Direct link to querying-braintrust-with-returned-spanid

Mastra uses its returned spanId as both the Braintrust row ID and span ID. Use it to find the corresponding Braintrust span by id or span_id.

Braintrust v3 stores a separate W3C trace ID in root_span_id, so the returned Mastra spanId isn't the Braintrust root_span_id.

src/mastra/usage.ts
const result = await agent.stream('Summarize this ticket')

console.log('Mastra trace ID:', result.traceId)
console.log('Braintrust row and span ID:', result.spanId)

// Use result.spanId in your Braintrust lookup/query path

The same applies to agent.generate() and workflow run results (run.start(), run.stream() final state, run.resume()).

On this page