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

# Sentry exporter

[Sentry](https://sentry.io/) 是一个具备 AI 专用 Tracing 功能的应用监控平台。Sentry exporter 使用 OpenTelemetry 语义约定将 Trace 发送到 Sentry，帮助你深入了解模型性能、token 用量和 Tool 执行情况。

## 安装

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 配置

### 前提条件

1. **Sentry 账户**：在 [sentry.io](https://sentry.io/) 注册
2. **DSN**：从 Project Settings → Client Keys 获取 [Data Source Name](https://docs.sentry.io/concepts/key-terms/dsn-explainer/)
3. **环境变量**：设置配置

```bash
SENTRY_DSN=https://...@...sentry.io/...

# Optional
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0
```

### 零配置设置

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

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { SentryExporter } from '@mastra/sentry'

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

### 显式配置

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

```typescript
import { Mastra } from '@mastra/core'
import { Observability } from '@mastra/observability'
import { SentryExporter } from '@mastra/sentry'

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      sentry: {
        serviceName: 'my-service',
        exporters: [
          new SentryExporter({
            dsn: process.env.SENTRY_DSN!,
            environment: 'production',
            tracesSampleRate: 1.0, // Send 100% of transactions to Sentry
          }),
        ],
      },
    },
  }),
})
```

## 配置选项

### 完整配置

```typescript
new SentryExporter({
  // Required settings
  dsn: process.env.SENTRY_DSN!, // Data Source Name - tells the SDK where to send events

  // Optional settings
  environment: 'production', // Deployment environment (enables filtering issues and alerts by environment)
  tracesSampleRate: 1.0, // Percentage of transactions sent to Sentry (0.0 = 0%, 1.0 = 100%)
  release: '1.0.0', // Version of your code deployed (helps identify regressions and track deployments)

  // Advanced Sentry options
  options: {
    // Any additional Sentry.NodeOptions
    integrations: [],
    beforeSend: event => event,
    // ... other Sentry SDK options
  },

  // Diagnostic logging
  logLevel: 'info', // debug | info | warn | error
})
```

### 采样配置

控制发送到 Sentry 的 transaction 百分比。这对高流量应用很有用：

```typescript
new SentryExporter({
  dsn: process.env.SENTRY_DSN!,
  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
})
```

> **提示:** 开发环境设为 `1.0`（100%）；生产环境中的高负载应用设为 `0.1` 到 `0.2`（10%–20%）。要完全禁用 Tracing，请不要设置 `tracesSampleRate`，而不是将其设为 `0`。

## Span 类型映射

Mastra span 类型会自动映射到 Sentry operation：

| Mastra SpanType             | Sentry Operation       | 备注                                 |
| --------------------------- | ---------------------- | ---------------------------------- |
| `AGENT_RUN`                 | `gen_ai.invoke_agent`  | 包含子 MODEL\_GENERATION span 的 token |
| `MODEL_GENERATION`          | `gen_ai.chat`          | 包含用量统计和流式数据                        |
| `MODEL_STEP`                | _（跳过）_                 | 跳过以简化 Trace 层级                     |
| `MODEL_CHUNK`               | _（跳过）_                 | 数据聚合在 MODEL\_GENERATION 中          |
| `TOOL_CALL`                 | `gen_ai.execute_tool`  | 包含输入/输出的 Tool 执行                   |
| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  | MCP Tool 执行                        |
| `WORKFLOW_RUN`              | `workflow.run`         |                                    |
| `WORKFLOW_STEP`             | `workflow.step`        |                                    |
| `WORKFLOW_CONDITIONAL`      | `workflow.conditional` |                                    |
| `WORKFLOW_CONDITIONAL_EVAL` | `workflow.conditional` |                                    |
| `WORKFLOW_PARALLEL`         | `workflow.parallel`    |                                    |
| `WORKFLOW_LOOP`             | `workflow.loop`        |                                    |
| `WORKFLOW_SLEEP`            | `workflow.sleep`       |                                    |
| `WORKFLOW_WAIT_EVENT`       | `workflow.wait`        |                                    |
| `PROCESSOR_RUN`             | `ai.processor`         |                                    |
| `GENERIC`                   | `ai.span`              |                                    |

## OpenTelemetry 语义约定

Exporter 使用标准 GenAI 语义约定和 Sentry 专用属性：

**对于 MODEL\_GENERATION span：**

- `gen_ai.system`：模型 Provider（例如 `openai`、`anthropic`）
- `gen_ai.request.model`：模型标识符（例如 `gpt-5.4`）
- `gen_ai.response.model`：响应模型
- `gen_ai.response.text`：输出文本响应
- `gen_ai.response.tool_calls`：生成期间发出的 Tool 调用（JSON 数组）
- `gen_ai.usage.input_tokens`：输入 token 数量
- `gen_ai.usage.output_tokens`：输出 token 数量
- `gen_ai.request.temperature`：temperature 参数
- `gen_ai.request.stream`：是否请求流式传输
- `gen_ai.request.messages`：输入消息/prompt（JSON）
- `gen_ai.completion_start_time`：首个 token 到达时间

**对于 TOOL\_CALL span：**

- `gen_ai.tool.name`：Tool 标识符
- `gen_ai.tool.type`：`function`
- `gen_ai.tool.call.id`：Tool 调用 ID
- `gen_ai.tool.input`：Tool 输入（JSON）
- `gen_ai.tool.output`：Tool 输出（JSON）
- `tool.success`：Tool 调用是否成功

**对于 AGENT\_RUN span：**

- `gen_ai.agent.name`：Agent 标识符
- `gen_ai.pipeline.name`：Agent 名称（用于 Sentry AI 视图）
- `gen_ai.agent.instructions`：Agent 指令
- `gen_ai.response.model`：子生成所用模型
- `gen_ai.response.text`：子生成的输出文本
- `gen_ai.usage.*`：子生成的 token 用量

## 功能

- **分层 Trace**：保持父子关系
- **Token 跟踪**：自动跟踪生成的 token 用量
- **Tool 调用跟踪**：捕获带输入/输出的 Tool 执行
- **流式支持**：聚合流式响应
- **错误跟踪**：自动捕获错误状态和异常
- **Workflow 支持**：跟踪 Workflow 执行步骤
- **简化层级**：跳过 MODEL\_STEP 和 MODEL\_CHUNK span 以减少噪声

## 相关内容

- [Tracing 概览](https://mastra.zisheng.pro/docs/observability/tracing/overview)
- [Sentry 文档](https://docs.sentry.io/)
- [OpenTelemetry 语义约定](https://opentelemetry.io/docs/concepts/semantic-conventions/)