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

# Braintrust exporter

[Braintrust](https://www.braintrust.dev/) 是一个评估和监控平台，可帮助你衡量并提升 LLM 应用质量。Braintrust exporter 会将 Trace 发送到 Braintrust，以支持系统化评估、评分和实验。

## 安装

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

## 配置

### 前提条件

1. **Braintrust 账户**：在 [braintrust.dev](https://www.braintrust.dev/) 注册
2. **项目**：为 Trace 创建或选择一个项目
3. **API key**：在 Braintrust Settings → API Keys 中生成
4. **环境变量**：设置凭据：

```bash
BRAINTRUST_API_KEY=sk-xxxxxxxxxxxxxxxx

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

### 零配置设置

设置环境变量后，无需任何配置即可使用 exporter：

```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()],
      },
    },
  }),
})
```

### 显式配置

你也可以直接传入凭据（优先于环境变量）：

```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',
          }),
        ],
      },
    },
  }),
})
```

### 完整配置

```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
})
```

## 将 Trace 附加到 Braintrust Evals

如果应用使用 `Eval()`、`logger.traced()` 或 `currentSpan`，请直接安装 Braintrust SDK：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

```bash
bun add braintrust@latest
```

在 Braintrust `Eval()` 或 `logger.traced()` 中运行 Mastra 时，请将 Braintrust logger 和 `currentSpan` resolver 传给 exporter。从创建 eval 或 traced span 的同一个 `braintrust` 软件包实例导入 `currentSpan`。

如果应用与 `@mastra/braintrust` 解析到不同的 Braintrust SDK 安装副本，这有助于 Mastra 将自己的 span 附加到活跃的 Braintrust span 下。

Exporter 接受与 Braintrust SDK v2 和 v3 兼容的 logger 和 span 对象。应用的 Braintrust SDK 版本无需与 `@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,
})
```

在 Braintrust eval task 中使用配置好的 Mastra 实例。上面的 `currentSpan` resolver 会读取 `Eval()` 创建的活跃 span。

```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: [],
})
```

如果应用将直接依赖的 Braintrust 从 v2 升级到 v3，并使用 Nunjucks prompt 模板，请遵循 [Braintrust v2 到 v3 迁移指南](https://www.braintrust.dev/docs/sdks/typescript/migrations/v2-to-v3)。

## 使用返回的 `spanId` 查询 Braintrust

Mastra 会将返回的 `spanId` 同时用作 Braintrust 行 ID 和 span ID。可通过 `id` 或 `span_id` 用它查找对应的 Braintrust span。

Braintrust v3 会在 `root_span_id` 中存储单独的 W3C Trace ID，因此 Mastra 返回的 `spanId` 并不是 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
```

这同样适用于 `agent.generate()` 和 Workflow 运行结果（`run.start()`、`run.stream()` 最终状态、`run.resume()`）。

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Braintrust 文档](https://www.braintrust.dev/docs)