Mastra Observability 演进全解mastra/observability 的追踪、指标、成本与数据脱敏能力指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraMastra 是面向 AI 应用与 Agent 的现代 TypeScript 框架而mastra/observability仓库中的 observability/mastra 目录正是其可观测性核心包它提供层次化 trace、自动提取的指标、与当前 trace 关联的结构化日志以及对 Mastra 平台与各类第三方后端的导出能力。本文以该包从0.0.2占位包到1.17.8-alpha.1的完整演进记录observability/mastra/CHANGELOG.md为骨架结合仓库源码为你梳理mastra/observability的核心概念、内置导出器、敏感数据过滤、span 生命周期管理、指标与成本估算等关键机制帮助你在自己的 Mastra 应用中把 Agent、工作流、工具与模型调用“看得清清楚楚”。包定位与快速上手mastra/observability的定位在 observability/mastra/README.md 中写得很明确为 Agent 运行、模型生成、工具与 MCP 调用、处理器执行、工作流运行与工作流步骤提供埋点。每个配置的 observability 实例都有自己的服务名、导出器、采样策略与 span 处理器导出器通过中央 observability bus 接收追踪事件。安装与最小配置npm install mastra/observabilityimport { Mastra } from mastra/core; import { Observability, MastraStorageExporter, MastraPlatformExporter } from mastra/observability; export const mastra new Mastra({ observability: new Observability({ configs: { default: { serviceName: my-app, exporters: [new MastraStorageExporter(), new MastraPlatformExporter()], }, }, }), });其中MastraStorageExporter把事件持久化到配置的 Mastra storage供 Studio 查询MastraPlatformExporter把数据上传到 Mastra 平台Arize、Braintrust、Langfuse、LangSmith、Sentry 以及兼容 OpenTelemetry 的后端则由额外包提供。说明该包当前版本为1.17.8-alpha.1见 observability/mastra/package.json本文涉及的 API 以仓库中实际代码与 CHANGELOG 记录为准。从占位包到稳定版一条完整的演进主线CHANGELOG 忠实地记录了该包从零到成熟的路线理解这条主线能帮你判断“某个能力为什么长这样”。0.0.2占位包包创建时只是空占位等待从其他包迁移 AI tracing 与 scorer 代码PR #9051。1.0.0首个稳定版a最低 Node.js 版本提升到22.13.0b把 ai-tracing 代码正式迁入mastra/observabilityPR #9661c全面去掉 “AI-” 前缀、Tracing更名为ObservabilityPR #9744例如原来的mastra/observability/init副作用导入被改为显式构造Observability实例传入new Mastra({ observability: ... })PR #9709dOUTPUT泛型从OutputSchema约束改为普通泛型为后续标准 schema 方案铺路PR #11741。1.3.0引入ObservabilityBus内置 promise 跟踪与 flush 支持修复了 durable execution 场景下 span 丢失的问题#13388。同期带来自动指标agent run、工具调用、工作流的 duration/count 指标、结构化日志上下文LoggerContext 把日志自动关联到父 trace/span、以及防高基数标签冲击指标后端的 CardinalityFilter。1.6.0加入成本估算能力——内置各厂商定价数据为自动提取的模型 token 指标做运行时成本估算并让成本上下文在指标与导出器之间传播PR #14609要求mastra/core 1.17.0-0。同版本还支持通过mastra.observability.getRecordedTrace({ traceId })加载已持久化的 trace并追加 score 与 feedback。1.12.0重要转折a两个内置导出器更名——CloudExporter→MastraPlatformExporter、DefaultExporter→MastraStorageExporter旧名仍导出但已弃用bSensitiveDataFilter默认自动生效c新增MODEL_INFERENCEspan 类型挂在MODEL_STEP之下只覆盖模型 provider 调用用于单独度量模型延迟。1.17.x近期围绕 span 树完整性endTree、敏感数据过滤的稳定性requestContext脱敏、indexed风格 token 稳定性、Mastra 平台配额暂停协议quota-pause等持续打磨。从源码结构也能印证这一演进src/bus/ObservabilityBus、src/exporters/base、mastra-storage、mastra-platform、tracking、event-buffer、auth-failure-cooldown、src/metrics/pricing-registry、estimator、auto-extract、cardinality、src/span_processors/sensitive-data-filter等模块与 CHANGELOG 记录的能力一一对应。核心配置实例、采样、过滤与序列化ObservabilityInstanceConfig 关键字段observability/mastra/src/config.ts 定义了ObservabilityInstanceConfig常用字段如下字段作用说明/默认值name实例在 registry 中的唯一标识必需serviceName追踪的服务名必需sampling采样策略默认ALWAYSexporters自定义导出器数组如MastraStorageExporter、MastraPlatformExporterbridge可观测性桥接如 OpenTelemetry 上下文提取可选spanOutputProcessorsspan 输出处理器如SensitiveDataFilter可选includeInternalSpans是否导出 Mastra 内部 span默认falseexcludeSpanTypes按类型剔除 span降低按 span 计费平台的开销如[SpanType.MODEL_CHUNK, SpanType.MODEL_STEP]spanFilter细粒度谓词过滤返回false即丢弃在excludeSpanTypes与输出处理器之后运行requestContextKeys从 RequestContext 自动提取为 span metadata 的键支持点号嵌套可选serializationOptions序列化截断限制maxStringLength、maxDepth、maxArrayLength、maxObjectKeys见下文默认值采样策略SamplingStrategy支持四种类型同样定义在 config.ts{ type: always }——全部保留默认{ type: never }——全部丢弃{ type: ratio, probability }——按概率采样{ type: custom, sampler }——自定义采样函数接收requestContext与metadata。一个值得注意的修复1.0.0PR #11676采样决策在根 span 层面只做一次子 span 继承父 span 的采样结果自定义 sampler 每条 trace 只调用一次保证要么整条 trace 被采样、要么整条被丢弃避免出现“同一 trace 内部被拆散”的碎片化现象。对应测试见 trace-level-sampling.test.ts。序列化限制1.2.0 起默认maxStringLength从 1KB 提高到128KB、maxDepth从 6 提高到8避免大 prompt 与长回复被截断如需恢复旧行为serializationOptions: { maxStringLength: 1024, maxDepth: 6, }1.8.0 起deepClean()会作用于所有信号logs、metrics、scores、feedback并且在ObservabilityBus.emit()中统一执行保证离开 bus 的每个信号都是“有界且 JSON 安全”的同时deepClean()开始保留Map转为 entries 对象、Set转为数组以及更完整的Error保留stack与递归清洗后的cause。另外注意deepClean()对new Set([...])的兼容处理1.2.1PR #13322避免打包器把 Set 转成普通对象后触发keysToStrip.has is not a function崩溃。内置导出器与事件总线ObservabilityBus事件总线是导出器接收事件的枢纽。1.5.0 起ObservabilityBus构造函数改为接收配置对象cardinalityFilter、autoExtractMetrics原来的setCardinalityFilter()、enableAutoExtractedMetrics()被移除PR #142141.13.0 起MastraStorageExporter在无法持久化事件时也会像DefaultExporter一样通知自定义导出器与集成PR #16755。相关实现见 src/bus/observability-bus.ts。MastraStorageExporter原 DefaultExporter负责把 span 持久化到配置的 storage让 Studio 可以查询。其健壮性演进包括1.2.1修复默认导出器初始化完成前 span 被静默丢弃的问题导出器先在内存中持有 span初始化完成后统一传播到追踪后端PR #12936。1.16.1存储导出器会立即上报持久化失败并按配置的指数退避自动重试失败的批次PR #19259。1.17.2若启动时配置的 observability store 暂时不可用导出器不再保持禁用而是在后续事件到达时自动恢复PR #21957。MastraPlatformExporter原 CloudExporter负责向 Mastra 平台批量上传全部五类信号traces、logs、metrics、scores、feedback1.8.0PR #15124。源码见 src/exporters/mastra-platform.ts其关键行为批量配置maxBatchSize默认 1000、maxBatchWaitMs默认 5000、maxRetries默认 3。端点推导默认对 traces 使用/spans/publishlogs/logs/publishmetrics/metrics/publishscores/scores/publishfeedback/feedback/publish未设置projectId时走 JWT 风格/ai/{signal}/publish设置后走/projects/:projectId/ai/{signal}/publish1.9.0PR #15189。配额暂停协议quota-pause1.16.6 起当平台以402 Payment Required和x-mastra-observability: disabled头拒绝发布请求时导出器会停止上传、本地丢弃事件而非重试并按x-mastra-observability-retry-after提示默认每 5 分钟周期探测平台重新启用后自动恢复导出PR #21160。1.17.1 起该能力通过x-mastra-observability-capabilities: quota-pause-v1头在每个请求上声明PR #21447以区分能理解契约的新客户端与只能盲目重试的旧客户端。认证失败冷却1.14.0 起凭据无效时暂停上传避免反复发送未授权请求PR #16743相关逻辑在 src/exporters/auth-failure-cooldown.ts。环境变量方面1.17.4 修复了MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT被忽略的问题现在可以作为 observability 端点覆盖其他信号端点由它推导# 基础 origin其余信号端点由此推导 MASTRA_PLATFORM_OBSERVABILITY_ENDPOINThttps://observability.eu.mastra.ai # 或完整的 traces 发布 URL MASTRA_PLATFORM_OBSERVABILITY_ENDPOINThttps://observability.eu.mastra.ai/spans/publish遗留的MASTRA_CLOUD_TRACES_ENDPOINT仍然有效且两者同时设置时它优先。token 方面1.12.0 起MASTRA_PLATFORM_ACCESS_TOKEN是首选环境变量MASTRA_CLOUD_ACCESS_TOKEN作为向后兼容的回退PR #16500。TrackingExporter 与 EventBuffer1.0.0 引入TrackingExporter基类PR #11870专门处理三类问题乱序 span先于父 span 到达的 span 进入队列依赖就绪后处理延迟清理trace 结束后短暂保留数据以承接迟到的更新内存管理对 pending 与总 trace 数量设限。其可配置项与默认值earlyQueueMaxAttempts: 5、earlyQueueTTLMs: 30000、traceCleanupDelayMs: 30000、maxPendingCleanupTraces: 100、maxTotalTraces: 500。mastra/braintrust、mastra/langfuse、mastra/langsmith、mastra/posthog均已迁移到该基类。1.5.0 还新增EventBuffer用于以可配置的 flush 间隔批量发送非追踪信号PR #14214。此外customSpanFormatter允许为单个导出器做 span 变换支持同步与异步包括异步数据富化并可用chainFormatters组合多个格式化器PR #11985import { DefaultExporter, chainFormatters } from mastra/observability; import { SpanType } from mastra/core/observability; import type { CustomSpanFormatter } from mastra/core/observability; const plainTextFormatter: CustomSpanFormatter span { if (span.type SpanType.AGENT_RUN Array.isArray(span.input)) { const userMessage span.input.find(m m.role user); return { ...span, input: userMessage?.content ?? span.input }; } return span; }; const exporter new DefaultExporter({ customSpanFormatter: plainTextFormatter });SensitiveDataFilter默认开启的敏感数据脱敏1.12.0 起Observabilityregistry 会自动为每个实例套用SensitiveDataFilterPR #16234API key、token、密码等秘密在到达导出器之前就被脱敏。顶层sensitiveDataFilter选项控制该行为true默认以默认选项应用过滤器false关闭自动过滤传入SensitiveDataFilterOptions对象自定义敏感字段、脱敏 token 与脱敏风格。若配置里已经显式包含SensitiveDataFilter自动套用会被跳过以避免双重脱敏预实例化的ObservabilityInstance不会被修改。实现见 src/span_processors/sensitive-data-filter.ts其默认敏感字段包括password、token、secret、key、apikey、auth、authorization、bearer、bearertoken、jwt、credential、clientsecret、privatekey、refresh、ssn匹配时大小写不敏感且会归一化分隔符api-key、api_key、Api Key都会被识别。三种脱敏风格风格行为示例full默认一律替换为redactionToken[REDACTED]partial保留首尾各 3 个字符中间脱敏abc...xyzindexed每个唯一值获得稳定的[LABEL_N]token[APIKEY_1]indexed风格1.17.0PR #21328最有价值它在不暴露原始值的前提下让同一 secret 在 trace 内保持可关联。其内部状态以 SHA-256 摘要为键避免在内存中保留明文每条 trace 最多跟踪 1000 个唯一值、最多保留最近 1000 条 trace 的状态达到上限后新值回退到完整脱敏 token。CHANGELOG 中记录了不少围绕该过滤器的坑与修复值得留意过滤器同时作用于 span 的attributes、metadata、input、output、errorInfo与requestContext1.17.6 修复了requestContext里的敏感字段例如工具使用的按请求 API token此前被明文导出到所有追踪导出器的问题PR #23055。1.17.6 修复indexed风格 token 漂移span 会因span_started、span_updated、span_ended多次被处理旧实现会把自身产出的[APIKEY_1]当作新 secret 再次替换成[APIKEY_2]现在已脱敏值保持原 tokenPR #23057。过滤器会解析并脱敏 JSON 字符串中的敏感字段1.0.0PR #10776同时会跳过不可能的 JSON 前缀以避免反复解析异常1.17.6PR #23314。1.0.0 修复了过滤器破坏Date对象的问题——Object.keys(new Date())返回空数组导致 Date 被误转成{}进而影响依赖getTime()的导出器PR #11437。Span 生命周期endTree、异常关闭与桥接释放span 生命周期管理是近期版本的重头戏核心目标是“trace 必须完整、绝不能悬空”。endTree整树关闭1.17.2 引入span.endTree()PR #22278用于在“操作被放弃而非完成”的场景下仍输出完整 trace// 结束该 span 及其下所有仍开放的子 span并给每个被强制关闭的 span 打上标记 workflowSpan.endTree({ attributes: { status: canceled } });传入的选项会应用到它所关闭的每一个 span因此被强制关闭的子 span 可以与正常结束的 span 区分开。同时重复调用span.end()会被忽略——被整树关闭的 span 保持其关闭状态即使其覆盖的工作后续真正结束也不会再次上报。对应测试见 src/spans/end-tree.test.ts。异常结束时的 span 树收拢1.17.6 修复了 Agent 运行异常结束时泄漏开放 span 的问题PR #22764Errors、aborts、suspensions、tripwires、prepare failures 现在都会关闭整棵 span 树提前结束的 span 会把自己仍开放的子 span 交给最近的存活祖先。这对“等待每个 span 都结束”的导出器如 Datadog很重要——否则 trace 及其 payload 会永远驻留内存。该版本还同步在span.end()与span.error()上提供了endTree选项。未导出 span 的状态释放1.16.4 修复了一个隐蔽问题PR #20463被excludeSpanTypes、spanFilter或 span 输出处理器丢弃的 span 不会发出 span-end 事件导致mastra/otel-bridge、mastra/datadog等桥接器一直持有其状态直到进程关闭。现在这些 span 会触发桥接器的releaseSpan调用导出行为不变被过滤的 span 仍不导出、trace 结构不受影响。Studio 中的日志/指标 span 链接1.17.3 修复了从 Studio 的日志或指标详情打开 span 时出现的 “Span not found.” 错误PR #22286在 internal 或被排除 span 内部发出的日志与指标之前被打上该 span 自己的 id而这些 span 在导出前就被丢弃导致 404。现在日志与指标会解析到“真正到达导出器的最近祖先 span”没有这样的祖先时干脆省略spanId。自动指标、成本估算与基数控制自动提取的指标1.3.0 起ObservabilityBus 会根据 span 生命周期自动派生指标Agent 运行、工具调用、工作流的时长与计数指标都带有结构化标签。1.8.0 的excludeSpanTypes/spanFilter虽会减少 span 导出但 1.15.1 明确修复了“被过滤的 span 其自动指标不应随之消失”的问题PR #18253——metrics 的发射独立于 span 导出过滤。相关实现见 src/metrics/auto-extract.ts。token 与成本相关的指标例如mastra_model_total_input_tokens/mastra_model_total_output_tokens在 1.6.0 起会包含基于已成功定价明细桶估算出的成本PR #14674。成本估算与定价数据成本估算依赖 src/metrics/pricing-registry.ts、src/metrics/estimator.ts 与内置定价快照 src/metrics/pricing-data.jsonl。CHANGELOG 里有一长串围绕“模型名对不上定价表”的修复体现其匹配策略的演进1.16.2provider 名归一化如openai.chat→openai以匹配定价数据键PR #14716AI SDK provider 名与内置定价数据不一致时也能估算PR #19513。1.17.1修复 Anthropic 缓存写入cache-write成本估算按 TTL 应用费率且不重复计算聚合 tokenPR #21563。1.9.1模型名带日期后缀如gpt-5.4-mini-2026-03-17时尝试剥掉日期后缀、把点转成短横线等多种变体PR #15349。1.7.1回退到点转短横线归一化gpt-5.2→gpt-5-2解决 Azure 部署的no_matching_modelPR #14959。1.14.1OpenRouter 带厂商前缀与点号版本的 id如google/gemini-2.5-flash也能正确匹配PR #17140。1.15.2provider 回报的响应模型匹配不上定价表但配置模型能匹配时回退到配置模型再报告no_matching_modelPR #16585。此外1.14.1 还支持外部 SDK Agent 集成自带成本当 SDK agent 在其模型生成 span 上记录了估算成本时observability 会把它带到自动提取的模型 token 指标上即使 Mastra 无法用自身定价表计算PR #16906。CardinalityFilter自动指标标签会经过 src/metrics/cardinality.ts 的基数过滤防止 user id、trace id 等无界值淹没指标后端1.3.0PR #13612。指标查询与可观测性存储1.14.1 补充了如何从 observability store 查询与检索指标数据的文档能力PR #17178开发者可以了解如何聚合指标、按标签拆解、可视化时间序列、计算百分位数途径包括进程内 store API、HTTP 端点或 CLI 命令。1.10.0 起所有可观测性信号logs、metrics、scores、feedback都获得唯一 IDlogId、metricId、scoreId、feedbackId在发射时自动生成用于框架管线的去重与跨系统关联PR #15242对于已有的 ClickHouse 与 DuckDB observability 信号表需要先执行npx mastra migrate再初始化 store以应用新的信号 ID schema。关键 API 备忘mastra.observability.flush()1.16.0 起ObservabilityEntrypoint提供flush()serverless 环境下直接可用不再需要mastra.observability.getDefaultInstance()?.flush()它委托给所有已注册实例与既有shutdown()模式一致PR #18873。mastra.observability.getRecordedTrace({ traceId })加载已持久化 trace并可通过 recorded trace/span 或顶层addScore()/addFeedback()附加评分与反馈1.6.0PR #14842。评分与反馈现在也能在只有上下文 metadata 而无 trace id 时存储1.7.1PR #14942。registerExporter可在运行时向 observability 栈与 Mastra 类注册导出器1.7.0PR #14730。logging配置ObservabilityInstance支持logging: { enabled, level }控制哪些内部日志进入 observability 存储1.7.0PR #14899level可选debug | info | warn | error | fatal。hideInput/hideOutputTracingOptions支持隐藏整条 trace含子 span的输入/输出用于保护敏感信息1.0.0PR #11969。信号 IDlogId、metricId、scoreId、feedbackId在发射时自动生成1.10.0。结语mastra/observability的演进记录本身就是一份很好的“可观测性工程实践清单”从默认开启的敏感数据脱敏到异常终止时仍然完整的 span 树再到按 span 计费平台下的精细过滤与配额暂停协议每一处都对应着真实的线上痛点。对使用 Mastra 的开发者来说理解这套机制意味着你不仅能“接上”可观测性还能在成本、隐私与排障体验之间做出精细权衡——这正是 AI 应用进入生产环境后最需要的能力。建议继续阅读仓库中的 observability/mastra/src 源码尤其exporters/、metrics/、span_processors/、bus/目录与 observability/mastra/src/spans/end-tree.test.ts、observability/mastra/src/trace-level-sampling.test.ts 等测试文件它们用真实用例展示了上述每一项机制的行为边界。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考