用应用元数据把多租户 Python 服务的每个 span…

当一个 Python 服务需要按 agent、租户、团队或请求的元数据，把各自的 span 发送到对应的 Arize space 和 project 时使用。

适用场景

解决思路

1. 确认目标 Python 服务和入口点，梳理现有 tracing 初始化、provider/exporter、instrumentor 以及客户端创建顺序。
2. 找到拥有目标元数据的请求或 agent 执行边界，确定能解析出 Arize space_id 和 project_name 的稳定元数据字段及其现有来源。
3. 检查可能超出请求上下文的异步任务、线程池、队列或后台 worker。
4. 找到应用的测试命令和现有测试风格；只检查目标应用的配置，不要到无关仓库、兄弟服务、shell 启动文件或任意 .env 文件中找凭据。
5. 若服务范围、元数据字段、映射来源或目标行为不明确，先停下来问最小必要问题，不要先安装包或改代码；四项都清楚时简要总结契约再继续。
6. 用项目的包管理器要求 arize-otel>=0.11.0，不改动无关依赖。
7. 若应用没有现成的 OpenTelemetry provider，在 instrumentor 和 LLM 客户端之前调用 register_with_routing(api_key=os.environ["ARIZE_API_KEY"]) 初始化路由。
8. 若应用已有带非 Arize 遥测的 provider，保留它并添加 ArizeRoutingSpanProcessor(api_key=os.environ["ARIZE_API_KEY"], endpoint=Endpoint.ARIZE, transport=Transport.GRPC)，复用应用已配置的 endpoint 和 transport。
9. 绝不要在另一个全局 provider 已安装后再调用 register_with_routing；若 provider 还有固定 Arize processor/exporter，在初始化时先移除该固定路径再添加路由，因为 OpenTelemetry processor 启动后无法安全移除。
10. 适配应用现有元数据模型实现解析器，返回 space_id 和 project_name 两个非空值或返回无目标；映射数据保留在现有来源中，不要在 tracing 代码里重复。
11. 在拥有元数据且包含所有子 span 的最高边界进入路由上下文：解析成功且两个值非空时用 set_routing_context(space_id=..., project_name=...) 包裹整个操作。
12. 只捕获解析器预期的查找/配置异常，不要掩盖无关的应用失败。
13. 解析失败或无目标时，用 context_api.attach(context_api.Context()) 在全新 OpenTelemetry 上下文中运行该操作，并在 finally 中 detach，防止继承的路由值泄漏到其他租户；记录不含密钥或敏感元数据的警告。
14. 不要在 span 已开始后再设置路由；路由上下文内自动插桩和手动创建的子 span 会继承 arize.space_id 和 arize.project.name。
15. 后台任务要显式传播 OpenTelemetry 上下文，或在 worker 中重新解析并进入新的路由上下文，绝不依赖队列或线程边界之后的请求本地上下文。
16. 运行解析器和执行边界的聚焦单元测试。
17. 验证两组不同元数据产生两组不同的 space/project 对。
18. 验证子 span 继承所选 pair。
19. 验证并发操作不会泄漏路由上下文。
20. 验证未知元数据和解析器失败会清除继承的路由、不向任何回退目标导出 span，且业务逻辑继续运行。
21. 验证已有的非 Arize exporter/processor 仍保持挂载，且没有残留固定 Arize 路径。
22. 在非生产 space 中为每个目标触发一个唯一命名的 trace。
23. 用相同凭据上下文运行 arize-trace，确认每个 trace 只存在于预期目标中。
24. 短生命周期脚本在退出前调用 force_flush() 和 shutdown()。
25. 最终以 confirmed、confirmed with warnings 或精确的 blocker 收尾；被要求做实时验证时，绝不能仅凭单元测试报告完成。
26. 两个路由值都必填，缺少任一值的 span 会被跳过。
27. ArizeRoutingSpanProcessor 会为每个唯一 space 创建并缓存一个 processor，实现前要标记无界或高基数的 space ID。
28. 路由只选择 space 和 project，其他客户元数据仍应放在常规 OpenInference 属性中。
29. 若 dogfooding 暴露 arize-otel 缺少能力，停下来提议单独的 SDK 变更，不要添加兼容性 hack。

适用边界 · 注意事项

• 不要用于普通的单 project tracing，那种情况应使用 arize-instrumentation。
• 本技能不会在导出后重新路由 span、回填历史 span、创建 Arize space/project，也不会凭空发明客户特定的元数据映射。
• 若没有一个对所有目标 space 都授权的 API key，应停止并报告凭据阻塞问题。