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

# SentryExporter

使用 OpenTelemetry semantic convention，將 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'` - Log 層級（預設：INFO）

## 方法

### `exportTracingEvent`

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

將 tracing 事件匯出至 Sentry。處理 SPAN\_STARTED、SPAN\_UPDATED 與 SPAN\_ENDED 事件。

### flush

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

強制將所有待處理 span flush 至 Sentry，而不關閉 exporter。最多等待 2 秒，讓待處理資料完成傳送。這在 serverless 環境中特別實用，可確保 runtime 結束前已匯出 span。

### 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 operation：

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

MODEL\_STEP 與 MODEL\_CHUNK span 會略過，以簡化 trace 階層。其資料會彙總至 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`：聊天 thread 識別碼，從 `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 array）
- `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 call 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 instructions
- `gen_ai.response.model`：來自子 generation 的模型
- `gen_ai.response.text`：來自子 generation 的輸出
- `gen_ai.usage.*`：來自子 generation 的 token 用量