Skip to main content

Sentry 导出器

🌐 Sentry Exporter

Sentry 是一个具有 AI 特定跟踪功能的应用监控平台。Sentry 导出器使用 OpenTelemetry 语义约定将你的跟踪发送到 Sentry，从而提供有关模型性能、令牌使用情况和工具执行的洞察。

安装
Direct link to 安装

🌐 Installation

npm install @mastra/sentry@beta

配置
Direct link to 配置

🌐 Configuration

先决条件
Direct link to 先决条件

🌐 Prerequisites

  1. Sentry 账户：在 sentry.io 注册
  2. DSN：从项目设置 → 客户端密钥获取你的数据源名称
  3. 环境变量：设置你的配置
.env
SENTRY_DSN=https://...@...sentry.io/...

# Optional
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=1.0.0

零配置设置
Direct link to 零配置设置

🌐 Zero-Config Setup

设置环境变量后，使用无配置的导出器：

🌐 With environment variables set, use the exporter with no configuration:

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()],
      },
    },
  }),
});

显式配置
Direct link to 显式配置

🌐 Explicit Configuration

你也可以直接传递凭据（优先于环境变量）：

🌐 You can also pass credentials directly (takes precedence over environment variables):

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
          }),
        ],
      },
    },
  }),
});

配置选项
Direct link to 配置选项

🌐 Configuration Options

完成配置
Direct link to 完成配置

🌐 Complete Configuration

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
});

采样配置
Direct link to 采样配置

🌐 Sampling Configuration

控制发送到 Sentry 的交易百分比。这对于高流量应用很有用：

🌐 Control the percentage of transactions sent to Sentry. This is useful for high-volume applications:

new SentryExporter({
  dsn: process.env.SENTRY_DSN!,
  tracesSampleRate: 0.1, // Send 10% of transactions to Sentry (recommended for high-load backends)
});
tip

对于开发，将其设置为 1.0（100%）；对于高负载生产应用，将其设置为 0.1 到 0.2（10-20%）。要完全禁用跟踪，不要设置 tracesSampleRate，而不是将其设置为 0。

跨度类型映射
Direct link to 跨度类型映射

🌐 Span Type Mapping

Mastra 跨度类型会自动映射到 Sentry 操作：

🌐 Mastra span types are automatically mapped to Sentry operations:

Mastra SpanTypeSentry OperationNotes
AGENT_RUNgen_ai.invoke_agentContains tokens from child MODEL_GENERATION span
MODEL_GENERATIONgen_ai.chatIncludes usage stats, streaming data
MODEL_STEP(skipped)Skipped to simplify trace hierarchy
MODEL_CHUNK(skipped)Data aggregated in MODEL_GENERATION
TOOL_CALLgen_ai.execute_toolTool execution with input/output
MCP_TOOL_CALLgen_ai.execute_toolMCP tool execution
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 语义约定
Direct link to OpenTelemetry 语义约定

🌐 OpenTelemetry Semantic Conventions

导出器使用带有 Sentry 特定属性的标准 GenAI 语义约定：

🌐 The exporter uses standard GenAI semantic conventions with Sentry-specific attributes:

对于 MODEL_GENERATION 范围:

  • gen_ai.system：模型提供商（例如，openai、anthropic）
  • gen_ai.request.model：模型标识符（例如，gpt-4）
  • gen_ai.response.model：响应模型
  • gen_ai.response.text：输出文本响应
  • gen_ai.response.tool_calls：生成过程中发出的工具调用（JSON 数组）
  • gen_ai.usage.input_tokens：输入令牌数
  • gen_ai.usage.output_tokens：输出令牌数
  • gen_ai.request.temperature：温度参数
  • gen_ai.request.stream：是否请求了流
  • gen_ai.request.messages：输入消息/提示（JSON）
  • gen_ai.completion_start_time：第一枚令牌到达的时间

对于 TOOL_CALL 范围：

  • gen_ai.tool.name：工具标识符
  • gen_ai.tool.type：function
  • gen_ai.tool.call.id：工具调用ID
  • gen_ai.tool.input：工具输入（JSON）
  • gen_ai.tool.output：工具输出（JSON）
  • tool.success：工具调用是否成功

对于 AGENT_RUN 时间段:

  • gen_ai.agent.name：代理标识
  • gen_ai.pipeline.name：代理名称（用于 Sentry AI 查看）
  • gen_ai.agent.instructions：代理指令
  • gen_ai.response.model：来自儿童世代的模型
  • gen_ai.response.text：子代生成的输出文本
  • gen_ai.usage.*：子代生成的令牌使用

功能
Direct link to 功能

🌐 Features

  • 层级追踪：保持父子关系
  • 令牌追踪：自动跟踪生成过程中令牌的使用情况
  • 工具调用跟踪：记录工具的执行及其输入/输出
  • 流支持：聚合流响应
  • 错误跟踪：自动捕获错误状态和异常
  • 工作流支持：跟踪工作流执行步骤
  • 简化层次：跳过 MODEL_STEP 和 MODEL_CHUNK 范围以减少噪音

🌐 Related

目录