> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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`          | 包含使用量統計與 Streaming 資料              |
| `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 專用 attribute：

**針對 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 array）
- `gen_ai.usage.input_tokens`：輸入 token 數量
- `gen_ai.usage.output_tokens`：輸出 token 數量
- `gen_ai.request.temperature`：Temperature 參數
- `gen_ai.request.stream`：是否要求 Streaming
- `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 View）
- `gen_ai.agent.instructions`：Agent instructions
- `gen_ai.response.model`：子生成作業所使用的模型
- `gen_ai.response.text`：子生成作業的輸出文字
- `gen_ai.usage.*`：子生成作業的 token 用量

## 功能

- **階層式 Trace**：維持父子關係
- **Token 追蹤**：自動追蹤生成作業的 token 用量
- **Tool 呼叫追蹤**：擷取 Tool 執行作業及其輸入／輸出
- **支援 Streaming**：彙總 Streaming 回應
- **錯誤追蹤**：自動擷取錯誤狀態與例外
- **支援 Workflow**：追蹤 Workflow 執行步驟
- **簡化階層**：略過 MODEL\_STEP 與 MODEL\_CHUNK span，減少干擾資訊

## 相關內容

- [Tracing 總覽](https://mastra.zisheng.pro/zh-TW/docs/observability/tracing/overview)
- [Sentry 文件](https://docs.sentry.io/)
- [OpenTelemetry 語意慣例](https://opentelemetry.io/docs/concepts/semantic-conventions/)