Mastra 接入 Datadog LLM Observability：从零配置到源码级原理的完整指南

Mastra 接入 Datadog LLM Observability从零配置到源码级原理的完整指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastraDatadog 是 Mastra 官方可观测性生态中的重要一环。mastra/datadog包负责把 Mastra 的 Agent、工作流、模型调用、工具调用等 Span 数据导出到 Datadog LLM Observability让你在既有监控体系中统一观察 AI 应用。本文以 CHANGELOG.md 为主线结合仓库源码与测试系统讲解两种集成模式DatadogBridge与DatadogExporter的选型、配置参数、Span 类型映射、消息格式化、Token 指标、错误追踪与 Serverless 刷新机制读完即可在生产环境落地并理解其底层工作方式。一、两种集成模式Bridge 与 Exporter 如何选型从 index.ts 的注释可以看出mastra/datadog提供两条集成路径DatadogBridge推荐在 Mastra Span 创建时即时创建原生 dd-trace APM Span并将其激活到 dd-trace 的作用域scope中。这样 dd-trace 的自动插桩HTTP、数据库、框架调用都能找到正确的父 Span从而保持 APM 上下文正确传播同时把同一 Span 注册给 Datadog LLMObs避免产生第二棵合成 Span 树。DatadogExporter旧版导出器模式采用完成后导出模式仅在span_ended事件时回填导出 LLMObs Span。它不参与 dd-trace 的实时作用域因此自动插桩的 APM SpanHTTP、DB不会被挂到 Mastra Span 之下。从源码结构推断如果你的应用启用了 dd-trace 自动插桩APM应优先使用DatadogBridge如果只需要 LLMObs 数据、不关心 APM 关联DatadogExporter也足够。这正好对应 1.1.0 引入 Bridge 时解决的问题——旧导出器会让 APM Span 回退到最近的活跃 Span通常是请求处理器导致嵌套关系错乱。二、安装与最小可用配置按 README.md 安装npm install mastra/datadog在应用入口初始化 dd-traceBridge 模式下需要Exporter 亦可然后在Mastra实例中挂载观测配置import tracer from dd-trace; tracer.init({ service: process.env.DD_SERVICE || my-mastra-app, env: process.env.DD_ENV || production, }); import { Mastra } from mastra/core; import { Observability } from mastra/observability; import { DatadogBridge } from mastra/datadog; const mastra new Mastra({ observability: new Observability({ configs: { default: { serviceName: my-mastra-app, bridge: new DatadogBridge({ mlApp: process.env.DD_LLMOBS_ML_APP!, }), }, }, }), });以上示例来自 1.1.0 的发布说明是 Bridge 模式的官方推荐写法。Exporter 模式则写在exporters数组里import { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { DatadogExporter } from mastra/datadog; export const mastra new Mastra({ observability: new Observability({ configs: { datadog: { serviceName: my-service, exporters: [new DatadogExporter()], }, }, }), });零配置模式自 1.0.0 起导出器支持零配置实例化直接从环境变量读取凭据// 零配置用法——自动读取环境变量 const exporter new DatadogExporter();支持的环境变量源码见 tracing.ts 构造函数与 bridge.ts 构造函数环境变量含义默认值DD_LLMOBS_ML_APPML 应用名用于对 Trace 分组必需无DD_API_KEYDatadog API Keyagentless 模式必需无DD_SITEDatadog 站点datadoghq.comDD_ENV环境名如production、staging无DD_LLMOBS_AGENTLESS_ENABLED是否启用 agentless 模式true/1/false/0见下方说明配置缺失时的行为很明确若缺少mlAppBridge/Exporter 会调用setDisabled()并记录Missing required mlApp日志整个导出链路被安全禁用若 agentless 模式下缺少apiKey同样会禁用。参见 bridge.ts 与 tracing.ts 的校验逻辑。三、核心配置参数详解两类组件都继承BaseExporterConfig参数基本一致定义见 bridge.ts 的DatadogBridgeConfig参数类型说明默认值mlAppstringML 应用名按应用对 Trace 分组DD_LLMOBS_ML_APPapiKeystringDatadog API Keyagentless 模式必需DD_API_KEYsitestringDatadog 站点DD_SITE→datadoghq.comservicestring服务名未指定时 Bridge 回退到mlAppmlAppenvstring环境名DD_ENVagentlessboolean直连 HTTPS 上报true或走本地 Datadog AgentfalseBridge 默认 falseExporter 默认 trueintegrationsEnabledboolean启用 dd-trace 自动插桩HTTP、数据库等Bridge 默认 trueExporter 默认 falserequestContextKeysstring[]需要提升为扁平 LLMObs Tag 的请求上下文键名无注意两个组件在agentless与integrationsEnabled上的默认值相反这是有意的设计Bridge 面向 APM 集成场景假定用户已运行本地 Datadog AgentAPM 数据必需因此agentless默认false、integrationsEnabled默认true见 bridge.ts。Exporter 只关心 LLMObs与其他 Mastra 导出器保持一致agentless默认true、integrationsEnabled默认false见 tracing.ts。requestContextKeys是 1.0.10 引入的能力把多租户场景下常用的tenantId、agentId等键从嵌套的annotations.metadata提升为扁平、可索引、可筛选的 LLMObs Tag方便在 Datadog UI 中直接过滤new DatadogExporter({ mlApp: my-app, requestContextKeys: [tenantId, agentId], });ensureTracer()见 utils.ts保证 dd-trace 每个进程只初始化一次并会调用tracer.llmobs.enable({ mlApp, agentlessEnabled })启用 LLM Observability若应用已自行tracer.init()它会跳过重复初始化只做 LLMObs 开启。四、Span 类型映射原理新旧两套层级mastra/datadog把 Mastra 的SpanType映射为 Datadog LLMObs 的kindllm、agent、workflow、tool、task、retrieval、embedding映射逻辑在 utils.ts 中分为两套旧层级无model-inference-span特性MODEL_STEP即实际 API 调用Mastra SpanTypeDatadog KindAGENT_RUNagentMODEL_GENERATIONworkflowMODEL_STEPllmTOOL_CALL/MCP_TOOL_CALL/PROVIDER_TOOL_CALLtoolWORKFLOW_RUNworkflow其他task兜底新层级启用model-inference-span特性MODEL_INFERENCE是真实 LLM 调用Mastra SpanTypeDatadog KindAGENT_RUNagentMODEL_GENERATIONworkflowMODEL_STEPworkflow包裹 processors 推理 工具执行MODEL_INFERENCEllmTOOL_CALL/MCP_TOOL_CALL/PROVIDER_TOOL_CALLtoolWORKFLOW_RUNworkflow其他task兜底两套映射的切换由特性检测函数isModelInferenceEnabled()驱动见 features.ts它同时检查mastra/core的coreFeatures与动态加载的mastra/observability的observabilityFeatures是否都声明了model-inference-span从而在老版本配对下降级到旧层级。这一映射的演进在 CHANGELOG 中有完整脉络1.0.15修正模型 Span 的 kind——每次模型调用上报为llm此前是task导致 Datadog Model Calls 计数错误、输入输出不渲染为消息生成的外层包装上报为workflow而不是llm避免看起来像多了一次 LLM 调用Token 与费用只挂在单次调用的llmSpan 上避免重复计数llmSpan 从父代继承modelName与modelProvider。1.0.10修正MODEL_GENERATION错误映射为workflow导致model_name: custom、provider 丢失的问题——现在MODEL_GENERATION正确映射为llm、MODEL_STEP兜底为task。1.2.0新增MODEL_INFERENCE→llm、MODEL_STEP→workflow的新映射并在旧 core 上回退。1.3.4把PROVIDER_TOOL_CALL加入映射与耗时指标使 provider 执行的工具 Span 在所有观测平台都被分类为 tool Span。从源码结构看kindFor()每次调用都会重新读取特性标志见 utils.ts因此测试可以在运行时切换标志生产环境中该值在模块加载时即可确定。五、LLM 输入输出消息格式化与 Tool Call 渲染Datadog LLMObs 要求模型 Span 的输入输出呈现为{ role, content }[]消息数组formatInput()与formatOutput()见 utils.ts负责规范化已是消息数组直接转换并把每个消息的toolCalls规范化为 Datadog 认可的{ name, arguments, toolId, type }形状兼容 Mastra 原始结构toolName/args/toolCallId与已规范化结构name/arguments/toolId见toDatadogToolCalls()。Gemini 格式{ role, parts }会归一化为{ role, content }从 parts 中提取文本二进制数据inlineData只保留[mimeType]占位、函数调用显示为[tool: name]避免撑爆 Trace见geminiContentToMessage()。该能力是 1.0.14 加入的。包装对象解包Mastra 会把MODEL_GENERATION输入包成{ messages, schema? }、Gemini 请求体用{ contents }格式化时会解包取messages/contents防止消息数组被序列化进单个 user 消息造成双重编码 JSON对应 1.2.0 修复的 double-encoded JSON 问题。输出对象优先渲染text存在toolCalls时输出为带结构化 tool-call 块的 assistant 消息对应 1.2.1 的修复object输出则字符串化。空消息清理空的 user 消息会被过滤掉见toDatadogMessages()末尾的.filter()。工具调用的渲染是反复打磨的点1.2.1 修复了 LLM 输出 tool call 不渲染为结构化块的问题1.2.4 修复了输入消息中的 tool call 显示为空对象的问题此前原始 tool-call 形状被原样透传、被 dd-trace 丢弃输出侧早已处理、输入侧这次对齐。六、Token 用量、缓存与耗时指标Token 指标由formatUsageMetrics()见 metrics.ts生成映射关系如下Mastra 字段Datadog 指标键usage.inputTokensinputTokensusage.outputTokensoutputTokens输入 输出totalTokensusage.outputDetails.reasoningreasoningOutputTokensusage.inputDetails.cacheReadcacheReadTokensusage.inputDetails.cacheWritecacheWriteTokens指标只挂在 LLM 类 Span 上新层级为MODEL_INFERENCE旧层级为MODEL_STEP避免 Datadog 对 Token 与费用重复计数见 tracing.ts 与 bridge.ts。几个值得注意的修复1.0.8多步 Agent 运行中优先使用 AI SDK 聚合的inputTokenDetails而非providerMetadata后者只反映最后一步并修正对零值的真值判断同时把指标键对齐为 dd-trace 期望的cacheReadTokens、cacheWriteTokens、reasoningOutputTokens。1.0.8 还修复了 Span 耗时不准的问题dd-trace 的llmobs.trace()不理会 span options 里的endTime因此现在显式调用ddSpan.finish(endTimeMs)来落定每个 Span 的真实结束时间见 tracing.ts 的注释说明。1.3.8 修复了 fire-and-forget 任务如Memory.generateTitle在 Datadog 中显示为断开的根 Trace 的问题。原因在于 dd-trace 只通过包裹的llmobs.trace()回调建立 LLMObs 父子关系迟到的 Span 链现在改为以嵌套子树方式发出使标题生成运行以单一 Tracestep、inference、chunk Span 正确嵌套呈现实现见 tracing.ts 的 late-arriving spans 分支。七、错误追踪从 [object Object] 到完整 Error Banner错误信息在 Datadog 的展示经历过三轮修复最终形成结构化字段进 Tag、自由文本进 metadata的稳定方案1.0.9错误详情message、id、domain、category从嵌套对象改为扁平 Tagerror.message、error.id、error.domain、error.category解决[object Object]问题。1.0.10错误消息文本从 Tag 移入 Span metadata。因为 Tag 归一化会破坏自由文本冒号被拆成键值对、空格变下划线、被截断而 metadata 保留原文结构化错误字段仍留在 Tag。1.0.12导出器设置原生 dd-trace 错误 Tagerror.message、error.type、error.stack使 Datadog Error Tracking UI 显示包含消息、类型、堆栈的完整错误横幅见setErrorTags()tracing.ts、bridge.ts。八、Eval 评分上报与 Serverless flush()评分上报自 1.2.0 起Mastra Eval 结果会转发到 Datadog。实现上通过tracer.llmobs.submitEvaluation()提交见 bridge.ts 与 tracing.ts携带labelscorer 名、value分数、metricType: score、reasoning理由、metadata等。Exporter 有一个明确的时序约束被评分的 Span 必须先完成SPAN_ENDED并已被发出到 dd-trace否则评分事件会被丢弃并记录警告见 tracing.ts。Mastra 的正常评分路径天然满足此约束——scorer hook 在实体完成后触发。Serverless flush()1.0.0 为导出器与观测实例新增了flush()方法面向 Vercel Fluid Compute 这类实例可复用的 Serverless 环境在实例被回收前冲刷缓冲的 Span但不释放资源、不阻止后续导出区别于shutdown()。// 通过观测实例冲刷所有导出器 const observability mastra.getObservability(); await observability.flush(); // 或单独冲刷某个导出器 const exporters observability.getExporters(); await exporters[0].flush();Bridge 的flush()会同时冲刷 LLMObs 与 APM 导出器见 bridge.ts其中 APM 导出器的冲刷通过内部_tracer._exporter.flush回调实现flushApmExporter()封装了 Promise 化与竞态保护。Exporter 内部还维护了 trace 状态的双层清理机制常规清理 1 分钟、最长存活 30 分钟兜底见 tracing.ts防止永不结束的 Trace 导致内存无限增长。九、依赖与安全演进dd-trace 依赖持续升级1.3.9 从^5.108.0升到^5.117.0此前 1.2.5 从^5.89.0升到^5.108.0当前 package.json 锁定^5.117.0要求 Node22.13.0。1.0.0 将openfeature/core、openfeature/server-sdk声明为可选 peer dependency消除安装警告它们来自 dd-trace 的传递依赖。1.2.7 针对 2026-06-17 的 easy-day-js 供应链事件做了补丁发布发布干净版本以越过被污染的版本。1.4.5 将CHANGELOG.md从 npm 发布包中移除减小包体积同时更新了 README。十、版本演进速览1.0.0 → 1.4.x从 CHANGELOG.md 可以梳理出这条集成从实验性 beta 到稳定的主线版本关键变化1.0.0-beta.2 / 1.0.0首次发布DatadogExporterLLMObs 集成、双模式、Span 映射、消息格式化、Token 指标、错误追踪、层级 Trace新增flush()零配置兼容1.0.6修复 Tagkey:value被附加:true的问题1.0.8修复缓存 Token 提取与 Span 耗时准确性1.0.9 / 1.0.10 / 1.0.12错误信息三连修复Span 类型映射修正请求上下文扁平 Tag1.0.14 / 1.0.15Gemini 输入格式支持模型 Span kind 修正1.1.0引入DatadogBridgeAPM 上下文传播1.2.0Eval 结果上报MODEL_INFERENCE新映射修复双重编码 JSON1.2.1 / 1.2.4输入输出 Tool Call 渲染修复模型请求选项temperature、maxOutputTokens、reasoningEffort转发1.2.7easy-day-js 供应链安全补丁1.3.4PROVIDER_TOOL_CALL映射补齐1.3.7被过滤 Span 的 bridge 状态及时释放1.3.8迟到 Span 链以嵌套子树发出避免断开根 Trace1.4.0Bridge 报告 Span 父节点来源Mastra 内部或外部外部父节点下的运行在 Mastra Studio 中记录为 Trace 根十一、源码阅读与测试指引想深入验证本文结论可以直接阅读bridge.tsBridge 的完整实现含createSpan()的父节点解析外部父节点优先、其次活跃作用域、executeWithSpanContext()的上下文激活、annotateAndFinishSpan()的收尾流程与releaseSpan()的状态释放。tracing.tsExporter 的树构建buildSpanTree、树发射emitSpanTree子 Span 在父回调内嵌套发出以建立父子关系、迟到子树takeSubTree。utils.tsSpan kind 映射与消息格式化。metrics.tsToken 指标映射。features.tsmodel-inference-span特性检测。bridge.test.ts用 mock dd-trace 验证 Bridge 每个 Mastra Span 生命周期只保留一个即时 dd Span、不产生第二棵合成树并覆盖配置校验、评分上报等场景。结语mastra/datadog从 1.0.0 的实验性导出器起步经过 Bridge 引入、Span 类型映射两轮演进、错误追踪三轮修复、Token 指标与消息格式化的持续打磨已成为一条成熟的 Datadog 接入路径。日常接入记住三条Bridge 管 APM 关联、Exporter 只管 LLMObsmlApp是硬性要求agentless 模式记得配DD_API_KEY按环境变量零配置起步再按需调agentless、integrationsEnabled与requestContextKeys即可在 Datadog 上获得完整的 Mastra Agent 可观测视图。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考