跳到主要内容

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包含用量统计和流式数据
MODEL_STEP（跳过）跳过以简化 Trace 层级
MODEL_CHUNK（跳过）数据聚合在 MODEL_GENERATION 中
TOOL_CALLgen_ai.execute_tool包含输入/输出的 Tool 执行
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 调用（JSON 数组）
  • 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 调用 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 视图）
  • gen_ai.agent.instructions：Agent 指令
  • gen_ai.response.model：子生成所用模型
  • gen_ai.response.text：子生成的输出文本
  • gen_ai.usage.*：子生成的 token 用量

功能
功能的直接链接

  • 分层 Trace：保持父子关系
  • Token 跟踪：自动跟踪生成的 token 用量
  • Tool 调用跟踪：捕获带输入/输出的 Tool 执行
  • 流式支持：聚合流式响应
  • 错误跟踪：自动捕获错误状态和异常
  • Workflow 支持：跟踪 Workflow 执行步骤
  • 简化层级：跳过 MODEL_STEP 和 MODEL_CHUNK span 以减少噪声
On this page