跳至主要內容

Sentry Exporter

Sentry 是一個應用程式監控平台，具備 AI 專用的 Tracing 功能。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%）。若要完全停用 Tracing，請不要設定 tracesSampleRate，而不是將它設為 0。

Span 類型對應
「Span 類型對應」的直接連結

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

Mastra SpanTypeSentry operation備註
AGENT_RUNgen_ai.invoke_agent包含子 MODEL_GENERATION span 的 token
MODEL_GENERATIONgen_ai.chat包含使用量統計與 Streaming 資料
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 專用 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，減少干擾資訊
On this page