跳到主要内容

SentryExporter

使用 OpenTelemetry 语义约定将 Tracing 数据发送到 Sentry，用于 AI tracing 和监控。

构造函数
构造函数的直接链接

new SentryExporter(config: SentryExporterConfig)

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' - 日志级别（默认：INFO）

方法
方法的直接链接

exportTracingEvent
exporttracingevent的直接链接

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

将 tracing 事件导出到 Sentry。处理 SPAN_STARTED、SPAN_UPDATED 和 SPAN_ENDED 事件。

flush
flush的直接链接

async flush(): Promise<void>

在不关闭 Exporter 的情况下，强制将所有待处理 Span 刷新到 Sentry。最多等待 2 秒，以便发送待处理数据。适用于需要在运行时终止前确保 Span 已导出的 serverless 环境。

shutdown
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 选项
使用自定义 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 映射
Span 映射的直接链接

Mastra Span 类型会映射为 Sentry 操作：

Mastra SpanTypeSentry 操作
AGENT_RUNgen_ai.invoke_agent
MODEL_GENERATIONgen_ai.chat
MODEL_STEP（跳过）
MODEL_CHUNK（跳过）
TOOL_CALLgen_ai.execute_tool
MCP_TOOL_CALLgen_ai.execute_tool
PROVIDER_TOOL_CALLgen_ai.execute_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

为简化 Trace 层次结构，MODEL_STEP 和 MODEL_CHUNK Span 会被跳过。它们的数据会聚合到 MODEL_GENERATION Span 中。

环境变量
环境变量的直接链接

Exporter 从以下环境变量读取配置：

变量描述
SENTRY_DSNData Source Name，用于告知 SDK 将事件发送到何处
SENTRY_ENVIRONMENT部署环境名称
SENTRY_RELEASE已部署代码的版本

OpenTelemetry 属性
opentelemetry-attributes的直接链接

Exporter 会设置以下标准 OpenTelemetry 属性：

通用属性（所有 Span）：

  • sentry.origin：auto.ai.mastra（标识来自 Mastra 的 Span）
  • ai.span.type：Mastra Span 类型
  • gen_ai.conversation.id：聊天线程标识符，从 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 数组）
  • 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：来自子生成过程的模型
  • gen_ai.response.text：来自子生成过程的输出
  • gen_ai.usage.*：来自子生成过程的 token 用量
On this page