arize-span-routing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Arize Span Routing Skill

Arize Span路由技能

Use this skill to send each traced operation from one Python service to its correct Arize space and project. Each operation must resolve to exactly one

space_id

and

project_name

before its first span starts.

Do not use this skill for ordinary single-project tracing; use

arize-instrumentation

. This skill does not reroute spans after export, backfill historical spans, create Arize spaces/projects, or invent a customer-specific metadata mapping.

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

space_id

和

project_name

。

请勿将此技能用于普通的单项目追踪；请使用

arize-instrumentation

。此技能不支持在导出后重新路由Span、回填历史Span、创建Arize空间/项目，也不会生成客户特定的元数据映射。

Safety rules

安全规则

Never guess a destination or silently use another tenant's destination.
Never embed API keys in code or ask users to paste keys into chat. Read
```
ARIZE_API_KEY
```
from the environment.
Preserve existing non-Arize exporters and processors. Remove or replace a fixed-destination Arize export path so routed spans are not also copied to that destination.
Missing, invalid, or unavailable routing metadata must leave the business operation running but its spans unexported to Arize. Run that operation under a fresh OpenTelemetry context so stale routing values cannot leak across tenants. Log a warning without including secrets or sensitive metadata values.
Use one API key that is authorized for every destination space. Stop and report a credential blocker if that is not true.

绝不能猜测目标地址，也不能静默使用其他租户的目标地址。
绝不能在代码中嵌入API密钥，也不要要求用户在聊天中粘贴密钥。请从环境变量中读取
```
ARIZE_API_KEY
```
。
保留现有的非Arize导出器和处理器。移除或替换固定目标的Arize导出路径，以避免路由后的Span同时被复制到该目标地址。
如果路由元数据缺失、无效或不可用，业务操作仍需正常运行，但对应的Span不会导出到Arize。请在全新的OpenTelemetry上下文下运行该操作，以防止过期的路由值在租户之间泄露。记录警告信息，但不要包含密钥或敏感元数据值。
使用一个有权访问所有目标空间的API密钥。如果无法满足此要求，请立即停止并报告凭证问题。

Phase 1: Inspect and define the contract

阶段1：检查并定义契约

Read only until the routing contract is clear.

Identify the exact Python service and entrypoint to change.
Find current tracing initialization, provider/exporters, instrumentors, and client creation order.
Find the request or agent-execution boundary that owns destination metadata.
Identify the stable metadata field(s) and existing source of truth that resolve to:
- Arize
```
space_id
```
- Arize
```
project_name
```
Check async tasks, thread pools, queues, or background workers that may outlive the request context.
Find the app's test command and existing test style.

Inspect only the target app's configuration. Do not search unrelated repositories, sibling services, shell startup files, or arbitrary

.env

files for credentials.

If service scope, metadata fields, mapping source, or destination behavior is ambiguous, stop and ask the minimum question needed. Do not install packages or edit code first. If the user requested implementation and all four are clear, summarize the contract briefly and continue.

仅需阅读到路由契约明确为止。

确定需要修改的具体Python服务和入口点。
找到当前的追踪初始化、提供者/导出器、工具以及客户端创建顺序。
找到拥有目标元数据的请求或Agent执行边界。
识别可解析为以下内容的稳定元数据字段和现有可信数据源：
- Arize
```
space_id
```
- Arize
```
project_name
```
检查可能超出请求上下文生命周期的异步任务、线程池、队列或后台工作进程。
找到应用的测试命令和现有测试风格。

仅检查目标应用的配置。不要在无关仓库、兄弟服务、Shell启动文件或任意

.env

文件中搜索凭证。

如果服务范围、元数据字段、映射源或目标行为不明确，请停止操作并提出必要的最少问题。不要先安装包或编辑代码。如果用户要求实现且以上四点均明确，请简要总结契约后继续。

Phase 2: Implement

阶段2：实现

1. Ensure routing support exists

1. 确保路由支持已存在

Use the project's package manager to require

arize-otel>=0.11.0

. Do not change unrelated dependencies.

使用项目的包管理器要求

arize-otel>=0.11.0

。不要修改无关依赖。

2. Initialize routing once

2. 初始化路由一次

For an app without an existing OpenTelemetry provider, initialize routing before instrumentors and LLM clients:

python

import os

from arize.otel import register_with_routing

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

If the app already owns a provider with non-Arize telemetry, keep it and add the routing processor:

python

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,
    )
)

Reuse the app's configured endpoint and transport when present. Never call

register_with_routing

after another global provider has already been installed. If the provider also has a fixed Arize processor/exporter, remove that fixed path in its initialization before adding routing; OpenTelemetry processors cannot be safely removed after startup.

对于没有现有OpenTelemetry提供者的应用，请在工具和LLM客户端之前初始化路由：

python

import os

from arize.otel import register_with_routing

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

如果应用已拥有包含非Arize遥测数据的提供者，请保留该提供者并添加路由处理器：

python

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,
    )
)

如果应用已配置了端点和传输方式，请复用这些配置。绝不要在已安装其他全局提供者后调用

register_with_routing

。如果该提供者还包含固定的Arize处理器/导出器，请在添加路由前移除该固定路径；OpenTelemetry处理器在启动后无法安全移除。

3. Resolve one routing target

3. 解析一个路由目标

Adapt the app's existing metadata model; do not introduce a framework for one lookup. The resolver must return both non-empty values or no target. Keep mapping data in its existing source of truth rather than duplicating it in tracing code.

python

from dataclasses import dataclass


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

Use this type only when the codebase lacks an equivalent. Validate the result before any traced work begins.

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

python

from dataclasses import dataclass


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

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

4. Set context around the complete operation

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

Enter routing context at the highest boundary that has the metadata and encloses every child span:

Replace

RoutingLookupError

below with the resolver's specific existing lookup/configuration exception.

python

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)

Catch only the resolver's expected lookup/configuration exceptions; do not hide unrelated application failures. A fresh context on the no-target path intentionally prevents inherited routing values from reaching Arize. It may start a new trace for other exporters; tenant isolation takes priority. If preserving the distributed parent is mandatory, report the missing public routing-clear API as an SDK follow-up rather than using private context keys.

All auto-instrumented and manual child spans created inside the routing context inherit

arize.space_id

and

arize.project.name

. Do not set routing after spans have started.

For background work, propagate the OpenTelemetry context explicitly or resolve and enter a new routing context in the worker. Never rely on request-local context after a queue or thread boundary.

See

references/REFERENCE.md

for agent experiment endpoints, existing-provider details, concurrency rules, testing, verification, and troubleshooting.

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

将下面的

RoutingLookupError

替换为解析器特定的现有查询/配置异常。

python

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路由查询失败；Span将不会被导出")
        return run_without_arize_routing(request)

    if target is None or not target.space_id or not target.project_name:
        logger.warning("无Arize路由目标；Span将不会被导出")
        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。它可能会为其他导出器启动新的追踪；租户隔离优先。如果必须保留分布式父级，请报告缺失的公共路由清除API作为SDK后续任务，不要使用私有上下文键。

在路由上下文内创建的所有自动工具化和手动子Span都会继承

arize.space_id

和

arize.project.name

。不要在Span开始后设置路由。

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

有关Agent实验端点、现有提供者详细信息、并发规则、测试、验证和故障排除，请参阅

references/REFERENCE.md

。

Verification

验证

Run focused unit tests for the resolver and execution boundary.
Prove two different metadata values produce two different space/project pairs.
Prove child spans inherit the selected pair.
Prove concurrent operations cannot leak routing context.
Prove unknown metadata and resolver failures clear inherited routing, export no spans to any fallback destination, and leave business logic running.
Prove pre-existing non-Arize exporters/processors remain attached and no fixed Arize path remains.
Trigger one uniquely named trace per target in non-production spaces.
Use
```
arize-trace
```
with the same credential context to confirm each trace exists only in its intended destination.

For short-lived scripts, call

force_flush()

and

shutdown()

before exit. Finish as confirmed, confirmed with warnings, or a precise blocker; never report completion from unit tests alone when live verification was requested.

为解析器和执行边界运行聚焦单元测试。
证明两个不同的元数据值会生成两个不同的空间/项目对。
证明子Span会继承所选的空间/项目对。
证明并发操作不会泄露路由上下文。
证明未知元数据和解析器故障会清除继承的路由，不会将Span导出到任何 fallback 目标，且业务逻辑仍能正常运行。
证明预先存在的非Arize导出器/处理器仍保持连接，且不存在固定的Arize路径。
在非生产空间中为每个目标触发一个唯一命名的追踪。
使用相同凭证上下文的
```
arize-trace
```
确认每个追踪仅存在于其预期的目标地址中。

对于短生命周期脚本，请在退出前调用

force_flush()

和

shutdown()

。最终状态标记为已确认、**已确认（含警告）**或明确的阻塞问题；当要求进行实时验证时，绝不要仅通过单元测试就报告完成。

Guardrails and limits

防护措施与限制

Both routing values are required. Spans missing either value are skipped.
```
ArizeRoutingSpanProcessor
```
creates and caches one processor per unique space. Flag unbounded or high-cardinality space IDs before implementation.
Routing selects spaces and projects only; other customer metadata still belongs in normal OpenInference attributes.
If dogfooding exposes a missing
```
arize-otel
```
capability, stop and propose a separate SDK change instead of adding a compatibility hack.

两个路由值都是必需的。缺少任一值的Span会被跳过。
```
ArizeRoutingSpanProcessor
```
会为每个唯一空间创建并缓存一个处理器。在实现前标记无限制或高基数的空间ID。
路由仅选择空间和项目；其他客户元数据仍应放在常规的OpenInference属性中。
如果内部测试暴露了
```
arize-otel
```
的功能缺失，请停止操作并提出单独的SDK变更建议，不要添加兼容性 hack。

arize-span-routing

Original

Translation

Arize Span Routing Skill

Arize Span路由技能

Safety rules

安全规则

Phase 1: Inspect and define the contract

阶段1：检查并定义契约

Phase 2: Implement

阶段2：实现

1. Ensure routing support exists

1. 确保路由支持已存在

2. Initialize routing once

2. 初始化路由一次

3. Resolve one routing target

3. 解析一个路由目标

4. Set context around the complete operation

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

Verification

验证

Guardrails and limits

防护措施与限制

Related skills

相关技能