Mastra 可观测性接入实战使用 mastra/arize 将 Agent 追踪导出到 Arize AX 与 Phoenix【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本篇技术指南以 Mastra 开源仓库中的mastra/arize可观测性包observability/arize/README.md为核心讲解如何在 TypeScript 版 Mastra 应用中接入 OpenInference 生态的可观测性平台无论是托管的 Arize AX还是自托管的 Phoenix都可以通过一行ArizeExporter配置将 Agent、LLM、工具与工作流调用链完整导出。读完本文你将掌握mastra/arize的安装、环境变量与配置项语义、两种鉴权模式的区别以及底层 OpenInference 语义转换span 类型映射、Token 用量、会话与用户标识的工作原理从而能够独立完成生产级可观测性接入与问题排查。一、mastra/arize 是什么mastra/arize是 Mastra 官方提供的可观测性导出器核心能力是将 Mastra 采集到的 trace 数据导出到任何支持 OpenInference 语义的 OpenTelemetry 可观测性平台典型目标包括Arize AXArize 推出的生成式 AI 可观测性托管平台默认接收端点https://otlp.arize.com/v1/tracesPhoenixArize 开源的自托管 LLM 追踪与分析平台通常运行在本地通过PHOENIX_COLLECTOR_ENDPOINT指定收集端点。关于 OpenInference 本身的语义规范可以参考 Arize 开源的 OpenInference Semantic Conventions 规范说明本文章不展开其全文仅围绕 Mastra 仓库内代码可验证的实现进行讲解。从包结构上看observability/arize/package.json 显示该包名为mastra/arize当前版本为1.3.16-alpha.1要求 Node.js22.13.0并以mastra/otel-exporterworkspace 依赖作为底层导出基础在此基础上叠加了 Arize/OpenInference 专属的语义转换层。数据流转链路从源码结构可以梳理出完整的 trace 导出链路Mastra Core 采集 TracingEventSPAN_ENDED ↓ ArizeExporter继承 mastra/otel-exporter 的 OtelExporter ↓ OpenInferenceOTLPTraceExporter继承 OTLPTraceExporter做语义转换 ↓ OTLP http/protobuf 协议发送到 Arize AX / Phoenix其中ArizeExporter类定义在 observability/arize/src/tracing.ts语义转换的核心逻辑OpenInferenceOTLPTraceExporter定义在 observability/arize/src/openInferenceOTLPExporter.ts。二、安装在 Mastra 项目中通过 npm 安装npm install mastra/arize根据 observability/arize/package.json 的声明该包的 peerDependencies 要求mastra/core 1.16.0-0 2.0.0-0实际使用时应确保你的mastra/core版本落在该范围内当前仓库内的 core 版本满足此约束。包内部依赖arizeai/openinference-genai与arizeai/openinference-semantic-conventions来完成属性转换无需额外手动安装。三、快速开始第一步设置环境变量根据 README 的说明至少需要设置收集端点若目标是需要鉴权的实例还需设置 API Key# Phoenix / 通用 OpenInference 收集器 export PHOENIX_COLLECTOR_ENDPOINThttp://localhost:6006/v1/traces # 需要鉴权的实例Phoenix Cloud、Arize AX 等 export PHOENIX_API_KEYyour-api-key第二步在 Mastra 中注册 observability 配置import { Mastra } from mastra/core/mastra; import { Observability } from mastra/observability; import { ArizeExporter } from mastra/arize; export const mastra new Mastra({ observability: new Observability({ configs: { arize: { serviceName: my-service, exporters: [new ArizeExporter()], }, }, }), });这里configs下的arize键名与ArizeExporter实例的name属性源码中固定为arize保持一致Observability构造函数会用 Zod schema 对配置做校验见 observability/mastra/src/default.ts配置非法时会抛出OBSERVABILITY_INVALID_CONFIG错误并给出字段级提示。验证是否接入成功本地 Phoenix启动 Phoenix 后访问其 UI运行一次 Agent/工作流调用即可看到以service.name为标识的 trace若配置缺失ArizeExporter会以禁用状态启动不抛异常排查时关注日志中的[ArizeExporter]前缀提示详见下文自动禁用逻辑。四、ArizeExporter 配置详解虽然快速开始里new ArizeExporter()不传任何参数但源码 observability/arize/src/tracing.ts 定义了完整的ArizeExporterConfig所有字段均可选配置项类型说明对应环境变量spaceIdstringArize AX 模式必填Arize 工作区空间 ID用于构造space_id请求头ARIZE_SPACE_IDapiKeystringArize AX 或需要 Authorization 头的收集器必填ARIZE_API_KEY/PHOENIX_API_KEYendpointstringtrace 导出目标端点。Phoenix、Phoenix Cloud 及其他收集器必填Arize AX 模式下可选有默认端点PHOENIX_COLLECTOR_ENDPOINT/PHOENIX_ENDPOINTprojectNamestring可选项目名作为 OpenInference 资源属性openinference.project.name写入ARIZE_PROJECT_NAME/PHOENIX_PROJECT_NAMEheadersRecordstring, string追加到每个 OTLP 请求上的自定义请求头—resourceAttributesRecordstring, string追加到资源上的自定义属性继承自OtelExporterConfig—logLeveldebug \| info等调试日志开关继承自OtelExporterConfig—配置优先级ArizeExporter构造函数observability/arize/src/tracing.ts明确的取值优先级为构造函数传入的 config 最高其次为ARIZE_*系列环境变量最后为PHOENIX_*系列环境变量作为通用 OpenInference 兼容方案的兜底。端点解析的优先级则略有不同config.endpoint PHOENIX_COLLECTOR_ENDPOINT PHOENIX_ENDPOINT ARIZE_AX_ENDPOINT仅当设置了 spaceId其中ARIZE_AX_ENDPOINT为常量https://otlp.arize.com/v1/traces只有在传入了spaceIdArize AX 模式且未显式指定任何端点时才会作为回退使用。两种鉴权模式根据是否传入spaceId构造函数会走两套不同的请求头逻辑见 observability/arize/src/tracing.tsArize AX 模式传入spaceId必须同时提供apiKey否则导出器被禁用请求头设置space_id: spaceId与api_key: apiKey端点未指定时自动使用ARIZE_AX_ENDPOINT。标准 OTLP 模式未传spaceId但有apiKey请求头设置为Authorization: Bearer apiKey适配 Phoenix Cloud 及其他使用标准 Bearer 鉴权的收集器。这一双模式设计在 observability/arize/src/tracing.config.test.ts 中有直接验证测试断言传入spaceId与apiKey后provider.custom的 endpoint 会被解析为ARIZE_AX_ENDPOINT且 headers 为{ space_id, api_key }、协议为http/protobuf同时验证了自定义 headers、resourceAttributes 的合并行为。自动禁用逻辑不抛异常的降级ArizeExporter采用配置不完整就静默禁用的策略避免应用启动直接崩溃Arize AX 模式缺apiKey禁用提示设置ARIZE_API_KEY或在 config 中传apiKey端点完全缺失非 AX 模式且未配端点禁用提示设置PHOENIX_COLLECTOR_ENDPOINT、或传ARIZE_SPACE_ID进入 AX 模式、或在 config 中传endpoint。被禁用时构造器会以endpoint: http://disabled的占位配置创建底层 exporter 并调用setDisabled(reason)。排查时可从日志中搜索[ArizeExporter]前缀的禁用原因。五、底层语义转换原理OpenInference 属性映射ArizeExporter真正将 Mastra trace 翻译成 Arize/Phoenix 可理解数据的关键是自定义的OpenInferenceOTLPTraceExporterobservability/arize/src/openInferenceOTLPExporter.ts。它在每次export时对 span 做一次属性重写主要工作如下。1. Span 类型 → OpenInference Span KindOpenInference 用openinference.span.kind区分 trace 中的不同角色LLM、TOOL、AGENT、CHAIN 等。Mastra 的 span 类型通过mastra.span.type属性标记映射表源码 L55-L65为Mastra span 类型OpenInference Span Kindmodel_generation、model_step、model_chunkLLMtool_call、mcp_tool_callTOOLagent_runAGENT其余所有类型workflow_run、workflow_step、processor_run、generic及未来新增类型CHAIN默认值这套映射在 observability/arize/src/tracing.test.ts 中被逐一测试覆盖例如agent_run断言为AGENT、model_generation断言为LLM、workflow_run/workflow_step/processor_run断言为CHAIN、MCP 工具调用断言为TOOL并保留tool.name、tool.description、tool_call.id与mastra.mcp_tool_call.server_name等元数据。2. 输入/输出消息与调用参数转换器优先使用 OpenTelemetry GenAI 语义约定中的属性gen_ai.input_messages、gen_ai.output_messages、gen_ai.tool_call.arguments、gen_ai.tool_call.result并将它们写入 OpenInference 的input.value/output.valuemime_type统一为application/json。对于非 LLM/工具类 span则回退读取mastra.model_step.input、mastra.model_step.output、mastra.model_chunk.output甚至遍历mastra.*命名空间下以.input/.output结尾的任意属性如mastra.processor_run.input、mastra.workflow_run.input保证工作流与处理器链路的入参出参也能被 OpenInference 后端索引。3. Token 用量转换OTel 的 GenAI 用量属性gen_ai.usage.*会被转换成 OpenInference 的llm.token_count.*系列源码 L74-L122源属性OTel目标属性OpenInferencegen_ai.usage.input_tokensllm.token_count.promptgen_ai.usage.output_tokensllm.token_count.completion两者都存在时llm.token_count.total输入 输出gen_ai.usage.cache_read.input_tokensllm.token_count.prompt.details.cache_readgen_ai.usage.cache_creation.input_tokensllm.token_count.prompt.details.cache_writegen_ai.usage.reasoning_tokensllm.token_count.completion.details.reasoninggen_ai.usage.audio_input_tokensllm.token_count.prompt.details.audiogen_ai.usage.audio_output_tokensllm.token_count.completion.details.audio测试tracing.test.ts验证了两个关键行为部分用量数据不会补零例如只有 inputTokens 时completion 与 total 保持 undefined 而非 0以及 cache/reasoning/audio 明细都能正确映射。4. 会话与用户标识Mastra 元数据中的threadId与userId会被转换为 OpenInference 原生语义的session.id与user.id源码 L165-L181随后从mastra.metadata.*中移除避免重复字段。测试 tracing.test.ts 明确断言threadId/userId映射后原始属性不再存在。这是 Arize/Phoenix 中按会话聚合、按用户分析的基石。5. Tags 与自定义元数据Tags根 span 上由 SpanConverter 序列化得到的mastra.tagsJSON 字符串会被映射为 OpenInference 原生tag.tags且仅根 span 携带子 span 与空 tags 数组都会被过滤见 tracing.test.ts。自定义元数据mastra.metadata.*前缀下剩余的键值对被聚合成一个 JSON 字符串写入metadata属性best-effort 方式序列化失败则忽略供后端做自定义属性检索。6. 底层导出链路参数作为基类的OtelExporterobservability/otel-exporter/src/tracing.ts为 Arize 导出提供了 OTLP 传输与批处理能力默认参数为批量导出大小512batchSize可覆盖队列容量2048调度延迟5000msscheduledDelayMillis导出超时30000mstimeout可覆盖协议http/protobuf信号路径自动拼接/v1/traces与/v1/logs。Arize 模式下 trace 与 log 两个信号默认均开启signals.traces/logs可显式关闭。六、验证与测试仓库为mastra/arize提供了两套 vitest 测试可作为接入行为的权威参考observability/arize/src/tracing.config.test.ts验证端点回退、双鉴权模式 headers、自定义 headers/resourceAttributes 合并observability/arize/src/tracing.test.ts通过 mock 的BatchSpanProcessor直接断言导出后的 span 属性快照涵盖消息结构、Token 计数、会话/用户映射、tags、span kind 映射、MCP 工具元数据保留、model_chunk输出与 span 命名如model_chunk gpt-4o等全部转换行为。本地运行测试cd observability/arize pnpm test七、常见问题排查配置正确但 Arize 控制台看不到 trace先确认ArizeExporter未被禁用——日志中搜索[ArizeExporter]前缀的 disabled 原因再确认端点可达本地 Phoenix 默认监听6006端口。Trace 类型在 UI 中显示为 CHAIN 而非 LLM/TOOL检查 span 是否携带了mastra.span.type属性根据映射表只有model_*、tool_call、mcp_tool_call、agent_run才会被映射为更具体的 kind。Token 面板缺少 totalllm.token_count.total仅在 input 与 output 同时存在时才会写入这是刻意的设计而非缺陷。Tag 在 Phoenix 中不可见tags 仅写在根 span 上检查该 span 是否为根 span。Node 版本不满足该包要求 Node.js22.13.0低于此版本安装/运行会失败。相关文件索引包说明文档observability/arize/README.md导出器与配置实现observability/arize/src/tracing.tsOpenInference 语义转换实现observability/arize/src/openInferenceOTLPExporter.ts转换行为测试observability/arize/src/tracing.test.ts配置解析测试observability/arize/src/tracing.config.test.ts底层 OTLP 导出基类observability/otel-exporter/src/tracing.ts可观测性注册入口observability/mastra/src/default.ts【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考