使用 mastra/laminar 将 Mastra 追踪数据接入 LaminarOTLP/HTTP 导出与评分回传实战指南【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文以 Mastra 仓库中observability/laminar包的官方文档为骨架深入讲解如何在 Mastra 应用中接入 Laminar 可观测性平台。你将掌握mastra/laminar的安装与配置方法、LaminarExporter全部配置参数的含义与默认值、追踪数据如何通过 OTLP/HTTPprotobuf协议上报以及如何把评估器scorer的评分结果回传到 Laminar Evaluators并结合仓库源码与测试用例理解其底层实现原理。一、mastra/laminar 是什么mastra/laminar是 Mastra 官方提供的 Laminar 可观测性导出器observability exporter包位于仓库的 observability/laminar 目录。其核心职责有两条对应 src/index.ts 中的模块说明追踪导出Tracing通过OTLP/HTTPprotobuf协议将 Mastra 采集到的 spans 导出到 Laminar评分回传Scoring将 Mastra 评估器scorer产生的评分结果发送到Laminar Evaluators实现评估数据的统一聚合。从 package.json 可以看到该包基于 OpenTelemetry 生态构建依赖opentelemetry/exporter-trace-otlp-protoprotobuf 格式的 OTLP 追踪导出器、opentelemetry/sdk-trace-baseSpan 处理器与opentelemetry/semantic-conventions语义约定运行时要求 Node.js 22.13.0对mastra/core的 peer 依赖为1.16.0-0 2.0.0-0。二、安装在你的 Mastra 项目中通过 npm 安装npm install mastra/laminar该包同样适用于 pnpm 与 yarn安装后即可从包入口导出LaminarExporter参见 src/index.ts 中的export * from ./tracing。三、快速接入最小配置示例在创建LaminarExporter之前必须先设置环境变量LMNR_PROJECT_API_KEYLaminar 项目 API Key。然后在 Mastra 的observability配置中注册该导出器import { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { LaminarExporter } from mastra/laminar; export const mastra new Mastra({ observability: new Observability({ configs: { laminar: { serviceName: my-service, exporters: [new LaminarExporter()], }, }, }), });这段配置的含义是创建一个名为laminar的可观测性实例服务名为my-service追踪数据经由LaminarExporter上报。3.1 配置结构说明Observability的configs是一个以实例名为 key 的映射表类型定义见 observability/mastra/src/config.ts 中的ObservabilityRegistryConfig每个实例配置中serviceName为必填zod schema 校验z.string().min(1)exporters数组至少要提供一个导出器或一个 bridge否则校验会失败At least one exporter or a bridge is required当configs中有两个及以上实例时必须同时提供configSelector函数用于选择实例。3.2 关于 API KeyLaminarExporter的构造函数会按如下优先级解析 API Key见 src/tracing.ts 构造函数config.apiKey ?? process.env.LMNR_PROJECT_API_KEY如果两者都未提供导出器会调用setDisabled进入禁用状态并打印警告Missing required API key. Set LMNR_PROJECT_API_KEY environment variable or pass apiKey in config.因此建议在.env文件中配置LMNR_PROJECT_API_KEYyour-laminar-project-api-key四、LaminarExporter 配置参数详解LaminarExporter的构造函数接受一个可选的LaminarExporterConfig对象接口定义见 src/tracing.ts下表汇总了全部参数及其默认值参数类型默认值说明apiKeystringprocess.env.LMNR_PROJECT_API_KEYLaminar 项目 API Key未配置时导出器自动禁用baseUrlstringprocess.env.LMNR_BASE_URL或https://api.lmnr.aiLaminar API 基础地址。用于 trace 导出当endpoint未设置时以及评分接口/v1/evaluators/scoreendpointstringprocess.env.LAMINAR_ENDPOINT或${baseUrl}/v1/traces完整的 OTLP/HTTP traces 端点headersRecordstring, string{ Authorization: Bearer apiKey }附加到 OTLP 请求的自定义请求头realtimebooleanfalse每个 span 结束后立即forceFlush实现近乎实时的可见性disableBatchbooleanfalse禁用批处理使用SimpleSpanProcessor逐条发送batchSizenumber512每批最多导出的 span 数仅BatchSpanProcessor生效timeoutMillisnumber30000OTLP 导出超时时间毫秒此外LaminarExporterConfig继承自BaseExporterConfig见 observability/mastra/src/exporters/base.ts因此还支持logger自定义 Mastra 日志器logLevel日志级别取值debug/info/warn/error默认infocustomSpanFormatter自定义 span 格式化函数在导出前对 span 做变换例如从结构化消息中抽取纯文本。4.1 参数在源码中的解析逻辑构造函数中的解析逻辑src/tracing.ts如下const baseUrl stripTrailingSlash(config.baseUrl ?? process.env.LMNR_BASE_URL ?? https://api.lmnr.ai); const endpoint config.endpoint ?? envEndpoint ?? ${baseUrl}/v1/traces; const headers: Recordstring, string { ...config.headers, Authorization: Bearer ${apiKey}, }; this.config { realtime: config.realtime ?? false, disableBatch: config.disableBatch ?? false, batchSize: config.batchSize ?? 512, timeoutMillis: config.timeoutMillis ?? 30000, };注意baseUrl会经过stripTrailingSlash处理尾部的/会被去除该函数在 src/tracing.ts 中实现并有针对超长路径的线性时间复杂度回归测试。Authorization: Bearer头会自动注入无需手动配置。4.2 发送器与处理器选择在setupIfNeeded中src/tracing.ts导出器会创建OTLPTraceExporter并根据disableBatch决定使用哪种 span 处理器this.exporter new OTLPTraceExporter({ url: this.config.endpoint, headers: this.config.headers, timeoutMillis: this.config.timeoutMillis, }); this.processor this.config.disableBatch ? new SimpleSpanProcessor(this.exporter) : new BatchSpanProcessor(this.exporter, { maxExportBatchSize: this.config.batchSize, exportTimeoutMillis: this.config.timeoutMillis, });disableBatch: true使用SimpleSpanProcessor每个 span 结束立即发送延迟最低但请求量最大默认批处理模式使用BatchSpanProcessor按batchSize默认 512批量导出吞吐更高realtime: true在handleSpanEnded中每次processor.onEnd后调用forceFlush适合希望近乎实时看到 trace 的场景冒烟脚本 scripts/smoke.mjs 即采用realtime: true验证导出链路。五、追踪导出的工作流程与实现原理5.1 事件路由仅导出已结束的 spanLaminarExporter继承自BaseExporter通过重写_exportTracingEvent处理追踪事件src/tracing.tsprotected async _exportTracingEvent(event: TracingEvent): Promisevoid { // Track hierarchy on span start to build lmnr.span.path/ids_path for child spans. if (event.type TracingEventType.SPAN_STARTED !event.exportedSpan.isEvent) { this.handleSpanStarted(event.exportedSpan); return; } // Only export when the span is ended (including event spans). if (event.type ! TracingEventType.SPAN_ENDED) { return; } await this.handleSpanEnded(event.exportedSpan); }即span 开始时仅记录层级关系用于构建路径属性只有在SPAN_ENDED时才真正转换为 OTel span 并交给 processor 导出。5.2 层级追踪lmnr.span.path 与 lmnr.span.ids_pathLaminar 需要知道 span 在 trace 中的嵌套路径。导出器内部维护一个traceMapMaptraceId, TraceState在 span 开始或事件 span 结束时兜底根据父 span 的路径拼接出当前 span 的路径lmnr.span.path由各层 span 的 name 组成的数组如[root, gen]lmnr.span.ids_path由各层 span 的 ID 转换成的 UUID 数组如[root-uuid, child-uuid]。handleSpanEnded中还有引用计数清理逻辑当一个 trace 的activeSpanIds为空时会从traceMap中删除该 trace 的状态避免内存泄漏见 src/tracing.ts。5.3 span 类型映射Mastra 的SpanType会被映射为 Laminar 的三类 span 类型mapLaminarSpanType见 src/tracing.tsMastra SpanTypeLaminar 类型MODEL_GENERATION/MODEL_STEP/MODEL_CHUNKLLMTOOL_CALL/MCP_TOOL_CALL/PROVIDER_TOOL_CALLTOOL其他如AGENT_RUN、WORKFLOW_RUN等DEFAULT同时OTel 的SpanKind映射为MODEL_GENERATION与MCP_TOOL_CALL使用SpanKind.CLIENT其余使用SpanKind.INTERNAL。5.4 LLM 相关的 GenAI 语义属性对于MODEL_GENERATION类型的 span导出器会提取ModelGenerationAttributes并写入 Laminar 后端使用的 GenAI 属性见buildLaminarAttributes与formatLaminarUsagegen_ai.systemprovider 名称会经过normalizeProvider归一化取点号前的部分并转小写例如ai-sdk/openai→openaigen_ai.request.model/gen_ai.response.model请求/响应模型名gen_ai.usage.input_tokens/gen_ai.usage.output_tokens输入/输出 token 数gen_ai.usage.cache_creation_input_tokens/gen_ai.usage.cache_read_input_tokens缓存写入/读取的 token 数来自usage.inputDetails.cacheWrite/cacheRead。5.5 输入输出与关联属性lmnr.span.input/lmnr.span.outputspan 的输入输出会被序列化写入。对于MODEL_GENERATION的输入getLaminarSpanInput会优先提取其中的messages数组——Laminar 在收到消息列表形式的lmnr.span.input时可以渲染丰富的聊天视图lmnr.span.type见上文的类型映射lmnr.span.instrumentation_source固定为javascriptlmnr.span.language_version写入process.version关联属性Association propertiesspan.metadata中的sessionId、userId会映射为lmnr.association.properties.session_id/user_id其余 metadata 以lmnr.association.properties.metadata.key形式透传仅接受标量与同构数组其余值 JSON 序列化lmnr.association.properties.tags根 spanisRootSpan的tags数组会写入该属性。5.6 错误与异常处理当 span 带有errorInfo时buildStatusAndEvents见 src/tracing.tsOTel span 状态置为SpanStatusCode.ERRORmessage 为errorInfo.message追加一个名为exception的事件包含exception.message、exception.type固定Error以及可选有 stack 时的exception.stacktrace。5.7 测试用例佐证仓库中的单元测试 src/tracing.test.ts 对上述行为做了完整验证测试中 mock 了 OTLP 导出器与 span 处理器不触网构造 root child 两级 span验证子 span 的lmnr.span.path为[root, gen]、lmnr.span.ids_path为两个 UUID验证lmnr.span.type为LLMlmnr.span.input/output为 JSON 字符串验证gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens等 GenAI 属性正确写入验证otelSpanIdToUUID/otelTraceIdToUUID的 UUID 转换逻辑验证stripTrailingSlash的边界行为含无 ReDoS 风险的线性复杂度回归测试。六、评分回传将 scorer 结果写入 Laminar Evaluators除追踪外LaminarExporter还支持把评估器评分回传到 Laminar。当前推荐的方式是走 Mastra 可观测性的评分事件管线调用mastra.observability.addScore触发ScoreEvent导出器的onScoreEvent会将评分上报到${baseUrl}/v1/evaluators/score。onScoreEvent的请求体结构如下见 src/tracing.ts 的submitScore{ name: scorerName 或 scorerId, score: 0.75, source: Code, metadata: { ...metadata..., reason: reason }, spanId: span-uuid // 有 spanId 时 // 或 traceId: trace-uuid // 无 spanId 时 }关键细节UUID 转换OTel 的 traceId32 位十六进制与 spanId16 位十六进制会被otelTraceIdToUUID/otelSpanIdToUUID转换为 UUID 格式后再提交与 Laminar 侧的 ID 规范对齐身份字段同时提供spanId时评分挂在具体 span 上否则挂在整个traceId上认证评分请求使用Authorization: Bearer apiKey与content-type: application/json请求头超时使用AbortControllertimeoutMillis默认 30000ms控制超时会记录timedOut日志失败处理非 2xx 响应记录 warn 日志网络异常记录 error 日志不会抛出中断主流程。测试 src/tracing.test.ts 中验证了_addScoreToTrace与onScoreEvent都会 POST 到包含/v1/evaluators/score的 URL请求体中的traceId/spanId均为 UUID 格式metadata会合并reason字段。注意_addScoreToTrace是已弃用的旧接口源码中以deprecated标注仅保留向后兼容实际转发到与onScoreEvent相同的 Laminar 评分端点。新代码请统一使用mastra.observability.addScore。七、生命周期管理flush 与 shutdownLaminarExporter提供两个生命周期方法async flush(): Promisevoid { if (this.isDisabled || !this.processor) return; await this.processor.forceFlush(); } async shutdown(): Promisevoid { await this.processor?.shutdown(); this.traceMap.clear(); await super.shutdown(); }flush()强制刷出缓存的 spans 但不关闭导出器非常适合 Serverless 环境——在运行时实例被终止前确保 spans 已导出基类 observability/mastra/src/exporters/base.ts 的默认实现为 no-opLaminar 覆盖了该实现shutdown()关闭 processor 并清空traceMap状态再调用基类 shutdown 完成收尾。八、端到端冒烟验证仓库提供了可选的冒烟脚本 scripts/smoke.mjs用于在真实 Laminar 环境中验证导出链路。运行前提是设置LMNR_PROJECT_API_KEY脚本会构造一个AGENT_RUN根 span 与一个MODEL_GENERATION子 span含 provider/model/usage 与 session/user 关联属性以realtime: true模式导出并在结束时打印 traceId 与转换后的 UUID供你在 Laminar 控制台检索验证LMNR_PROJECT_API_KEYyour-key node scripts/smoke.mjs脚本内置 30 秒超时保护任何步骤失败都会以非零退出码结束。九、常见问题与排查建议导出器被禁用日志出现laminar disabled: Missing required API key...说明LMNR_PROJECT_API_KEY未设置且未传apiKey。检查环境变量是否在进程启动前注入。看不到实时数据默认使用批处理模式span 会攒批发送如需近乎实时可见设置realtime: true或disableBatch: true。追踪数据发往了错误地址确认LMNR_BASE_URL/LAMINAR_ENDPOINT或baseUrl/endpoint配置是否符合你的 Laminar 环境默认https://api.lmnr.aitraces 端点为${baseUrl}/v1/traces。评分没有出现在 Evaluators确认使用的是mastra.observability.addScore新管线而非已弃用的_addScoreToTrace并检查score.traceId是否存在onScoreEvent中if (!score.traceId) return;会直接跳过。错误 span 的状态errorInfo会映射为 OTelERROR状态与exception事件可在 Laminar 中按错误状态筛选。十、相关资源包文档observability/laminar/README.md核心实现src/tracing.ts单元测试src/tracing.test.ts冒烟脚本scripts/smoke.mjs导出器基类observability/mastra/src/exporters/base.ts可观测性配置与校验 schemaobservability/mastra/src/config.ts版本历史observability/laminar/CHANGELOG.md【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考