2026/9/14 22:27:52
FEATURED · 精选文章 
Mastra 可观测性系列mastra/sentry —— 用 OpenTelemetry GenAI 语义约定把 Agent 追踪接入 Sentry【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/sentry 是 Mastra 官方推出的 Sentry AI 可观测性导出器它把 Mastra 应用运行过程中产生的 Agent、模型、工具、工作流等追踪tracing数据以 OpenTelemetry GenAI 语义约定semantic conventions标准化后上报到 Sentry 的 AI 监控体系。读完本文你将掌握如何安装并零配置接入该导出器、每个配置项的真实含义与默认值、span 类型到 Sentry op 的完整映射规则、会话conversation聚合的实现原理以及无服务器环境下flush()的正确用法。包概览与安装mastra/sentry是 Mastra 可观测性生态中的一个独立 npm 包位于仓库的 observability/sentry 目录。从其 package.json 可以看到它的依赖关系运行时依赖mastra/observability导出器基类BaseExporter与mastra/otel-exporter提供 GenAI 语义属性的构建函数并以sentry/node^10.68.0作为底层上报 SDK同时要求mastra/core作为 peer dependency1.16.0-0 2.0.0-0并声明 Node.js 22.13.0。安装只需要一条命令README 原文npm install mastra/sentry零配置接入在 Mastra 中注册 SentryExporter该包的核心导出类是SentryExporter定义在 observability/sentry/src/tracing.ts 中。它继承自mastra/observability的BaseExporter与 Mastra 的Observability实例配合使用。README 提供了可直接运行的完整接入示例import { Mastra } from mastra/core/mastra; 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()], }, }, }), });在这个配置中configs.sentry是 Mastra 可观测性配置中专门为 Sentry 预留的键serviceName标识你的服务名称会体现在 Sentry 的 issue 与 trace 归属上exporters数组内传入SentryExporter实例后续所有 span 事件SPAN_STARTED、SPAN_UPDATED、SPAN_ENDED都会流入该导出器。值得注意的是 CHANGELOG 1.2.15 记录过一次包体积优化从分发的 npm 文件中去除了CHANGELOG.md以减少发布体积。这意味着你通过 npm 安装后不会在node_modules里看到 changelog版本历史都以仓库内这份 CHANGELOG.md 为准。SentryExporter 配置项详解SentryExporter构造函数接受SentryExporterConfig其全部字段与默认值都写在源码中tracing.ts 的 SentryExporterConfig 定义与 CHANGELOG 各版本迭代相互印证配置项类型默认值说明dsnstring优先取构造参数其次process.env.SENTRY_DSN否则为空Sentry Data Source Name决定事件上报到哪个项目。必填缺失时导出器会调用setDisabled自动禁用并输出提示environmentstring优先取构造参数其次process.env.SENTRY_ENVIRONMENT否则production部署环境标识用于在 Sentry 中按环境过滤 issue 与告警tracesSampleRatenumber1.0发送到 Sentry 的 transaction 采样比例0.0 表示 0%1.0 表示 100%releasestring优先取构造参数其次process.env.SENTRY_RELEASE否则为空部署代码版本帮助定位回归与跟踪发布optionsPartialSentry.NodeOptions无透传给Sentry.init()的其余 SDK 选项integrations、beforeSend 等从构造函数实现tracing.ts 构造函数可以看到内部会调用Sentry.init({ dsn, environment, tracesSampleRate, release, ...config.options })完成 SDK 初始化若初始化抛错同样会走setDisabled路径而不是让应用崩溃。这一“缺失 DSN 自动降级禁用”的行为也被测试覆盖见 tracing.test.ts 附近对“无 DSN 时警告并禁用导出器”的断言。CHANGELOG 1.2.9 记录了依赖升级sentry/node从^10.57.0升至^10.68.0。如果遇到 SDK 行为差异可将 changelog 作为排查起点。span 类型映射从 Mastra SpanType 到 Sentry op导出器的核心价值在于把 Mastra 内部的 span 语义翻译成 Sentry 能识别的 AI 操作。源码中的SPAN_TYPE_CONFIG是这张翻译表tracing.ts结合 CHANGELOG 的演进记录可以完整还原其设计MastraSpanTypeSentryopTypeopName引入/变更版本AGENT_RUNgen_ai.invoke_agentinvoke_agent1.0.0MODEL_GENERATIONgen_ai.chatchat1.0.0TOOL_CALL/MCP_TOOL_CALLgen_ai.execute_toolexecute_tool1.0.0PROVIDER_TOOL_CALLgen_ai.execute_toolexecute_tool1.2.4 新增CHANGELOG #19261WORKFLOW_RUNworkflow.runworkflow1.0.0WORKFLOW_STEP等步骤类workflow.step/workflow.conditional/workflow.parallel/workflow.loop/workflow.sleep/workflow.waitstep1.0.0PROCESSOR_RUNai.processorstep—GENERIC/MODEL_STEP/MODEL_CHUNKai.spanspan/step1.0.0SCORER_RUN/SCORER_STEPworkflow.run/workflow.stepeval/step1.0.11 新增CHANGELOG #14920MEMORY_OPERATIONai.memorymemory1.0.13 新增CHANGELOG #14305WORKSPACE_ACTIONai.workspaceworkspace1.2.16 调整CHANGELOG #22542SKILL_ACTIONai.skillskill1.2.16 调整CHANGELOG #22542CHANGELOG 1.2.16 的这条记录非常关键Skill 与 workspace 的 span 不再映射为笼统的ai.span而是分别上报为ai.skill与ai.workspace与内存 span 早已映射到ai.memory的方式保持一致。结合源码注释可以理解其取舍这类 span 可能来自模型调用的工具也可能来自 Agent 配置派生的处理器若映射成处理器风格的 op 会误标工具调用因此统一落到各自子系统的命名空间下。向后兼容的防御buildSpanTypeConfig源码中还隐藏着一个与 CHANGELOG 1.2.16 描述呼应的工程细节buildSpanTypeConfigtracing.ts。由于mastra/sentry的 peer range 允许配对一个比“引入某 SpanType 成员”更旧的mastra/core此时SpanType.X在运行时是undefined。如果直接用普通对象字面量构建映射这些条目会被落在字面量undefined键下进而匹配所有类型为 undefined 的 span 造成误标。该函数会在构建映射时把这类条目剔除CHANGELOG 明确写道“Span types that are missing from an older pairedmastra/coreare skipped rather than mapped under anundefinedkey”。对应测试见 tracing.test.ts 的 buildSpanTypeConfig 用例。会话聚合gen_ai.conversation.id 的引入CHANGELOG 1.1.0PR #16925记录了一个对多轮对话场景至关重要的小版本特性导出器现在会把metadata.threadId映射为gen_ai.conversation.idspan 属性。同一聊天线程产生的 span 因此在 Sentry 的 Conversations 视图AI Agent Monitoring 的一部分中被聚合到一起。changelog 原文给出了用法const agent mastra.getAgent(chat); // Pass threadId as before — the Sentry exporter now emits it as gen_ai.conversation.id await agent.generate(Hello, { memory: { thread: thread-123, resource: user-1 }, });你不需要改动任何调用代码只要像往常一样在generate时传入memory.thread导出器就会自动完成属性写入。源码中对应的实现位于buildSpanAttributestracing.tsthis.setAttributeIfDefined(attributes, ATTRIBUTE_KEYS.GEN_AI_CONVERSATION_ID, span.metadata?.threadId);其中GEN_AI_CONVERSATION_ID常量即gen_ai.conversation.id见 ATTRIBUTE_KEYS。同时gen_ai.conversation.id这一属性名也是由mastra/otel-exporter的getAttributes统一生成的语义约定其行为有独立单测覆盖见 otel-exporter 的 gen-ai-semantics.test.ts 对 threadId 映射的断言说明会话 ID 的处理在 exporter 层被刻意保持了语义一致性。无服务器环境flush() 与 shutdown() 的正确姿势CHANGELOG 1.0.0PR #12003为该包引入了一个面向 serverless 的重要 APIflush()。在 Vercel fluid compute 这类“运行时实例可在多个请求间复用”的环境中span 会先缓冲在内存里实例即将被终止前必须把缓冲 span 冲刷出去但又不能像shutdown()那样释放资源、阻止后续导出。changelog 原文给出了两种调用方式// Flush all exporters via the observability instance const observability mastra.getObservability(); await observability.flush(); // Or flush individual exporters const exporters observability.getExporters(); await exporters[0].flush();源码中的实现tracing.ts 的 flush内部调用Sentry.flush(2000)即以 2 秒超时把待发送事件推送给 Sentry而shutdown()tracing.ts 的 shutdown则遍历spanMap结束所有未完成 span、清空内部状态再调用Sentry.close(2000)并交给super.shutdown()收尾。两者边界清晰flush 用于保持存活、只求落盘shutdown 用于彻底退出。可调试的错误上报从字符串到真实堆栈CHANGELOG 1.0.16PR #15343修复 #15337记录了一次直接改善排障体验的修复此前mastra/sentry把错误消息以字符串传给Sentry.captureExceptionSentry 只能从导出器自身的调用点SentryExporter.handleSpanEnded合成堆栈导致 issue 里的报错位置毫无参考价值。修复分两处导出器现在构造一个携带已捕获堆栈的Error实例再交给captureExceptionmastra/observability之前把包装的MastraError的堆栈存到 span 上掩盖了原始错误位置现在当MastraError存在cause时保留 cause 的堆栈。对应源码见 handleSpanEnded 的错误分支它新建Error回填name与stack并通过contexts.trace与contexts.span_info把traceId、spanId、span 名称、span 类型、errorInfo.id与errorInfo.category一并附加到上报上下文中。这样你在 Sentry 看到的异常会直接指向真正抛错的那一行代码。token 用量与缓存语义属性的演进CHANGELOG 1.0.21PR #15966记录了属性命名的规范对齐为了匹配 OpenTelemetry 语义约定缓存相关的 GenAI 用量属性做了重命名gen_ai.usage.cached_input_tokens→gen_ai.usage.cache_read.input_tokensgen_ai.usage.cache_write_tokens→gen_ai.usage.cache_creation.input_tokens同时明确gen_ai.usage.input_tokens不变仍是提示词的 token 总数缓存属性作为其子集单独下发。该变更同步更新了 Arize、Arthur 与 Sentry 三处映射。如果你在 Sentry 或其他后端建过引用旧属性名的仪表盘、告警或查询升级后需要同步修改。在 tracing.ts 的 ATTRIBUTE_KEYS 中可以看到当前完整属性集合除上述缓存属性外还包括gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.usage.total_tokens与gen_ai.usage.reasoning_tokens。token 汇总逻辑见applyUsageFromGenerationtracing.ts当AGENT_RUNspan 结束时从它唯一的子MODEL_GENERATIONspan 读取 usage每个 AGENT_RUN 只有一个 MODEL_GENERATION按需写入输入、输出、总量、缓存读、缓存写与推理 token 属性0 值不会被写入。工具调用关联toolCallId 的统一拾取CHANGELOG 1.2.7PR #19405记录了工具调用关联的修正所有可观测性导出器改为从 span 属性读取toolCallId并保留 metadata 兜底使 Braintrust 线程视图能通过真实工具调用 ID 配对工具结果Sentry 与 OTel 导出器也在所有工具 span 类型上一致地拾取该 ID。源码中的实现位于 addToolCallAttributesthis.setAttributeIfDefined( attributes, ATTRIBUTE_KEYS.GEN_AI_TOOL_CALL_ID, toolAttr.toolCallId ?? span.metadata?.toolCallId, );即优先ToolCallAttributes.toolCallId缺失时回退span.metadata.toolCallId。此外handleSpanStarted中还会把TOOL_CALL/PROVIDER_TOOL_CALL子 span 登记到其父MODEL_GENERATIONspan 的toolCalls列表里trackToolCallForParent当模型生成 span 结束时把该列表序列化写入gen_ai.response.tool_calls属性applyToolCallsAttribute方便在 Sentry 中直接查看一次生成发起了哪些工具调用。span 层级与简化策略源码文件头部注释给出了导出器的 trace 组织模型AGENT_RUN - MODEL_GENERATION - TOOL_CALL的层级结构并明确MODEL_STEP与MODEL_CHUNKspan 会被跳过以简化 trace 层级tracing.ts 头部注释。具体实现上_exportTracingEventtracing.ts会对这两类 span 做特殊处理开始时记入skippedSpans映射自身 id → 父 id结束时移除当其他 span 引用被跳过的 span 作为父节点时resolveParentSpanIdtracing.ts会沿链向上找到第一个未被跳过的祖先从而保证父子关系不因简化而断裂。事件型 spanexportedSpan.isEvent为真则不走完整 span 生命周期而是通过Sentry.addBreadcrumb记录为面包屑handleEventSpan把 spanId、traceId、input/output、metadata 与 attributes 一并附加错误级事件以error级别写入。版本脉络小结把 CHANGELOG 串联起来可以清晰看到该导出器一年来的能力演进主线版本里程碑1.0.0正式发布PR #11890基于 OpenTelemetry GenAI 语义约定的 AI 追踪导出器新增flush()PR #120031.0.11新增SCORER_RUN/SCORER_STEP映射PR #149201.0.13新增ai.memory内存操作 spanPR #143051.0.16修复错误堆栈指向导出器调用点的问题PR #153431.0.21缓存用量属性对齐 OTel 语义约定PR #159661.1.0新增gen_ai.conversation.id会话聚合PR #169251.2.4新增PROVIDER_TOOL_CALL到工具 span 的映射PR #192611.2.7统一从 span 属性读取toolCallIdPR #194051.2.9sentry/node升级至^10.68.0PR #197831.2.15分发包移除 CHANGELOG减小包体积PR #22737 / #228581.2.16Skill/workspace span 上报为ai.skill/ai.workspace并加入缺失类型防御PR #22542如果需要在 Mastra 之外继续深入可以顺带阅读同一仓库下 mastra/otel-exporter 的 gen-ai-semantics 实现属性与 span 命名的源头以及 mastra/observability 的BaseExporter基类flush/shutdown/setDisabled的生命周期约定这两处是理解SentryExporter行为的上游。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Mastra 可观测性系列：@mastra/sentry —— 用 OpenTelemetry GenAI 语义约定把 Agent 追踪接入 Sentry
Mastra 可观测性系列mastra/sentry —— 用 OpenTelemetry GenAI 语义约定把 Agent 追踪接入 Sentry【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/sentry 是 Mastra 官方推出的 Sentry AI 可观测性导出器它把 Mastra 应用运行过程中产生的 Agent、模型、工具、工作流等追踪tracing数据以 OpenTelemetry GenAI 语义约定semantic conventions标准化后上报到 Sentry 的 AI 监控体系。读完本文你将掌握如何安装并零配置接入该导出器、每个配置项的真实含义与默认值、span 类型到 Sentry op 的完整映射规则、会话conversation聚合的实现原理以及无服务器环境下flush()的正确用法。包概览与安装mastra/sentry是 Mastra 可观测性生态中的一个独立 npm 包位于仓库的 observability/sentry 目录。从其 package.json 可以看到它的依赖关系运行时依赖mastra/observability导出器基类BaseExporter与mastra/otel-exporter提供 GenAI 语义属性的构建函数并以sentry/node^10.68.0作为底层上报 SDK同时要求mastra/core作为 peer dependency1.16.0-0 2.0.0-0并声明 Node.js 22.13.0。安装只需要一条命令README 原文npm install mastra/sentry零配置接入在 Mastra 中注册 SentryExporter该包的核心导出类是SentryExporter定义在 observability/sentry/src/tracing.ts 中。它继承自mastra/observability的BaseExporter与 Mastra 的Observability实例配合使用。README 提供了可直接运行的完整接入示例import { Mastra } from mastra/core/mastra; 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()], }, }, }), });在这个配置中configs.sentry是 Mastra 可观测性配置中专门为 Sentry 预留的键serviceName标识你的服务名称会体现在 Sentry 的 issue 与 trace 归属上exporters数组内传入SentryExporter实例后续所有 span 事件SPAN_STARTED、SPAN_UPDATED、SPAN_ENDED都会流入该导出器。值得注意的是 CHANGELOG 1.2.15 记录过一次包体积优化从分发的 npm 文件中去除了CHANGELOG.md以减少发布体积。这意味着你通过 npm 安装后不会在node_modules里看到 changelog版本历史都以仓库内这份 CHANGELOG.md 为准。SentryExporter 配置项详解SentryExporter构造函数接受SentryExporterConfig其全部字段与默认值都写在源码中tracing.ts 的 SentryExporterConfig 定义与 CHANGELOG 各版本迭代相互印证配置项类型默认值说明dsnstring优先取构造参数其次process.env.SENTRY_DSN否则为空Sentry Data Source Name决定事件上报到哪个项目。必填缺失时导出器会调用setDisabled自动禁用并输出提示environmentstring优先取构造参数其次process.env.SENTRY_ENVIRONMENT否则production部署环境标识用于在 Sentry 中按环境过滤 issue 与告警tracesSampleRatenumber1.0发送到 Sentry 的 transaction 采样比例0.0 表示 0%1.0 表示 100%releasestring优先取构造参数其次process.env.SENTRY_RELEASE否则为空部署代码版本帮助定位回归与跟踪发布optionsPartialSentry.NodeOptions无透传给Sentry.init()的其余 SDK 选项integrations、beforeSend 等从构造函数实现tracing.ts 构造函数可以看到内部会调用Sentry.init({ dsn, environment, tracesSampleRate, release, ...config.options })完成 SDK 初始化若初始化抛错同样会走setDisabled路径而不是让应用崩溃。这一“缺失 DSN 自动降级禁用”的行为也被测试覆盖见 tracing.test.ts 附近对“无 DSN 时警告并禁用导出器”的断言。CHANGELOG 1.2.9 记录了依赖升级sentry/node从^10.57.0升至^10.68.0。如果遇到 SDK 行为差异可将 changelog 作为排查起点。span 类型映射从 Mastra SpanType 到 Sentry op导出器的核心价值在于把 Mastra 内部的 span 语义翻译成 Sentry 能识别的 AI 操作。源码中的SPAN_TYPE_CONFIG是这张翻译表tracing.ts结合 CHANGELOG 的演进记录可以完整还原其设计MastraSpanTypeSentryopTypeopName引入/变更版本AGENT_RUNgen_ai.invoke_agentinvoke_agent1.0.0MODEL_GENERATIONgen_ai.chatchat1.0.0TOOL_CALL/MCP_TOOL_CALLgen_ai.execute_toolexecute_tool1.0.0PROVIDER_TOOL_CALLgen_ai.execute_toolexecute_tool1.2.4 新增CHANGELOG #19261WORKFLOW_RUNworkflow.runworkflow1.0.0WORKFLOW_STEP等步骤类workflow.step/workflow.conditional/workflow.parallel/workflow.loop/workflow.sleep/workflow.waitstep1.0.0PROCESSOR_RUNai.processorstep—GENERIC/MODEL_STEP/MODEL_CHUNKai.spanspan/step1.0.0SCORER_RUN/SCORER_STEPworkflow.run/workflow.stepeval/step1.0.11 新增CHANGELOG #14920MEMORY_OPERATIONai.memorymemory1.0.13 新增CHANGELOG #14305WORKSPACE_ACTIONai.workspaceworkspace1.2.16 调整CHANGELOG #22542SKILL_ACTIONai.skillskill1.2.16 调整CHANGELOG #22542CHANGELOG 1.2.16 的这条记录非常关键Skill 与 workspace 的 span 不再映射为笼统的ai.span而是分别上报为ai.skill与ai.workspace与内存 span 早已映射到ai.memory的方式保持一致。结合源码注释可以理解其取舍这类 span 可能来自模型调用的工具也可能来自 Agent 配置派生的处理器若映射成处理器风格的 op 会误标工具调用因此统一落到各自子系统的命名空间下。向后兼容的防御buildSpanTypeConfig源码中还隐藏着一个与 CHANGELOG 1.2.16 描述呼应的工程细节buildSpanTypeConfigtracing.ts。由于mastra/sentry的 peer range 允许配对一个比“引入某 SpanType 成员”更旧的mastra/core此时SpanType.X在运行时是undefined。如果直接用普通对象字面量构建映射这些条目会被落在字面量undefined键下进而匹配所有类型为 undefined 的 span 造成误标。该函数会在构建映射时把这类条目剔除CHANGELOG 明确写道“Span types that are missing from an older pairedmastra/coreare skipped rather than mapped under anundefinedkey”。对应测试见 tracing.test.ts 的 buildSpanTypeConfig 用例。会话聚合gen_ai.conversation.id 的引入CHANGELOG 1.1.0PR #16925记录了一个对多轮对话场景至关重要的小版本特性导出器现在会把metadata.threadId映射为gen_ai.conversation.idspan 属性。同一聊天线程产生的 span 因此在 Sentry 的 Conversations 视图AI Agent Monitoring 的一部分中被聚合到一起。changelog 原文给出了用法const agent mastra.getAgent(chat); // Pass threadId as before — the Sentry exporter now emits it as gen_ai.conversation.id await agent.generate(Hello, { memory: { thread: thread-123, resource: user-1 }, });你不需要改动任何调用代码只要像往常一样在generate时传入memory.thread导出器就会自动完成属性写入。源码中对应的实现位于buildSpanAttributestracing.tsthis.setAttributeIfDefined(attributes, ATTRIBUTE_KEYS.GEN_AI_CONVERSATION_ID, span.metadata?.threadId);其中GEN_AI_CONVERSATION_ID常量即gen_ai.conversation.id见 ATTRIBUTE_KEYS。同时gen_ai.conversation.id这一属性名也是由mastra/otel-exporter的getAttributes统一生成的语义约定其行为有独立单测覆盖见 otel-exporter 的 gen-ai-semantics.test.ts 对 threadId 映射的断言说明会话 ID 的处理在 exporter 层被刻意保持了语义一致性。无服务器环境flush() 与 shutdown() 的正确姿势CHANGELOG 1.0.0PR #12003为该包引入了一个面向 serverless 的重要 APIflush()。在 Vercel fluid compute 这类“运行时实例可在多个请求间复用”的环境中span 会先缓冲在内存里实例即将被终止前必须把缓冲 span 冲刷出去但又不能像shutdown()那样释放资源、阻止后续导出。changelog 原文给出了两种调用方式// Flush all exporters via the observability instance const observability mastra.getObservability(); await observability.flush(); // Or flush individual exporters const exporters observability.getExporters(); await exporters[0].flush();源码中的实现tracing.ts 的 flush内部调用Sentry.flush(2000)即以 2 秒超时把待发送事件推送给 Sentry而shutdown()tracing.ts 的 shutdown则遍历spanMap结束所有未完成 span、清空内部状态再调用Sentry.close(2000)并交给super.shutdown()收尾。两者边界清晰flush 用于保持存活、只求落盘shutdown 用于彻底退出。可调试的错误上报从字符串到真实堆栈CHANGELOG 1.0.16PR #15343修复 #15337记录了一次直接改善排障体验的修复此前mastra/sentry把错误消息以字符串传给Sentry.captureExceptionSentry 只能从导出器自身的调用点SentryExporter.handleSpanEnded合成堆栈导致 issue 里的报错位置毫无参考价值。修复分两处导出器现在构造一个携带已捕获堆栈的Error实例再交给captureExceptionmastra/observability之前把包装的MastraError的堆栈存到 span 上掩盖了原始错误位置现在当MastraError存在cause时保留 cause 的堆栈。对应源码见 handleSpanEnded 的错误分支它新建Error回填name与stack并通过contexts.trace与contexts.span_info把traceId、spanId、span 名称、span 类型、errorInfo.id与errorInfo.category一并附加到上报上下文中。这样你在 Sentry 看到的异常会直接指向真正抛错的那一行代码。token 用量与缓存语义属性的演进CHANGELOG 1.0.21PR #15966记录了属性命名的规范对齐为了匹配 OpenTelemetry 语义约定缓存相关的 GenAI 用量属性做了重命名gen_ai.usage.cached_input_tokens→gen_ai.usage.cache_read.input_tokensgen_ai.usage.cache_write_tokens→gen_ai.usage.cache_creation.input_tokens同时明确gen_ai.usage.input_tokens不变仍是提示词的 token 总数缓存属性作为其子集单独下发。该变更同步更新了 Arize、Arthur 与 Sentry 三处映射。如果你在 Sentry 或其他后端建过引用旧属性名的仪表盘、告警或查询升级后需要同步修改。在 tracing.ts 的 ATTRIBUTE_KEYS 中可以看到当前完整属性集合除上述缓存属性外还包括gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.usage.total_tokens与gen_ai.usage.reasoning_tokens。token 汇总逻辑见applyUsageFromGenerationtracing.ts当AGENT_RUNspan 结束时从它唯一的子MODEL_GENERATIONspan 读取 usage每个 AGENT_RUN 只有一个 MODEL_GENERATION按需写入输入、输出、总量、缓存读、缓存写与推理 token 属性0 值不会被写入。工具调用关联toolCallId 的统一拾取CHANGELOG 1.2.7PR #19405记录了工具调用关联的修正所有可观测性导出器改为从 span 属性读取toolCallId并保留 metadata 兜底使 Braintrust 线程视图能通过真实工具调用 ID 配对工具结果Sentry 与 OTel 导出器也在所有工具 span 类型上一致地拾取该 ID。源码中的实现位于 addToolCallAttributesthis.setAttributeIfDefined( attributes, ATTRIBUTE_KEYS.GEN_AI_TOOL_CALL_ID, toolAttr.toolCallId ?? span.metadata?.toolCallId, );即优先ToolCallAttributes.toolCallId缺失时回退span.metadata.toolCallId。此外handleSpanStarted中还会把TOOL_CALL/PROVIDER_TOOL_CALL子 span 登记到其父MODEL_GENERATIONspan 的toolCalls列表里trackToolCallForParent当模型生成 span 结束时把该列表序列化写入gen_ai.response.tool_calls属性applyToolCallsAttribute方便在 Sentry 中直接查看一次生成发起了哪些工具调用。span 层级与简化策略源码文件头部注释给出了导出器的 trace 组织模型AGENT_RUN - MODEL_GENERATION - TOOL_CALL的层级结构并明确MODEL_STEP与MODEL_CHUNKspan 会被跳过以简化 trace 层级tracing.ts 头部注释。具体实现上_exportTracingEventtracing.ts会对这两类 span 做特殊处理开始时记入skippedSpans映射自身 id → 父 id结束时移除当其他 span 引用被跳过的 span 作为父节点时resolveParentSpanIdtracing.ts会沿链向上找到第一个未被跳过的祖先从而保证父子关系不因简化而断裂。事件型 spanexportedSpan.isEvent为真则不走完整 span 生命周期而是通过Sentry.addBreadcrumb记录为面包屑handleEventSpan把 spanId、traceId、input/output、metadata 与 attributes 一并附加错误级事件以error级别写入。版本脉络小结把 CHANGELOG 串联起来可以清晰看到该导出器一年来的能力演进主线版本里程碑1.0.0正式发布PR #11890基于 OpenTelemetry GenAI 语义约定的 AI 追踪导出器新增flush()PR #120031.0.11新增SCORER_RUN/SCORER_STEP映射PR #149201.0.13新增ai.memory内存操作 spanPR #143051.0.16修复错误堆栈指向导出器调用点的问题PR #153431.0.21缓存用量属性对齐 OTel 语义约定PR #159661.1.0新增gen_ai.conversation.id会话聚合PR #169251.2.4新增PROVIDER_TOOL_CALL到工具 span 的映射PR #192611.2.7统一从 span 属性读取toolCallIdPR #194051.2.9sentry/node升级至^10.68.0PR #197831.2.15分发包移除 CHANGELOG减小包体积PR #22737 / #228581.2.16Skill/workspace span 上报为ai.skill/ai.workspace并加入缺失类型防御PR #22542如果需要在 Mastra 之外继续深入可以顺带阅读同一仓库下 mastra/otel-exporter 的 gen-ai-semantics 实现属性与 span 命名的源头以及 mastra/observability 的BaseExporter基类flush/shutdown/setDisabled的生命周期约定这两处是理解SentryExporter行为的上游。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
