跳至主要內容

Sentry exporter

Sentry 是一個具備 AI 專用追蹤功能的應用程式監察平台。Sentry exporter 使用 OpenTelemetry 語義慣例將 Trace 傳送至 Sentry，讓你深入了解模型效能、token 用量及 Tool 執行情況。

安裝
安裝 的直接連結

npm install @mastra/sentry@latest

配置
配置 的直接連結

前置要求
前置要求 的直接連結

  1. Sentry 帳戶：在 sentry.io 註冊
  2. DSN：從 Project Settings → Client Keys 取得你的 Data Source Name
  3. 環境變數：設定你的配置
.env
SENTRY_DSN=https://...@...sentry.io/...

# Optional
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

零配置設定
零配置設定 的直接連結

設定環境變數後，無需任何配置即可使用 exporter：

src/mastra/index.ts
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()],
      },
    },
  }),
})

明確配置
明確配置 的直接連結

你亦可直接傳入憑證（優先於環境變數）：

src/mastra/index.ts
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
          }),
        ],
      },
    },
  }),
})

配置選項
配置選項 的直接連結

完整配置
完整配置 的直接連結

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 百分比。這對高流量應用程式尤其有用：

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 類型對應
Span 類型對應 的直接連結

Mastra span 類型會自動對應至 Sentry operation：

Mastra SpanTypeSentry Operation備註
AGENT_RUNgen_ai.invoke_agent包含來自子 MODEL_GENERATION span 的 token
MODEL_GENERATIONgen_ai.chat包含用量統計和串流資料
MODEL_STEP(略過)略過以簡化 Trace 階層
MODEL_CHUNK(略過)資料彙整於 MODEL_GENERATION
TOOL_CALLgen_ai.execute_toolTool 執行及其輸入／輸出
MCP_TOOL_CALLgen_ai.execute_toolMCP Tool 執行
WORKFLOW_RUNworkflow.run
WORKFLOW_STEPworkflow.step
WORKFLOW_CONDITIONALworkflow.conditional
WORKFLOW_CONDITIONAL_EVALworkflow.conditional
WORKFLOW_PARALLELworkflow.parallel
WORKFLOW_LOOPworkflow.loop
WORKFLOW_SLEEPworkflow.sleep
WORKFLOW_WAIT_EVENTworkflow.wait
PROCESSOR_RUNai.processor
GENERICai.span

OpenTelemetry 語義慣例
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 以減少干擾資訊
On this page