> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Braintrust exporter

[Braintrust](https://www.braintrust.dev/) 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

**npm**:

```bash
npm install @mastra/braintrust@latest
```

**pnpm**:

```bash
pnpm add @mastra/braintrust@latest
```

**Yarn**:

```bash
yarn add @mastra/braintrust@latest
```

**Bun**:

```bash
bun add @mastra/braintrust@latest
```

## Configuration

### Prerequisites

1. **Braintrust Account**: Sign up at [braintrust.dev](https://www.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:

```bash
BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx

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

### Zero-Config Setup

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

```typescript
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

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

```typescript
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

```typescript
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

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

**npm**:

```bash
npm install braintrust@latest
```

**pnpm**:

```bash
pnpm add braintrust@latest
```

**Yarn**:

```bash
yarn add braintrust@latest
```

**Bun**:

```bash
bun add 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`.

```typescript
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()`.

```typescript
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](https://www.braintrust.dev/docs/sdks/typescript/migrations/v2-to-v3).

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

```typescript
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()`).

## Related

- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
- [Braintrust Documentation](https://www.braintrust.dev/docs)