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

# Sentry exporter

[Sentry](https://sentry.io/) 是一個具備 AI 專用追蹤功能的應用程式監察平台。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%）。如要完全停用追蹤，請不要設定 `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 call（JSON array）
- `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 call ID
- `gen_ai.tool.input`：Tool 輸入（JSON）
- `gen_ai.tool.output`：Tool 輸出（JSON）
- `tool.success`：Tool call 是否成功

**適用於 AGENT\_RUN span：**

- `gen_ai.agent.name`：Agent 識別碼
- `gen_ai.pipeline.name`：Agent 名稱（用於 Sentry AI view）
- `gen_ai.agent.instructions`：Agent 指示
- `gen_ai.response.model`：來自子模型生成作業的模型
- `gen_ai.response.text`：來自子模型生成作業的輸出文字
- `gen_ai.usage.*`：來自子模型生成作業的 token 用量

## 功能

- **階層式 Trace**：維持父子關係
- **Token 追蹤**：自動追蹤模型生成作業的 token 用量
- **Tool call 追蹤**：擷取 Tool 執行及其輸入／輸出
- **串流支援**：彙整串流回應
- **錯誤追蹤**：自動擷取錯誤狀態及 exception
- **Workflow 支援**：追蹤 Workflow 執行步驟
- **簡化階層**：略過 MODEL\_STEP 和 MODEL\_CHUNK span 以減少干擾資訊

## 相關資源

- [追蹤概覽](https://mastra.zisheng.pro/zh-HK/docs/observability/tracing/overview)
- [Sentry 文件](https://docs.sentry.io/)
- [OpenTelemetry 語義慣例](https://opentelemetry.io/docs/concepts/semantic-conventions/)