arize-span-routing

Arize Span Routing 技能

使用此技能，将一个 Python 服务中的每个追踪操作发送到正确的 Arize 空间和项目。每个操作都必须在其第一个 Span 开始前解析出唯一的 space_id 和 project_name。

普通的单项目追踪不使用此技能；请使用 arize-instrumentation。此技能不会在导出后重新路由 Span、回填历史 Span、创建 Arize 空间或项目，也不会臆造特定客户的元数据映射。

安全规则

• 切勿猜测目标位置，也不要悄悄使用其他租户的目标位置。
• 切勿在代码中嵌入 API 密钥，也不要让用户将密钥粘贴到聊天中。从环境中读取 ARIZE_API_KEY。
• 保留现有的非 Arize 导出器和处理器。移除或替换固定目标位置的 Arize 导出路径，以免路由后的 Span 也被复制到该目标位置。
• 缺失、无效或不可用的路由元数据必须使业务操作继续运行，但不将其 Span 导出到 Arize。在新的 OpenTelemetry 上下文中运行该操作，防止陈旧的路由值跨租户泄漏。记录警告时不得包含密钥或敏感元数据值。
• 对所有目标空间使用同一个有权访问的 API 密钥。如果该密钥无权访问所有目标空间，请停止并报告凭证阻碍。

阶段 1：检查并明确约定

只需检查到路由约定明确为止。

1. 确定需要修改的 Python 服务及其确切入口点。
2. 查找当前的追踪初始化、Provider/导出器、自动埋点工具以及客户端创建顺序。
3. 查找负责目标元数据的请求或 Agent 执行边界。
4. 确定可稳定解析出以下目标的元数据字段及其现有事实来源：
   • Arize space_id
   • Arize project_name
5. 检查可能超出请求上下文生命周期的异步任务、线程池、队列或后台工作进程。
6. 查找应用的测试命令和现有测试风格。

只检查目标应用的配置。不要搜索无关仓库、相邻服务、Shell 启动文件或任意 .env 文件来查找凭证。

如果服务范围、元数据字段、映射来源或目标行为不明确，请停止并提出必要的最少问题。不要先安装软件包或编辑代码。如果用户要求实施，且上述四项都已明确，请简要总结约定并继续。

阶段 2：实施

1. 确保存在路由支持

使用项目的软件包管理器，确保依赖 arize-otel>=0.11.0。不要更改无关依赖。

2. 仅初始化一次路由

对于尚无 OpenTelemetry Provider 的应用，请在自动埋点工具和 LLM 客户端之前初始化路由：

import os

from arize.otel import register_with_routing

tracer_provider = register_with_routing(
    api_key=os.environ["ARIZE_API_KEY"],
)

如果应用已拥有带有非 Arize 遥测的 Provider，请保留它并添加路由处理器：

import os

from arize.otel import ArizeRoutingSpanProcessor, Endpoint, Transport

tracer_provider.add_span_processor(
    ArizeRoutingSpanProcessor(
        api_key=os.environ["ARIZE_API_KEY"],
        endpoint=Endpoint.ARIZE,
        transport=Transport.GRPC,
    )
)

如果已配置端点和传输方式，请沿用应用的配置。全局 Provider 安装后，切勿再调用 register_with_routing。如果 Provider 还包含固定目标位置的 Arize 处理器/导出器，请在初始化时移除该固定路径后再添加路由；启动后无法安全地移除 OpenTelemetry 处理器。

3. 解析唯一的路由目标

适配应用现有的元数据模型；不要为了单次查找引入框架。解析器必须返回两个非空值，或不返回目标。映射数据应保留在现有事实来源中，不要在追踪代码中重复存储。

from dataclasses import dataclass


@dataclass(frozen=True)
class RoutingTarget:
    space_id: str
    project_name: str

仅当代码库中没有等效类型时才使用此类型。任何追踪工作开始前都必须验证解析结果。

4. 在完整操作范围内设置上下文

在包含元数据且涵盖所有子 span 的最高边界处进入路由上下文：

将下方的 RoutingLookupError 替换为解析器现有的特定查找／配置异常。

from opentelemetry import context as context_api
from arize.otel import set_routing_context


def run_without_arize_routing(request):
    token = context_api.attach(context_api.Context())
    try:
        return run_agent(request)
    finally:
        context_api.detach(token)


def handle_agent_request(request):
    try:
        target = resolve_routing_target(request.agent_metadata)
    except RoutingLookupError:
        logger.warning("Arize routing lookup failed; spans will not be exported")
        return run_without_arize_routing(request)

    if target is None or not target.space_id or not target.project_name:
        logger.warning("No Arize routing target; spans will not be exported")
        return run_without_arize_routing(request)

    with set_routing_context(
        space_id=target.space_id,
        project_name=target.project_name,
    ):
        return run_agent(request)

仅捕获解析器预期的查找／配置异常；不要掩盖无关的应用故障。在没有目标的路径上创建新上下文，是为了防止继承的路由值传递到 Arize。对于其他导出器，这可能会启动新 trace；租户隔离优先。如果必须保留分布式父级，请将缺少公开路由清除 API 的问题作为 SDK 后续事项报告，而不要使用私有上下文键。

在路由上下文中创建的所有自动插桩和手动子 span 都会继承 arize.space_id 和 arize.project.name。不要在 span 启动后设置路由。

对于后台工作，请显式传播 OpenTelemetry 上下文，或在工作线程中解析并进入新的路由上下文。绝不要在队列或线程边界之后依赖请求本地上下文。

有关 Agent 实验端点、现有提供方详情、并发规则、测试、验证和故障排查，请参阅 references/REFERENCE.md。

验证

1. 运行针对解析器和执行边界的单元测试。
2. 验证两个不同的元数据值会生成两组不同的空间／项目组合。
3. 验证子 span 会继承所选组合。
4. 验证并发操作不会泄漏路由上下文。
5. 验证未知元数据和解析器故障会清除继承的路由，不会将 span 导出到任何备用目标，并且业务逻辑仍能运行。
6. 验证预先存在的非 Arize 导出器／处理器仍保持连接，且不再存在固定的 Arize 路径。
7. 在非生产空间中，为每个目标触发一个名称唯一的 trace。
8. 使用相同的凭据上下文运行 arize-trace，确认每个 trace 只存在于其预期目标中。

对于生命周期较短的脚本，请在退出前调用 force_flush() 和 shutdown()。最终状态应为 已确认、已确认但有警告 或明确的阻塞原因；当请求了实时验证时，绝不要仅凭单元测试报告已完成。

防护措施与限制

• 必须提供两个路由值。缺少任一值的 span 都会被跳过。
• ArizeRoutingSpanProcessor 会为每个唯一空间创建并缓存一个处理器。实施前，请标记无界或高基数的空间 ID。
• 路由仅选择空间和项目；其他客户元数据仍应放入常规 OpenInference 属性中。
• 如果试用过程中发现 arize-otel 缺少某项功能，请停止并提出单独的 SDK 变更，而不是添加兼容性变通方案。

相关技能

• arize-instrumentation：首次追踪或单目标追踪
• arize-trace：导出后的验证与调试
• arize-admin：检查或管理已授权的空间和 API 密钥