SentryExporter

使用 OpenTelemetry semantic convention，將 Tracing 資料傳送至 Sentry，以進行 AI tracing 與監控。

建構函式

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 執行個體
• logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - Log 層級（預設：INFO）

方法

exportTracingEvent

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

將 tracing 事件匯出至 Sentry。處理 SPAN_STARTED、SPAN_UPDATED 與 SPAN_ENDED 事件。

flush

async flush(): Promise<void>

強制將所有待處理 span flush 至 Sentry，而不關閉 exporter。最多等待 2 秒，讓待處理資料完成傳送。這在 serverless 環境中特別實用，可確保 runtime 結束前已匯出 span。

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 操作
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：模型 Provider
• gen_ai.request.model：模型識別碼
• gen_ai.request.messages：輸入訊息／提示（JSON）
• 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.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 call 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 instructions
• gen_ai.response.model：來自子 generation 的模型
• gen_ai.response.text：來自子 generation 的輸出
• gen_ai.usage.*：來自子 generation 的 token 用量