arize-span-routing

Arize スパンルーティングスキル

このスキルを使うと、1 つの Python サービスからトレースされた各操作を、正しい Arize スペースとプロジェクトに送信できます。各操作では、最初のスパンが開始される前に、space_id と project_name がそれぞれちょうど 1 つに解決されている必要があります。

通常の単一プロジェクトのトレースにはこのスキルを使わず、arize-instrumentation を使ってください。このスキルでは、エクスポート後のスパンのルーティング変更、過去のスパンのバックフィル、Arize スペースやプロジェクトの作成、顧客固有のメタデータマッピングの推測は行いません。

安全上のルール

• 送信先を推測したり、別のテナントの送信先を黙って使ったりしないでください。
• API キーをコードに埋め込んだり、ユーザーにチャットでキーを貼り付けるよう求めたりしないでください。環境変数から ARIZE_API_KEY を読み取ってください。
• 既存の Arize 以外のエクスポーターとプロセッサーを維持してください。ルーティングされたスパンもその送信先にコピーされないよう、送信先が固定された Arize のエクスポート経路を削除または置き換えてください。
• ルーティングメタデータがない、無効、または利用できない場合も、ビジネス操作は実行したまま、スパンは Arize にエクスポートしないでください。テナント間で古いルーティング値が漏れないよう、その操作は新しい OpenTelemetry コンテキストで実行してください。秘密情報や機密性の高いメタデータ値を含めずに警告をログに記録してください。
• すべての送信先スペースで認可されている API キーを 1 つ使用してください。そうでない場合は停止し、認証情報の問題として報告してください。

フェーズ 1：契約を確認して定義する

ルーティングの契約が明確になるまでだけ読み進めてください。

1. 変更対象となる Python サービスとエントリーポイントを特定します。
2. 現在のトレース初期化、プロバイダー／エクスポーター、計装器、クライアント作成の順序を確認します。
3. 送信先メタデータを管理するリクエストまたはエージェント実行の境界を特定します。
4. 次の項目に解決する、安定したメタデータフィールドと既存の信頼できる情報源を特定します。
   • Arize の space_id
   • Arize の project_name
5. リクエストコンテキスト終了後も存続する可能性のある非同期タスク、スレッドプール、キュー、バックグラウンドワーカーを確認します。
6. アプリのテストコマンドと既存のテストスタイルを確認します。

対象アプリの設定だけを調べてください。無関係なリポジトリ、兄弟サービス、シェルの起動ファイル、任意の .env ファイルを検索して認証情報を探さないでください。

サービスの範囲、メタデータフィールド、マッピング元、または送信先の動作が曖昧な場合は、停止して必要最小限の質問をしてください。先にパッケージをインストールしたりコードを編集したりしないでください。ユーザーが実装を依頼しており、4 項目すべてが明確な場合は、契約を簡潔にまとめてから続行してください。

フェーズ 2：実装する

1. ルーティングサポートがあることを確認する

プロジェクトのパッケージマネージャーを使って、arize-otel>=0.11.0 を依存関係として追加してください。無関係な依存関係は変更しないでください。

2. ルーティングを一度だけ初期化する

OpenTelemetry プロバイダーがまだないアプリでは、計装器と LLM クライアントより先にルーティングを初期化してください。

import os

from arize.otel import register_with_routing

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

Arize 以外のテレメトリーを持つプロバイダーをアプリがすでに管理している場合は、それを維持してルーティングプロセッサーを追加してください。

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. ルーティング先を 1 つに解決する

アプリ既存のメタデータモデルに合わせてください。1 回の検索のためにフレームワークを導入しないでください。リゾルバーは、空でない値を両方返すか、送信先なしを返す必要があります。マッピングデータをトレースコードに複製せず、既存の信頼できる情報源に保持してください。

from dataclasses import dataclass


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

同等のものがコードベースにない場合にのみ、この型を使用してください。トレース対象の処理を開始する前に、結果を検証してください。

4. 操作全体を囲むコンテキストを設定する

メタデータを持ち、すべての子スパンを囲む最も外側の境界で、ルーティングコンテキストに入ります。

以下の 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 に渡らないようにするためです。ほかのエクスポーターでは新しいトレースが始まることがありますが、テナントの分離を優先します。分散トレースの親を維持する必要がある場合は、プライベートなコンテキストキーを使うのではなく、ルーティングをクリアする公開 API がないことを SDK の対応事項として報告してください。

ルーティングコンテキスト内で作成された、自動計装および手動のすべての子スパンは、arize.space_id と arize.project.name を継承します。スパンの開始後にルーティングを設定しないでください。

バックグラウンド処理では、OpenTelemetry コンテキストを明示的に伝播するか、ワーカー内でルーティングを解決して新しいルーティングコンテキストに入ってください。キューやスレッドの境界を越えた後も、リクエストローカルのコンテキストが使えるとは想定しないでください。

エージェント実験のエンドポイント、既存プロバイダーの詳細、並行処理の規則、テスト、検証、トラブルシューティングについては、references/REFERENCE.md を参照してください。

検証

1. リゾルバーと実行境界に対する重点的なユニットテストを実行します。
2. 2つの異なるメタデータ値によって、異なるスペース／プロジェクトの組み合わせが選択されることを確認します。
3. 子スパンが選択された組み合わせを継承することを確認します。
4. 並行処理によってルーティングコンテキストが漏えいしないことを確認します。
5. 未知のメタデータとリゾルバーの失敗時に、継承されたルーティングがクリアされ、フォールバック先を含むどの宛先にもスパンがエクスポートされず、ビジネスロジックの実行が継続することを確認します。
6. 既存の Arize 以外のエクスポーター／プロセッサーが引き続き接続され、固定の Arize 経路が残っていないことを確認します。
7. 本番環境以外のスペースごとに、一意の名前を付けたトレースを1つ生成します。
8. 同じ認証情報コンテキストを使って arize-trace を実行し、各トレースが意図した宛先にのみ存在することを確認します。

短時間で終了するスクリプトでは、終了前に force_flush() と shutdown() を呼び出してください。確認済み、警告付きで確認済み、または具体的なブロッカーのいずれかとして完了状況を報告してください。ライブ検証が求められている場合、ユニットテストだけで完了を報告してはいけません。

ガードレールと制限事項

• 2つのルーティング値はどちらも必須です。いずれかの値を欠くスパンはスキップされます。
• ArizeRoutingSpanProcessor は、一意のスペースごとに1つのプロセッサーを作成してキャッシュします。実装前に、スペース ID の種類が無制限または多すぎないか確認してください。
• ルーティングで選択するのはスペースとプロジェクトのみです。その他の顧客メタデータは、通常の OpenInference 属性に設定してください。
• dogfooding によって arize-otel の機能不足が判明した場合は、停止して別途 SDK の変更を提案してください。互換性ハックを追加してはいけません。

関連スキル

• arize-instrumentation：初回のトレース設定、または単一の宛先へのトレース
• arize-trace：エクスポート後の検証とデバッグ
• arize-admin：認可済みのスペースと API キーの確認または管理