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

# SentryExporter

使用 OpenTelemetry 语义约定将 Tracing 数据发送到 Sentry，用于 AI tracing 和监控。

## 构造函数

```typescript
new SentryExporter(config: SentryExporterConfig)
```

## `SentryExporterConfig`

```typescript
interface SentryExporterConfig extends BaseExporterConfig {
  dsn?: string
  environment?: string
  tracesSampleRate?: number
  release?: string
  options?: Partial<Sentry.NodeOptions>
}
```

扩展自 `BaseExporterConfig`，其中包括：

- `logger?: IMastraLogger` - Logger 实例
- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - 日志级别（默认：INFO）

## 方法

### `exportTracingEvent`

```typescript
async exportTracingEvent(event: TracingEvent): Promise<void>
```

将 tracing 事件导出到 Sentry。处理 SPAN\_STARTED、SPAN\_UPDATED 和 SPAN\_ENDED 事件。

### flush

```typescript
async flush(): Promise<void>
```

在不关闭 Exporter 的情况下，强制将所有待处理 Span 刷新到 Sentry。最多等待 2 秒，以便发送待处理数据。适用于需要在运行时终止前确保 Span 已导出的 serverless 环境。

### shutdown

```typescript
async shutdown(): Promise<void>
```

结束所有活动 Span、清除内部状态并关闭 Sentry 连接。最多等待 2 秒，以便发送待处理数据。

## 用法

### 零配置（使用环境变量）

```typescript
import { SentryExporter } from '@mastra/sentry'

// Reads from SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE
const exporter = new SentryExporter()
```

### 显式配置

```typescript
import { SentryExporter } from '@mastra/sentry'

const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  tracesSampleRate: 1.0,
  release: '1.0.0',
})
```

### 使用采样

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

### 使用自定义 Sentry 选项

```typescript
const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  options: {
    integrations: [
      // Custom Sentry integrations
    ],
    beforeSend: event => {
      // Custom event processing
      return event
    },
  },
})
```

## Span 映射

Mastra Span 类型会映射为 Sentry 操作：

| Mastra SpanType             | Sentry 操作              |
| --------------------------- | ---------------------- |
| `AGENT_RUN`                 | `gen_ai.invoke_agent`  |
| `MODEL_GENERATION`          | `gen_ai.chat`          |
| `MODEL_STEP`                | _（跳过）_                 |
| `MODEL_CHUNK`               | _（跳过）_                 |
| `TOOL_CALL`                 | `gen_ai.execute_tool`  |
| `MCP_TOOL_CALL`             | `gen_ai.execute_tool`  |
| `PROVIDER_TOOL_CALL`        | `gen_ai.execute_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`              |

为简化 Trace 层次结构，MODEL\_STEP 和 MODEL\_CHUNK Span 会被跳过。它们的数据会聚合到 MODEL\_GENERATION Span 中。

## 环境变量

Exporter 从以下环境变量读取配置：

| 变量                   | 描述                                 |
| -------------------- | ---------------------------------- |
| `SENTRY_DSN`         | Data Source Name，用于告知 SDK 将事件发送到何处 |
| `SENTRY_ENVIRONMENT` | 部署环境名称                             |
| `SENTRY_RELEASE`     | 已部署代码的版本                           |

## `OpenTelemetry` 属性

Exporter 会设置以下标准 OpenTelemetry 属性：

**通用属性（所有 Span）：**

- `sentry.origin`：`auto.ai.mastra`（标识来自 Mastra 的 Span）
- `ai.span.type`：Mastra Span 类型
- `gen_ai.conversation.id`：聊天线程标识符，从 `metadata.threadId` 设置，用于在 Sentry 的 Conversations 视图中对 Span 进行分组

**MODEL\_GENERATION Span：**

- `gen_ai.operation.name`：`chat`
- `gen_ai.system`：模型 Provider
- `gen_ai.request.model`：模型标识符
- `gen_ai.request.messages`：输入消息/提示词（JSON）
- `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.usage.total_tokens`：token 总数
- `gen_ai.request.stream`：流式标志
- `gen_ai.request.temperature`：temperature 参数
- `gen_ai.completion_start_time`：首个 token 的时间

**TOOL\_CALL Span：**

- `gen_ai.operation.name`：`execute_tool`
- `gen_ai.tool.name`：Tool 标识符
- `gen_ai.tool.type`：`function`
- `gen_ai.tool.call.id`：Tool 调用 ID
- `gen_ai.tool.input`：Tool 输入
- `gen_ai.tool.output`：Tool 输出
- `tool.success`：成功标志

**AGENT\_RUN Span：**

- `gen_ai.operation.name`：`invoke_agent`
- `gen_ai.agent.name`：Agent 标识符
- `gen_ai.pipeline.name`：Agent 名称
- `gen_ai.agent.instructions`：Agent 指令
- `gen_ai.response.model`：来自子生成过程的模型
- `gen_ai.response.text`：来自子生成过程的输出
- `gen_ai.usage.*`：来自子生成过程的 token 用量