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

# SentryExporter

按照 OpenTelemetry 語義慣例將 Tracing 資料傳送至 Sentry，供 AI 追蹤及監察之用。

## Constructor

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

強制將所有待處理的 span 傳送至 Sentry，而不會關閉 exporter。最多等候 2 秒，讓待處理資料完成傳送。這適用於 serverless 環境，讓你可確保 span 在 runtime 終止前完成匯出。

### 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 operation       |
| --------------------------- | ---------------------- |
| `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`：Model provider
- `gen_ai.request.model`：Model 識別符
- `gen_ai.request.messages`：輸入訊息／prompt（JSON）
- `gen_ai.response.model`：回應 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`：來自子生成程序的 Model
- `gen_ai.response.text`：來自子生成程序的輸出
- `gen_ai.usage.*`：子生成程序的 token 用量