Mastra 可观测性接入指南使用 mastra/deepeval 将 Traces 导出到 Confident AI【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇技术指南围绕 Mastra 仓库中的mastra/deepeval可观测性导出器展开讲解如何在 Mastra 应用中把 Agent、LLM、工具调用等 Tracing 数据发送到 Confident AI基于 DeepEval SDK 构建的评估与监控平台实现 AI 应用的在线评估与运行监控。读完本文你将掌握该导出器的安装、注册、配置项详解、环境变量设置以及其底层源码实现原理与 Span 类型映射规则。一、mastra/deepeval 是什么mastra/deepeval是 Mastra 官方的 Confident AI 可观测性导出器observability exporter定位是将 Mastra 的 traces 发送到 Confident AI 进行评估与监控。它构建在 DeepEval SDK 之上负责把 Mastra 内部产生的 Tracing 事件转换为 DeepEval/Confident AI 能识别的 trace 结构。从 包描述文件 可以看到该包的完整名称为mastra/deepeval采用 ESM/CJS 双格式输出其运行时依赖仅有mastra/observability与deepeval当前版本约束为^0.1.32peer 依赖为mastra/core 1.16.0-0 2.0.0-0并要求 Node.js22.13.0。这表明它是一个轻量适配层——真正的 trace 转换与上报逻辑复用了 DeepEval SDK 中的 Mastra 集成。与 Mastra 可观测性体系的关系在 Mastra 中可观测性通过mastra/observability包的Observability实例统一管理开发者可以在configs中按服务service注册多个不同的 exporter。mastra/deepeval就是其中的一种 exporter 实现它与仓库中其他导出器如 observability/mastra/src/exporters 下的 console、mastra-platform、cloud 等共享同一套 BaseExporter 抽象基类因此生命周期、日志、禁用状态等通用能力由基类统一提供DeepEval 导出器只需实现具体的 trace 转换逻辑。二、安装在 Mastra 项目中通过包管理器安装npm install mastra/deepeval使用 pnpm仓库本身是 pnpm workspace则执行pnpm add mastra/deepeval安装完成后需要确保项目中已存在mastra/core与mastra/observability依赖通常 Mastra 应用已自带。三、快速开始注册 DeepEvalExporter在创建Mastra实例时通过Observability的configs字段注册导出器。官方 README 给出的最小可用示例位于 observability/deepeval/README.mdimport { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { DeepEvalExporter } from mastra/deepeval; export const mastra new Mastra({ observability: new Observability({ configs: { deepeval: { serviceName: my-service, exporters: [new DeepEvalExporter()], }, }, }), });配置要点说明configs是一个以服务名如deepeval为键的映射值为该服务的配置对象serviceName用于标识当前服务在 Confident AI 中的名称方便按服务维度筛选 traceexporters数组中可以挂载一个或多个导出器实例这里传入new DeepEvalExporter()环境变量CONFIDENT_API_KEY必须在创建 exporter 之前设置详见下一节。注意configs中的键名deepeval仅是本示例中的服务命名实际使用中可自由命名真正决定导出目标的是exporters数组中的DeepEvalExporter实例。四、环境变量与认证DeepEval 导出器通过环境变量完成认证与运行环境标识环境变量是否必填作用CONFIDENT_API_KEY必填Confident AI 平台 API Key用于身份认证CONFIDENT_TRACE_ENVIRONMENT可选指定 trace 所属的运行环境如 production / staging / development从 CHANGELOG 的发布说明可以确认设置CONFIDENT_API_KEY并可选设置CONFIDENT_TRACE_ENVIRONMENT后即可发送 traces。也可以在创建导出器时通过配置对象显式传入apiKey其优先级高于环境变量见下文配置项。未配置 API Key 时的行为这是一个容易被忽略但重要的行为细节。从 tracing.test.ts 的测试用例可以看到当环境中不存在CONFIDENT_API_KEY且未显式传入apiKey时导出器会进入禁用disabled状态——所有 tracing 事件被直接丢弃测试断言captured长度为 0同时通过console.warn输出告警。这意味着应用不会因缺少 Key 而崩溃但 trace 数据也不会被导出因此排查问题时优先检查该告警日志。五、配置项详解DeepEvalExporterConfigDeepEvalExporterConfig是导出器的完整配置类型由两部分合并而成见 tracing.tsexport interface DeepEvalExporterConfig extends BaseExporterConfig, DeepEvalCoreConfig {}即Mastra 侧通用的BaseExporterConfig DeepEval SDK 侧的DeepEvalCoreConfig。5.1 来自 BaseExporterConfig 的通用配置这些配置由 BaseExporter 基类 定义对所有 Mastra exporter 通用配置项类型默认值说明loggerIMastraLoggerConsoleLogger自定义 Mastra 日志器实例用于输出导出器日志logLevelLogLevel \| debug \| info \| warn \| errorINFO日志级别支持枚举与字符串两种写法字符串会经基类映射为枚举值customSpanFormatter(span) span \| Promisespan无在导出前对每个 span 做自定义转换支持同步与异步函数customSpanFormatter是扩展性最强的钩子典型用法包括从结构化 AI SDK 消息中抽取纯文本以便于阅读、按目标平台要求转换输入/输出格式、增删特定字段等。基类会在exportTracingEvent流程中自动调用它见 base.ts且转换器抛错时会回退为原始事件并记录 error 日志不会中断导出链路。示例——把 AGENT_RUN span 的输入数组压缩为用户消息纯文本new DeepEvalExporter({ customSpanFormatter: span { if (span.type agent Array.isArray(span.input)) { const userMsg span.input.find(m m.role user); return { ...span, input: userMsg?.content ?? span.input }; } return span; }, });5.2 DeepEval 侧配置DeepEvalCoreConfig这一部分配置由 DeepEval SDK 的 Mastra 集成定义从测试用例中可以确认以下可用字段配置项类型说明apiKeystringConfident AI API Key显式传入时优先于环境变量traceCaptureSink(trace) voidtrace 捕获回调每生成一条完整 trace 即被调用可用于本地观测、测试断言或二次转发threadIdstring默认线程 ID作用于整条 traceuserIdstring默认用户 ID作用于整条 tracetagsstring[]默认标签集合customSpanFormatter见上文与 Base 配置合并后的同一字段此外测试中还体现了 per-request 级别的上下文覆盖能力单个 span 的metadata中可携带threadId、userId、testCaseId、turnId及任意自定义字段如team这些请求级取值会覆盖 exporter 级默认值。这一机制在 tracing.test.ts 中有完整验证。六、源码实现解析一个薄薄的适配层mastra/deepeval的核心实现只有约 38 行见 tracing.tsimport type { InitExporterOptions, TracingEvent } from mastra/core/observability; import { BaseExporter } from mastra/observability; import type { BaseExporterConfig } from mastra/observability; import { DeepEvalExporter as DeepEvalCoreExporter, type DeepEvalExporterConfig as DeepEvalCoreConfig, } from deepeval/integrations/mastra; export interface DeepEvalExporterConfig extends BaseExporterConfig, DeepEvalCoreConfig {} export class DeepEvalExporter extends BaseExporter { name deepeval; readonly #inner: DeepEvalCoreExporter; constructor(config: DeepEvalExporterConfig {}) { super(config); this.#inner new DeepEvalCoreExporter(config); } override init(options: InitExporterOptions): void { this.#inner.init?.(options); } protected async _exportTracingEvent(event: TracingEvent): Promisevoid { await this.#inner.exportTracingEvent(event); } override async flush(): Promisevoid { await this.#inner.flush(); } override async shutdown(): Promisevoid { await this.#inner.shutdown(); } }几个值得注意的实现细节委托模式DeepEvalExporter内部持有一个deepeval/integrations/mastra的DeepEvalCoreExporter实例#inner所有真正的工作都委托给它。Mastra 侧类的作用是实现BaseExporter抽象契约、统一命名name deepeval、打通生命周期方法。生命周期完整代理init(options)在 Mastra 完全配置完成后由框架调用可选钩子_exportTracingEvent(event)基类的抽象方法被exportTracingEvent在未禁用 应用 formatter之后调用flush()强制冲刷缓冲的 span 而不关闭导出器对 Serverless 等请求结束后进程可能被回收的场景尤其有用基类默认实现为空操作此处真正调用 DeepEval 的 flushshutdown()关闭导出器并清理资源。入口导出index.ts 仅一行export * from ./tracing;把DeepEvalExporter与配置类型直接暴露为包级 API。基类提供的通用保障BaseExporter在 base.ts 中定义了标准的导出入口exportTracingEvent先检查isDisabled状态禁用则直接返回再应用customSpanFormatter最后调用子类实现的_exportTracingEvent。同时它还通过setDisabled(reason)支持显式禁用并输出原因日志——这正是缺少 API Key 时静默丢弃事件的实现基础。七、Span 类型映射Mastra 事件如何变成 Confident AI Trace这是整个导出器最核心的数据转换逻辑。根据 tracing.test.ts 中的测试与 CHANGELOG 的说明Mastra 的 Span 类型会映射为 Confident AI 的AGENT、LLM、TOOL、RETRIEVER、CUSTOM等类型并携带模型名称、token 计数、工具调用信息与指标集合。测试覆盖的映射与行为Mastra SpanTypeConfident AI Trace 类型关键字段透传AGENT_RUNagent作为根 span携带input/output、实体名entityNameMODEL_GENERATIONllmmodel、inputTokenCount/outputTokenCount来自 usageTOOL_CALLtoolname、inputParameters并汇总进 trace 的toolsCalledMODEL_CHUNK直接丢弃流式分片 span 不进入最终 trace树形组装测试用例builds an agent trace with a nested LLM spantracing.test.ts演示了标准流程一条AGENT_RUN根 spanisRootSpan: true下挂一个parentSpanId指向它的MODEL_GENERATION子 span两个 span 分别以SPAN_STARTED/SPAN_ENDED事件流式进入导出器后最终产出一条 trace根类型为agent其children中包含类型llm的子节点model为gpt-4o-miniinputTokenCount: 10、outputTokenCount: 5trace 级input为{ question: weather in Tokyo? }output为Sunny.。工具调用汇总用例records tool calls on the tracetracing.test.ts验证TOOL_CALLspan 会成为 agent 根的子节点type: tool, name: get_weather同时被收集进 trace 的toolsCalled数组包含name与inputParameters{ city: Tokyo }便于在 Confident AI 平台上统一查看一次 Agent 运行调用过的所有工具及入参。流式分片处理用例drops streaming event spanstracing.test.ts确认MODEL_CHUNK类型的 span 会被剔除不会出现在最终 trace 的 children 中避免流式输出的大量分片污染 trace 结构。八、用测试锁定行为边界该包的测试文件 tracing.test.ts 采用 vitest 编写通过注入traceCaptureSink回调捕获完整 trace 做断言是理解导出器行为的最佳说明书。七个用例覆盖了继承自BaseExporter且name deepevalAgent 嵌套 LLM span 的树形组装与字段透传工具调用的记录与汇总请求级上下文threadId/userId/testCaseId/turnId/ 自定义 metadata覆盖 exporter 级默认值流式分片 span 被丢弃customSpanFormatter在导出前生效缺少 API Key 时导出器禁用且告警、事件被丢弃。如需运行测试验证行为cd observability/deepeval pnpm test九、适用场景与注意事项适用场景希望将 Mastra Agent 的每次运行含 LLM 调用、工具调用、输入输出发送到 Confident AI 做线上评估evaluation与监控monitoring需要按serviceName、userId、threadId、testCaseId、turnId等维度组织与检索 trace需要自定义 span 内容后再上报customSpanFormatter。注意事项认证依赖CONFIDENT_API_KEY缺失时导出器自动禁用且仅输出警告不会报错中断应用当前包的实现依赖 DeepEval SDKdeepeval依赖约束^0.1.32Node 环境要求22.13.0流式生成产生的MODEL_CHUNKspan 不会进入最终 trace若同时使用多个 exporter注意各 exporter 独立持有自己的缓冲与生命周期flush()/shutdown()需要分别触发。十、总结mastra/deepeval以极轻量的适配层形式将 Mastra 丰富的 tracing 数据无缝对接到 Confident AI开发者只需安装包、设置CONFIDENT_API_KEY、在Observability配置中注册DeepEvalExporter即可获得包含 Agent、LLM、工具调用完整调用链的线上评估数据。其源码实现tracing.ts、测试用例tracing.test.ts与通用基类base.ts共同构成了一条清晰的事件 → formatter → 树形组装 → 上报数据链路值得作为理解 Mastra 可观测性扩展机制的入门范例。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考