SentryExporter

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

Constructor

new SentryExporter(config: SentryExporterConfig)

SentryExporterConfig

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

async exportTracingEvent(event: TracingEvent): Promise<void>

將 Tracing 事件匯出至 Sentry。處理 SPAN_STARTED、SPAN_UPDATED 及 SPAN_ENDED 事件。

flush

async flush(): Promise<void>

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

shutdown

async shutdown(): Promise<void>

結束所有使用中的 span、清除內部狀態，並關閉 Sentry 連線。最多等候 2 秒，以傳送待處理資料。

用法

零設定（使用環境變數）

import { SentryExporter } from '@mastra/sentry'

// Reads from SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE
const exporter = new SentryExporter()

明確設定

import { SentryExporter } from '@mastra/sentry'

const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: 'production',
  tracesSampleRate: 1.0,
  release: '1.0.0',
})

使用取樣

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 選項

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 用量