Skip to main content

SentryExporter

使用 OpenTelemetry 语义规范将追踪数据发送到 Sentry，以进行 AI 追踪和监控。

🌐 Sends Tracing data to Sentry for AI tracing and monitoring using OpenTelemetry semantic conventions.

构造函数
Direct link to 构造函数

🌐 Constructor

new SentryExporter(config: SentryExporterConfig)

SentryExporterConfig
Direct link to SentryExporterConfig

interface SentryExporterConfig extends BaseExporterConfig {
  dsn?: string;
  environment?: string;
  tracesSampleRate?: number;
  release?: string;
  options?: Partial<Sentry.NodeOptions>;
}

扩展自 BaseExporterConfig，包括：

🌐 Extends BaseExporterConfig, which includes:

  • logger?: IMastraLogger - 记录器实例
  • logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error' - 日志级别（默认：INFO）

方法
Direct link to 方法

🌐 Methods

exportTracingEvent
Direct link to exportTracingEvent

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

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

🌐 Exports a tracing event to Sentry. Handles SPAN_STARTED, SPAN_UPDATED, and SPAN_ENDED events.

flush
Direct link to flush

async flush(): Promise<void>

强制将任何未发送的跨度刷新到 Sentry，而不关闭导出器。最多等待 2 秒以发送待处理的数据。在无服务器环境中非常有用，确保在运行时终止之前导出跨度。

🌐 Force flushes any pending spans to Sentry without shutting down the exporter. Waits up to 2 seconds for pending data to be sent. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.

shutdown
Direct link to shutdown

async shutdown(): Promise<void>

结束所有活动的跨度，清除内部状态，并关闭 Sentry 连接。等待最多 2 秒以发送未完成的数据。

🌐 Ends all active spans, clears internal state, and closes the Sentry connection. Waits up to 2 seconds for pending data to be sent.

用法
Direct link to 用法

🌐 Usage

零配置（使用环境变量）
Direct link to 零配置（使用环境变量）

🌐 Zero-Config (using environment variables)

import { SentryExporter } from "@mastra/sentry";

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

显式配置
Direct link to 显式配置

🌐 Explicit Configuration

import { SentryExporter } from "@mastra/sentry";

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

带采样
Direct link to 带采样

🌐 With Sampling

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 选项
Direct link to 使用自定义 Sentry 选项

🌐 With Custom Sentry Options

const exporter = new SentryExporter({
  dsn: process.env.SENTRY_DSN,
  environment: "production",
  options: {
    integrations: [
      // Custom Sentry integrations
    ],
    beforeSend: (event) => {
      // Custom event processing
      return event;
    },
  },
});

跨度映射
Direct link to 跨度映射

🌐 Span Mapping

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

🌐 Mastra span types are mapped to Sentry operations:

Mastra 跨度类型Sentry 操作
AGENT_RUNgen_ai.invoke_agent
MODEL_GENERATIONgen_ai.chat
MODEL_STEP(跳过)
MODEL_CHUNK(跳过)
TOOL_CALLgen_ai.execute_tool
MCP_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

为了简化追踪层次，MODEL_STEP 和 MODEL_CHUNK 的跨度被跳过。它们的数据被汇总到 MODEL_GENERATION 的跨度中。

🌐 MODEL_STEP and MODEL_CHUNK spans are skipped to simplify trace hierarchy. Their data is aggregated into MODEL_GENERATION spans.

环境变量
Direct link to 环境变量

🌐 Environment Variables

导出器从这些环境变量中读取配置：

🌐 The exporter reads configuration from these environment variables:

变量描述
SENTRY_DSN数据源名称 - 告诉 SDK 将事件发送到哪里
SENTRY_ENVIRONMENT部署环境名称
SENTRY_RELEASE已部署代码的版本

OpenTelemetry 属性
Direct link to OpenTelemetry 属性

🌐 OpenTelemetry Attributes

导出器设置了这些标准的 OpenTelemetry 属性：

🌐 The exporter sets these standard OpenTelemetry attributes:

常见属性（所有跨度）：

  • sentry.origin：auto.ai.mastra（标识来自Mastra的跨度）
  • ai.span.type：Mastra 跨度类型

模型生成 范围:

  • gen_ai.operation.name：chat
  • gen_ai.system：模型提供商
  • gen_ai.request.model：型号标识
  • gen_ai.request.messages：输入消息/提示（JSON）
  • 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.usage.total_tokens：总令牌
  • gen_ai.request.stream：流式传输标志
  • gen_ai.request.temperature：温度参数
  • gen_ai.completion_start_time：首次令牌时间

TOOL_CALL 跨度：

  • gen_ai.operation.name：execute_tool
  • gen_ai.tool.name：工具标识符
  • gen_ai.tool.type：function
  • gen_ai.tool.call.id：工具调用ID
  • gen_ai.tool.input：工具输入
  • gen_ai.tool.output：工具输出
  • tool.success：成功标志

AGENT_RUN 跨度:

  • gen_ai.operation.name：invoke_agent
  • gen_ai.agent.name：代理标识
  • gen_ai.pipeline.name：代理名称
  • gen_ai.agent.instructions：代理指令
  • gen_ai.response.model：来自儿童世代的模型
  • gen_ai.response.text：子代生成的输出
  • gen_ai.usage.*：子代生成的令牌使用
目录