Mastra 可观测性实战从 CHANGELOG 读懂 mastra/braintrust 的演进、核心机制与升级迁移【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是面向 AI 应用与 Agent 的现代 TypeScript 框架其可观测性体系通过独立的mastra/observability抽象与各类后端对接mastra/braintrust即是其中用于将 Mastra 全链路 trace 导出到 Braintrust用于 LLM 评估与监控的官方集成包。本文以该包的 CHANGELOG.md 为骨架逐层拆解它从 0.1.0 到 1.3.13-alpha.1 的能力演进包括零配置接入、TrackingExporter缓冲与乱序处理机制、Thread 视图重建、评估分数回传、服务端 flush 等关键能力并结合 tracing.ts、metrics.ts 等源码与仓库内示例给出可直接落地的接入与升级方案。一、包定位与最小接入mastra/braintrust是 Mastra 的 Braintrust 可观测性提供方observability provider官方描述为 “Braintrust observability provider for Mastra - includes tracing and future observability features”。它通过零配置环境变量或显式项目配置将 Mastra 的 trace 导出到 Braintrust 用于 LLM 评估与监控见 README.md。安装npm install mastra/braintrust当前包的依赖与运行前提见 package.json运行时依赖mastra/observabilityworkspace 内联、braintrust^3.24.0v1.3.4 起从^3.22.0升级而来peerDependenciesmastra/core1.16.0-0 2.0.0-0、zod^3.25.34 || ^4.0.0引擎要求node 22.13.0该门槛由 1.0.0 版本确立。最小接入示例在 Mastra 实例上挂载Observability并在configs.braintrust中配置serviceName与exporters源自 README.md 的 Usage 示例import { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { BraintrustExporter } from mastra/braintrust; export const mastra new Mastra({ observability: new Observability({ configs: { braintrust: { serviceName: my-service, exporters: [new BraintrustExporter()], }, }, }), });注意从 1.0.0 起可观测性配置要求显式导入并实例化Observability传入实例而非纯对象这是早期版本的破坏性变更之一详见下文“稳定版 1.0.0 的重大变更”。二、零配置环境变量驱动CHANGELOG 在 1.0.0 版本中引入了 “zero-config environment variable support for all exporters” 能力PR #11686所有可观测性导出器都支持通过环境变量零配置启动实例化导出器时无需任何参数。对 Braintrust 而言涉及两个环境变量BRAINTRUST_API_KEYBraintrust API KeyBRAINTRUST_ENDPOINT自定义端点地址。在 tracing.ts 的构造函数中可以看到这一机制的实际落地——配置解析发生在调用父类构造函数之前constructor(config: BraintrustExporterConfig {}) { // Resolve env vars BEFORE calling super (config is readonly in base class) const resolvedApiKey config.apiKey ?? process.env.BRAINTRUST_API_KEY; const resolvedEndpoint config.endpoint ?? process.env.BRAINTRUST_ENDPOINT; super({ ...config, apiKey: resolvedApiKey, endpoint: resolvedEndpoint, }); // ... }因此可以直接这样写// 零配置从环境变量读取 BRAINTRUST_API_KEY / BRAINTRUST_ENDPOINT new BraintrustExporter();优先级规则显式配置优先于环境变量若两者都未提供 API Key导出器会通过setDisabled()进入禁用态并输出提示信息“SetBRAINTRUST_API_KEYenvironment variable or pass apiKey in config”见 tracing.ts。三、BraintrustExporterConfig配置项全景结合 tracing.ts 与 CHANGELOGBraintrustExporterConfig除继承TrackingExporterConfig外还包含配置项类型说明braintrustLoggerBraintrustLogger可选的 Braintrust logger 实例。提供后可启用上下文集成Agent 的 trace 可自动嵌套进Eval()/logger.traced()/ 外部父 spancurrentSpan() BraintrustSpan \| undefined当前活跃 span 解析器。当应用与 Mastra 各自解析到不同副本的braintrust包时传入同一包实例的currentSpan可保证评估 trace 正确嵌套1.1.0 新增apiKeystringBraintrust API Key未提供 logger 时必填endpointstring可选自定义端点projectNamestringBraintrust 项目名默认mastra-tracingtuningParametersRecordstring, any传给 Braintrust logger 的调优参数继承自TrackingExporterConfig的内存管理参数1.0.0 版本引入了TrackingExporter基类PR #11870改进了三类问题乱序 span 处理先于父 span 到达的 span 会被排队待依赖可用后再处理延迟清理span 结束后 trace 数据保留一小段时间以处理迟到更新内存管理对 pending 与 total trace 设置可配置上限防止内存泄漏。TrackingExporterConfig新增的配置项及默认值在 CHANGELOG 中明确给出配置项默认值作用earlyQueueMaxAttempts5排队事件的最大重试次数earlyQueueTTLMs30000排队事件的 TTL毫秒traceCleanupDelayMs30000完成 trace 的清理延迟毫秒maxPendingCleanupTraces100等待清理 trace 的软上限maxTotalTraces500trace 总数的硬上限mastra/braintrust、mastra/langfuse、mastra/langsmith、mastra/posthog均改用该基类。四、核心机制从 span 到 Braintrust trace 的映射1. Span 类型映射Braintrust 接受llm | score | function | eval | task | tool六种 span 类型。默认映射为task例外见 tracing.tsMastraSpanTypeBraintrust 类型MODEL_GENERATIONllmTOOL_CALL/MCP_TOOL_CALL/PROVIDER_TOOL_CALLtoolWORKFLOW_CONDITIONAL_EVAL/WORKFLOW_WAIT_EVENTfunction其他task1.2.4 版本还专门为PROVIDER_TOOL_CALL补充了导出器 span 类型映射与时长指标PR #19261使由 provider 执行工具产生的 span 在所有可观测平台上都被归类为工具 span。2. 指标映射与 TTFTtracing.ts 中MODEL_GENERATIONspan 的 usage 指标通过 metrics.ts 的formatUsageMetrics()转换。Braintrust 期望的规范指标键与 MastraUsageStats的对应关系如下Braintrust 指标键来源UsageStatsprompt_tokensinputTokenscompletion_tokensoutputTokenstokens两者之和自动计算completion_reasoning_tokensoutputDetails.reasoningprompt_cached_tokensinputDetails.cacheReadprompt_cache_creation_tokensinputDetails.cacheWriteTime-to-first-tokenTTFT1.0.0 版本引入time_to_first_token指标PR #10840由流式首个 chunk 到达时捕获的completionStartTime填充单位为秒if (modelAttr.completionStartTime) { payload.metrics.time_to_first_token (modelAttr.completionStartTime.getTime() - span.startTime.getTime()) / 1000; }流式调用无需额外代码即可自动上报const result await agent.stream(Hello); // time_to_first_token 作为 span metrics 自动发送到 Braintrust此外1.0.0 中同时修复了 CachedToken 跟踪PR #11029缓存 token 计数在所有可观测性导出器中统一修正Braintrust 的 TTFT 也被纳入修复范围。3. 消息格式转换与 Thread 视图Braintrust 的 Thread 视图要求输入/输出遵循其期望的消息格式Mastra 的 span 数据需要做多层转换输入转换transformInputtracing.ts将{ messages: [...] }解包为直接数组并把 AI SDKv4/v5消息转换为 OpenAI Chat Completion 格式修复 #11023输出转换transformOutput将{ content: ... }解包为{ role: assistant, content: text }字符串形式工具调用重构thread-reconstruction.tsbuildModelGenerationPayload当 LLM 生成包含工具调用时导出器通过检查子MODEL_STEP与TOOL_CALLspan以 OpenAI Chat Completion 格式重建完整对话流使 Thread 视图正确展示包含工具调用与结果的完整会话1.0.0PR #11984AI SDK 消息转换增强1.0.0PR #11673支持非文本内容类型图片、文件、reasoning用信息占位符展示同时兼容 AI SDK v4 的result与 v5 的output字段并优雅处理空内容数组与未知内容类型。4. 工具结果配对toolCallId 解析1.3.2 版本修复了可观测性导出器对toolCallId的读取PR #19405从 span attributes 读取含 metadata 回退Braintrust Thread 视图通过真实工具调用 ID 配对工具结果。resolveToolCallId()的解析优先级见 tracing.tsattributes.toolCallId→metadata.toolCallId→input.toolCallId→span.id。5. 反馈与评估分数logFeedback1.0.0 版本修复了logFeedback()失效的问题PR #11927。根因是startSpan()调用传入了spanId: span.id但遗漏了event: { id: span.id }导致 Braintrust 为 rowid字段自动生成不同的 UUID用户反馈因此成为独立行而非挂到原始生成记录上。修复方案是让 Mastra span ID 同时充当 Braintrust 的span_id与 rowid见 tracing.ts。评估分数通过onScoreEvent()上报tracing.tsscore 事件被转换为logger.logFeedback({ id: rowId, scores, comment, metadata, source: external })其中rowId取score.spanId ?? score.traceIdscorer 名称/ID 作为分数键。1.1.0 版本还实现了Mastra Eval 结果转发到 BraintrustPR #16185并新增current span 解析器选项解决应用与 Mastra 解析不同 Braintrust SDK 副本时评估 trace 无法正确嵌套的问题。五、服务端与长生命周期运行flush()1.0.0 版本为所有可观测性导出器与实例新增flush()方法PR #12003专为 serverless 环境设计例如 Vercel fluid compute 中运行时实例可跨请求复用flush 缓冲区中的 span 但不关闭导出器区别于shutdown()后者释放资源且阻止后续导出。// 通过 observability 实例刷新所有导出器 const observability mastra.getObservability(); await observability.flush(); // 或刷新单个导出器 const exporters observability.getExporters(); await exporters[0].flush();在 serverless 环境中应在运行时实例终止前调用 flush同时保持导出器对后续请求可用。六、工作流挂起/恢复与 trace 分组1.3.61.3.6 版本修复了挂起suspended与恢复resumed的工作流运行在 Braintrust 中显示为两条断裂 trace 的问题修复 #20771PR #21047挂起并恢复的工作流运行现在出现在一条Braintrust trace 中恢复的运行嵌套在其被挂起时所在的 span 之下Braintrust trace 改为按Mastra trace ID分组而非随机 ID因此多个共享显式 trace ID 的运行会显示为一条 Braintrust trace。其实现位于rootParentSpanIds()tracing.ts把rootSpanId固定为 Mastra trace ID使共享 trace 的每个 root 落入同一条 Braintrust trace仅当 span 携带 core 标记的resumedFromSpanId恢复的续段时才链接到其持久化父 span其余 root 保持空的span_parents。升级注意事项CHANGELOG 原文要点在升级前挂起、升级后恢复的运行仍会显示为两条 trace——旧半段按随机 ID 分组新版本无法恢复且恢复半段可能缺少根 span。只有跨越升级的在途运行受影响同一版本内挂起并恢复的运行不受影响。如果在意这条数据请在升级前排空挂起的运行。七、稳定版 1.0.0 的重大变更1.0.0 标志着该包进入稳定阶段伴随多项破坏性变更Node.js 最低版本提升至 22.13.0PR #9706可观测性配置 API 变更PR #9709必须显式导入并实例化Observabilityimport { Mastra } from mastra/core; import { Observability } from mastra/observability; // 显式导入 const mastra new Mastra({ ...other_config, observability: new Observability({ default: { enabled: true }, }), // 传入实例 });替代旧写法import mastra/observability/init 传入纯对象命名统一Tracing相关命名改为Observability去掉AI-前缀ai-tracing 代码整体迁入mastra/observabilityPR #9661span 类型重命名PR #9105LLM前缀改为Model前缀以反映其适用于所有 AI 模型而非仅大语言模型例如AISpanType.LLM_GENERATION→AISpanType.MODEL_GENERATION、LLMGenerationAttributes→ModelGenerationAttributes、InternalSpans.LLM→InternalSpans.MODEL新增TrackingExporter基类PR #11870前述乱序处理、延迟清理与内存上限参数均在此版本引入trace 标签支持PR #10765Braintrust 与 Langfuse 导出器新增 trace tagging嵌入文档支持PR #11472发布包在dist/docs/下附带SKILL.md、SOURCE_MAP.json与主题文档供编码 Agent 直接阅读node_modules中的说明。八、1.3.0Braintrust SDK v2 → v3 迁移1.3.0 是紧随稳定版之后的又一次关键升级PR #19507Breaking change内置 Braintrust SDK 从 v2 升级到 v3并将 SDK 专属的 logger 与 span 类型替换为稳定的 Mastra 接口/垫片shims兼容的 Braintrust v2 与 v3 logger、span 对象仍受支持v3 使用独立的 W3C trace ID 作为root_span_idMastra 返回的spanId仍作为 Braintrust 的 row ID 与 span ID用于 feedback 与查找BraintrustExporterConfig接口发生变更若使用braintrustLogger字段或getCurrentSpan()方法其类型已收窄、不再与 Braintrust SDK 绑定官方评估“通常不会影响你”但属于技术上破坏性变更独立升级 Braintrust 且使用 Nunjucks 提示词模板的应用应遵循 Braintrust 官方 v2→v3 迁移指南。与此呼应依赖版本的演进轨迹来自 CHANGELOG为braintrust^0.3.6→^0.3.80.1.4→^0.4.91.0.0-beta.1→^1.1.01.0.0-beta.8→^2.2.01.0.3→^3.22.01.3.4-alpha.0→^3.24.01.3.4。九、实战上下文感知接入Eval 与 logger.traced当braintrustLogger配置为外部 logger 后_buildRoot()tracing.ts会按以下顺序寻找挂载点① 配置的currentSpan()解析结果 → ② Braintrust 自身的currentSpan()→ ③ 回退到提供的 logger。这使得 Mastra 的 Agent trace 能自动嵌套进外层 Braintrust span。场景一Mastra 与 Braintrust Eval 结合仓库示例 observability/braintrust/examples/with-eval.ts 展示了 Agent trace 自动嵌套进Eval()任务 spanconst logger initLogger({ projectName: mastra-demo, apiKey: process.env.BRAINTRUST_API_KEY, appUrl: process.env.BRAINTRUST_API_URL, }); const exporter new BraintrustExporter({ braintrustLogger: logger }); const mastra new Mastra({ agents: { assistant: new Agent({ name: Assistant, instructions: Be concise., model: openai/gpt-4o-mini }) }, observability: new Observability({ configs: { braintrust: { serviceName: demo, exporters: [exporter] } }, }), }); await Eval(mastra-demo, { data: () [ { input: What is the capital of France?, expected: Paris }, { input: What is 22?, expected: 4 }, ], task: async (input: string) { const agent mastra.getAgent(assistant); return (await agent.generate(input)).text; }, scores: [ (args: any) ({ name: contains_answer, score: String(args.output).toLowerCase().includes(String(args.expected).toLowerCase()) ? 1 : 0, }), ], });运行后在 Braintrust 项目mastra-demo中即可看到带分数的评估结果、嵌套在每个评估任务内的 Mastra Agent trace以及完整的模型调用与工具使用轨迹。场景二logger.traced()手动包裹仓库示例 observability/braintrust/examples/with-logger-traced.ts 展示为不同环境建立带标签的父 spanfor (const env of [production, staging, development]) { await logger.traced(async span { span.log({ tags: [environment:${env}], metadata: { environment: env }, }); const agent mastra.getAgent(demo); const response await agent.generate(Say hi); console.log(${env}: ${response.text}); }); }对应配置的currentSpan传参方式为new BraintrustExporter({ braintrustLogger: logger, currentSpan })其中currentSpan应来自与应用创建Eval()/logger.traced()span 相同的包实例以保证在存在多副本 Braintrust SDK 时 trace 仍正确嵌套。此外包内还提供 examples/basic.ts 基础示例package.json 中预置了可直接运行的脚本pnpm example:basic、pnpm example:traced、pnpm example:eval。十、版本演进中的关键修复时间线以下是 CHANGELOG 中可核验的重要修复按版本梳理版本关键变更0.1.0BraintrustExporter初始发布用于 ai-observability0.1.4修复 braintrust 导出器乱序 span依赖升至^0.3.80.1.7traceId 作为 root_span_id保留 Mastra span ID 导出1.0.0稳定版Node 22.13.0、Observability API、TrackingExporter、TTFT、flush()、零配置环境变量、Thread 视图系列修复、logFeedback 修复1.1.0current span 解析器选项Mastra Eval 结果转发至 Braintrust1.2.4工具调用不再显示为unknown_tool真实工具名 配对结果PROVIDER_TOOL_CALL纳入工具类型映射1.3.0Braintrust SDK v2→v3BraintrustExporterConfig接口变更1.3.2导出器统一从 span attributes含 metadata 回退读取toolCallId1.3.6挂起/恢复工作流运行合并为单条 Braintrust trace按 Mastra trace ID 分组1.3.10更新 README从 npm 分发文件中移除 CHANGELOG 以减小包体积PR #22737十一、升级与排障速查API Key 缺失导出器会进入禁用态优先检查BRAINTRUST_API_KEY环境变量或apiKey配置升级 1.3.0 前若独立升级 Braintrust 且使用 Nunjucks 模板先完成 Braintrust v2→v3 迁移braintrustLogger/getCurrentSpan()的类型已收窄确认兼容跨越 1.3.6 升级若存在在途的挂起工作流运行先排空再升级避免产生无法合并的历史 trace 半段serverless 掉 trace在运行时实例被回收前调用observability.flush()而非shutdown()以保留后续请求的导出能力Thread 视图显示异常确认版本 ≥1.0.0覆盖消息格式转换、工具调用重构与 AI SDK v4/v5 兼容工具结果配对依赖toolCallId若仍异常可检查 span attributes 中的toolCallId是否被正确写入1.3.2 起统一读取。总体而言mastra/braintrust的演进主线清晰从早期的“能导出”逐步走向“导出得准确、可嵌套、可评估、可运维”——span 类型映射与指标格式标准化、Thread 视图消息重建、trace 分组语义Mastra trace ID以及 serverless flush 机制都是把通用 observability 语义无损翻译为 Braintrust 原生结构的关键设计值得在接入或移植到其他可观测平台时对照参考。附进一步阅读的仓库入口包说明与最小示例observability/braintrust/README.md完整版本历史observability/braintrust/CHANGELOG.md导出器核心实现observability/braintrust/src/tracing.ts指标映射observability/braintrust/src/metrics.ts消息格式转换observability/braintrust/src/formatter.tsThread 视图重建observability/braintrust/src/thread-reconstruction.ts嵌套场景测试observability/braintrust/src/braintrust-nesting.test.ts实战示例observability/braintrust/examples/basic.ts、observability/braintrust/examples/with-eval.ts、observability/braintrust/examples/with-logger-traced.ts【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考