arize-instrumentation

Arize 仪表化技能

首次为应用添加 Arize AX 跟踪：检测技术栈 → 获取唯一匹配的集成文档 → 接入自动仪表化 → 验证跟踪数据已发送。

在本地路由。 根据检测到的技术栈，通过 references/integration-routing.md 映射到单个文档页面，并且只获取该页面。当应用使用 Agent 框架时，应根据框架路由，而不是它封装的提供商 SDK——框架应用中单独导入 openai/anthropic 并不意味着目标集成是对应的提供商；只有当应用直接调用提供商 SDK，且没有使用框架时，才路由到提供商页面。如果该技术栈未列出，请按路由说明在 llms.txt 中搜索其集成页面；如果没有匹配项，则使用手动仪表化。切勿批量读取汇总文件 PROMPT.md。

规则： 修改前先检查；跟踪只作为附加功能，绝不更改业务逻辑；遵循现有风格；代码中不得包含机密，也绝不要要求用户在聊天中粘贴机密（API 密钥、令牌）——只引用 ARIZE_API_KEY/ARIZE_SPACE_ID 环境变量，由用户在自己的 .env/shell 中设置；保留应用的 Arize 区域/导出端点，或询问用户，而不要擅自假设为 US——参见 references/regions-and-endpoints.md；修改持久化本地状态（ax 配置文件、.zshrc、环境变量）前先征求同意——参见 references/ax-profiles.md。

阶段 1：分析（只读——不修改代码/文件）

从清单文件和导入语句中检测：语言、包管理器、大模型提供商、框架、现有跟踪（TracerProvider、register()、ARIZE_*/OTEL_*、Datadog/Honeycomb）、现有 Arize 端点/区域配置（ARIZE_COLLECTOR_ENDPOINT、代码中的 Arize 端点选项，或经确认指向 Arize 的 OTEL_EXPORTER_OTLP_ENDPOINT），以及应用是否会运行工具 / Agent 循环（仅当匹配的框架仪表化程序尚未覆盖时，才需要手动添加 CHAIN/TOOL span——在阶段 2 中确定）。先确认范围——如果是单体仓库、包含多个服务或使用多个框架，必须先询问“具体是哪一个？”，再进行任何操作；不要替用户做决定。

输出简短摘要（技术栈、建议的集成方式、现有跟踪、范围）。如果目标明确且用户要求立即进行仪表化，则继续；如果存在歧义或用户只要求分析，则停止并确认。

阶段 2：实施（确认目标后）

1. 获取匹配的集成文档，并严格按照其中的安装和接入说明操作。
2. 安装——先使用检测到的包管理器安装，再编写代码；具体依赖包以匹配的文档为准。Python 基础依赖：arize-otel（当前 PyPI 版本）+ openinference-instrumentation-{name}（包名使用连字符，导入名使用下划线）。TS/JS：@opentelemetry/sdk-trace-node + 匹配的 @arizeai/openinference-*（或第一方导出器，例如 Mastra 的 @mastra/arize）。Go 没有集成文档——有关安装、接入、刷新和手动 span，请参见 references/go.md。
3. 凭据和区域——应用需要 API 密钥 + Space + 导出器端点/区域。只检查目标应用自身的配置；绝不要扫描同级仓库/ shell 文件、泄露机密或接受用户粘贴的密钥。参见 references/credentials-and-config.md、references/regions-and-endpoints.md 和 references/ax-profiles.md。
4. 将初始化集中在一个模块中，并确保在创建任何大模型客户端之前完成。对于已有的 OTel，应将 Arize 作为额外导出器添加；不要替换现有导出器。
5. 如果所选的 TypeScript 集成支持过滤，请过滤掉非 GenAI 的 span。 将此设为 Arize 导出器的默认配置，避免通用 HTTP/fetch、框架和基础设施 span 淹没项目。对于搭配 @arizeai/openinference-vercel 使用的 Vercel AI SDK v7，请在 OpenInferenceSimpleSpanProcessor 上设置 spanFilter: isOpenInferenceSpan 和 reparentOrphanedSpans: true；否则，AI span 可能仍会引用已过滤掉的 HTTP 父 span。对于搭配 @mastra/observability 使用的 Mastra，请先确认应用不依赖 GENERIC span 作为唯一面向用户的边界，再在 Arize 可观测性配置上设置 spanFilter: span => span.type !== SpanType.GENERIC。不要假设存在通用的 OpenTelemetry 选项：请检查匹配的集成当前支持的 API。如果它没有过滤功能，就不要为 Arize 管道启用无关的 HTTP/自动检测，或者使用受支持的处理器/收集器过滤器来保留预期的 GenAI span。保留有用的语义请求边界；过滤策略不应悄然丢弃应用唯一的用户输入/最终答案 span。

自动检测与手动检测：优先使用自动检测工具——不要手动创建它已覆盖的 span（这会导致 span 重复，并偏离语义约定）。仅当自动检测工具无法看到某段逻辑，或技术栈完全没有自动检测工具时，才添加手动 span。当应用直接调用提供商 SDK 时，OpenAI 和 Anthropic SDK 检测工具会捕获 LLM 调用——包括模型的工具调用请求（名称 + 参数）——但不会捕获工具的执行、返回值或 Agent/链边界。使用原始 SDK 且自行处理工具调用循环的应用必须为每次执行添加 TOOL span（以捕获结果），并添加 CHAIN（或 AGENT）span 来组织这一轮调用；否则这些内容都不会显示。请在存在相应函数的地方使用 @tracer.tool/@tracer.chain 装饰器完成此操作（它们会自动设置类型、元数据和状态）；仅在没有可装饰函数的地方手动创建 span。有些 Agent 框架通过自己的客户端层驱动模型，并会生成自己的 OpenTelemetry span；对于这些框架，提供商检测工具不会捕获任何内容，因此应参阅框架集成页面进行检测，而不是使用提供商 SDK。框架检测工具（LangChain/LangGraph/OpenAI Agents SDK）通常会覆盖工具和链——决定是否跳过手动创建 span 前，请先查看匹配文档并确认。使用 register()/arize-otel-go 进行设置；请参阅 references/manual-spans.md 和 手动检测。 跨技术栈通用：

• 必须设置项目名称——缺少项目名称会导致 HTTP 500（仅设置 service.name 不够）。将其设为资源属性：Python 使用 register(project_name=…)；TS 使用 SEMRESATTRS_PROJECT_NAME/model_id；Go 使用 Options{ProjectName} 或 openinference.project.name。
• 不要手动创建 TracerProvider/导出器——使用 register()/arize-otel-go；仅在集成现有 Provider 时使用原始 OTel。
• **顺序：**注册 tracer → 插桩器 → 客户端。
• **区域：**不要假定使用美国区域。保留 ARIZE_COLLECTOR_ENDPOINT 或已确认指向 Arize 的端点。通用的 OTEL_EXPORTER_OTLP_ENDPOINT 可能属于现有的非 Arize 导出器；应单独保留该导出器，并询问 Arize SaaS 区域，而不要盲目复用此端点。请参阅 references/regions-and-endpoints.md。
• 优先使用 @tracer.* 装饰器，而不是手动创建 span——它们会自动设置类型、input.value/output.value、完整的 TOOL 元数据和终止状态，因此不会像手动创建的 span 那样产生 UNSET/不完整的 span。装饰器位于函数定义上，因此动态分派并不是手动创建 span 的理由。请参阅 references/manual-spans.md。
• 手动创建的 span 必须在退出前设置：openinference.span.kind、input.value/output.value，以及 TOOL span 的全部 tool.name/tool.description/tool.parameters。最容易遗漏的一行：start_as_current_span 会将引发的异常记录为 ERROR，但绝不会设置 OK——因此需要在成功路径中添加 span.set_status(Status(StatusCode.OK))，否则该 span 导出的状态会是 UNSET，评分也会失败。请参阅 references/manual-spans.md。
• 退出前刷新（CLI/脚本/笔记本），否则异步导出会丢失：Python 使用 force_flush()+shutdown()；TS 使用 shutdown()；Go 使用 defer tp.Shutdown(ctx)（绝不要在 span 执行期间调用 log.Fatalf/os.Exit）。请参阅 references/session-tracking.md。
• **会话：**对于明显的多轮交互（例如多轮聊天机器人），或用户提出要求时，添加 session.id，以便将各轮归为一次对话——请参阅 references/session-tracking.md。
• 绝不要悄悄覆盖应用的项目/空间/ID/端点——应指出不匹配之处。

验证

只有在应用构建/类型检查通过、启用追踪后能够启动、至少发出 1 个真实请求，并且你已在 Arize 中确认 trace，或准确说明应用与 Arize 之间的阻碍时，才算完成。触发一次大模型调用，然后使用 arize-trace 技能确认 spans（类型、input.value/output.value、父子关系；如果运行了工具，还要确认 CHAIN+TOOL）。对于提供筛选功能的 TypeScript 集成，还要检查 span 筛选器。检查新 trace 中的所有 spans，确认没有缺失输入/输出，包括尚未分类的 REST/HTTP spans；按照 references/verification.md 决定是添加语义请求/响应数据、添加明确的 AI 工作流边界，还是筛除无关的基础设施 spans。与用户一起决定如何表示应用无法安全或正确捕获的数据。没有 trace 时：检查 ARIZE_SPACE_ID/ARIZE_API_KEY、初始化顺序、已配置的收集器端点/区域以及导出器日志（GRPC_VERBOSITY=debug）；常见原因包括区域端点错误、缺少项目名称（500）、短生命周期进程未刷新，或导出/验证时的凭证上下文不匹配（报告此问题，不要重写配置——references/credentials-and-config.md）。有关确定性的 trace 查找顺序、阻碍分类和 trace 到达后的冒烟检查，请参阅 references/verification.md。

确认跟踪后

报告各个里程碑（安装 → 接线 → 运行 → 导出 → 验证）；将已恢复的错误标记为已解决；最后将已完成事项与阻塞项分开列出。然后简要提供下一步：arize-trace（检查/调试）、arize-dataset（整理）、arize-evaluator（评估）、arize-experiment（比较）、arize-prompt-optimization（改进提示词）。质量问题 → 首选 arize-trace。

参考资料

integration-routing（路由器） · credentials-and-config · regions-and-endpoints · ax-profiles · manual-spans · go（Go — 没有对应的文档页面） · session-tracking · verification · tracing-assistant-mcp。