arize-instrumentation

Arize Instrumentation Skill

アプリに初めて Arize AX トレーシングを追加します。スタックを検出 → 一致するインテグレーションのドキュメントを1つ取得 → 自動計装を接続 → トレースが届くことを検証します。

ローカルで振り分けます。 検出したスタックを references/integration-routing.md に基づいて単一のドキュメントページに対応付け、そのページだけを取得します。アプリがエージェントフレームワークを使用している場合は、ラップしているプロバイダー SDK ではなく、フレームワークに基づいて振り分けます。フレームワークを使うアプリ内に単独の openai／anthropic インポートがあっても、対象となるインテグレーションではありません。プロバイダー SDK をフレームワークなしで直接呼び出すアプリの場合に限り、プロバイダーのページに振り分けます。スタックが一覧にない場合は、ルーターに従って llms.txt からインテグレーションページを検索します。一致するページがなければ、手動計装を使用します。PROMPT.md の統合版をまとめて読み込むことは、決してしないでください。

ルール： 変更を加える前に調査します。トレーシングは追加的なものとし、ビジネスロジックは決して変更しません。既存のスタイルに従います。コードにシークレットを含めず、API キーやトークンなどのシークレットをチャットに貼り付けるようユーザーに求めることは決してありません。ARIZE_API_KEY／ARIZE_SPACE_ID 環境変数のみを参照し、ユーザー自身の .env／シェルで設定してもらいます。アプリの Arize リージョン／エクスポートエンドポイントを保持するか、ユーザーに確認し、米国リージョンだと決めつけないでください。references/regions-and-endpoints.md を参照してください。永続的なローカル状態（ax プロファイル、.zshrc、環境変数）を変更する前に確認します。references/ax-profiles.md を参照してください。

Phase 1: 分析（読み取り専用 — コード／ファイルの変更なし）

マニフェストとインポートから、言語、パッケージマネージャー、LLM プロバイダー、フレームワーク、既存のトレーシング（TracerProvider、register()、ARIZE_*／OTEL_*、Datadog／Honeycomb）、既存の Arize エンドポイント／リージョン設定（ARIZE_COLLECTOR_ENDPOINT、コード内の Arize エンドポイントオプション、または Arize を対象としていることが確認済みの OTEL_EXPORTER_OTLP_ENDPOINT）、およびアプリがツール／エージェントループを実行しているかどうかを検出します（手動の CHAIN／TOOL スパンを追加するのは、一致したフレームワークのインストルメンターがそれらをカバーしていない場合のみです。Phase 2 で判断します）。まず対象範囲を確認します。 モノレポ、複数のサービス、または複数のフレームワークがある場合は、何かに手を加える前に「どれを対象にしますか？」と確認します。ユーザーに代わって選択しないでください。

スタック、提案するインテグレーション、既存のトレーシング、対象範囲について、短い要約を出力します。対象が明確で、ユーザーが今すぐ計装するよう依頼している場合は続行します。不明確な場合、または分析のみを依頼された場合は、停止して確認します。

Phase 2: 実装（対象の確認後）

1. 一致したインテグレーションのドキュメントを取得し、 インストールと接続の手順に忠実に従います。
2. コードを書く前に、検出したパッケージマネージャーでインストールします。パッケージの正確な名前は、一致したドキュメントに記載されたものを使用します。Python の基本構成は、arize-otel（現在の PyPI リリース）と openinference-instrumentation-{name}（パッケージ名はハイフン、インポート名はアンダースコア）です。TS／JS は、@opentelemetry/sdk-trace-node と、一致した @arizeai/openinference-*（または Mastra の @mastra/arize などのファーストパーティーエクスポーター）です。Go にはインテグレーションのドキュメントがありません。インストール、接続、フラッシュ、手動スパンについては references/go.md を参照してください。
3. 認証情報とリージョン — アプリには API キー、Space、エクスポーターのエンドポイント／リージョンが必要です。対象アプリ自身の設定のみを調査します。兄弟リポジトリやシェルファイルを検索したり、シークレットを表示したり、貼り付けられたキーを受け取ったりしてはいけません。references/credentials-and-config.md、references/regions-and-endpoints.md、references/ax-profiles.md を参照してください。
4. 初期化処理を単一のモジュールに集約し、LLM クライアントを作成する前に実行します。既存の OTel がある場合は、Arize を追加のエクスポーターとして追加し、既存のものと置き換えないでください。 自動か手動か： 自動インストゥルメンターを優先してください。すでに自動インストゥルメンターがカバーしているスパンを手作業で作成しないでください（スパンが重複し、セマンティック規約からずれてしまいます）。自動インストゥルメンターでは検出できないロジック、またはスタックに自動インストゥルメンターがまったくない場合にのみ、手動スパンを追加してください。アプリがプロバイダー SDK を直接呼び出す場合、OpenAI と Anthropic の SDK インストゥルメンターは LLM 呼び出し（モデルによるツール呼び出しリクエスト（名前と引数）を含む）をキャプチャしますが、ツールの実行、その戻り値、エージェント／チェーンの境界はキャプチャしません。独自のツール呼び出しループを持つ raw-SDK アプリでは、実行ごとに TOOL スパン（結果をキャプチャするため）と、ターンをグループ化する CHAIN（または AGENT）スパンを追加する必要があります。そうしないと、これらは記録されません。関数がある場合は、@tracer.tool／@tracer.chain デコレーターを使ってください（種別、メタデータ、ステータスが自動的に設定されます）。デコレーターを適用できる関数がない場合に限り、スパンを手作業で作成してください。フレームワークによっては、独自のクライアントレイヤーを介してモデルを呼び出し、独自の OpenTelemetry スパンを出力するものもあります。その場合、プロバイダーのインストゥルメンターは何もキャプチャしないため、プロバイダー SDK ではなく、フレームワークのインテグレーションページを参考にしてインストゥルメントしてください。フレームワークのインストゥルメンター（LangChain／LangGraph／OpenAI Agents SDK）は通常、ツールとチェーンをカバーします。手動スパンを省略する前に、該当するドキュメントで確認してください。セットアップには 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 を使ってください。既存のプロバイダーと統合する場合に限り、raw OTel を使ってください。
• 順序： トレーサーを登録 → インストゥルメンターを設定 → クライアントを作成。
• リージョン： US と決めつけないでください。ARIZE_COLLECTOR_ENDPOINT、または Arize を参照することが確認済みのエンドポイントをそのまま使ってください。一般的な OTEL_EXPORTER_OTLP_ENDPOINT は既存の Arize 以外のエクスポーターに属する場合があります。そのエクスポーターは別途維持し、確認せずに流用するのではなく、Arize SaaS のリージョンを確認してください。references/regions-and-endpoints.mdを参照してください。
• 手作業でスパンを作成するより、@tracer.* デコレーターを優先してください。種別、input.value／output.value、TOOL のメタデータ一式、終了ステータスが自動設定されるため、手作業で作成したスパンで発生しがちな UNSET や不完全なスパンを出力しません。デコレーターは関数の定義に付けるため、動的ディスパッチを理由に手作業でスパンを作成する必要はありません。references/manual-spans.mdを参照してください。
• 手作業で作成するスパンでは、終了前に必ず次の値を設定してください： openinference.span.kind、input.value／output.value、および TOOL スパンの場合は tool.name／tool.description／tool.parameters のすべて。特に設定漏れが多い項目： start_as_current_span は例外が発生するとステータスを ERROR に記録しますが、OK は設定しません。そのため、成功時の処理に span.set_status(Status(StatusCode.OK)) を追加してください。設定しないと、スパンが UNSET のままエクスポートされ、スコアリングに失敗します。references/manual-spans.mdを参照してください。
• 終了前にフラッシュしてください（CLI／スクリプト／ノートブック）。そうしないと、非同期エクスポートでデータが失われます。Python：force_flush()＋shutdown()、TS：shutdown()、Go：defer tp.Shutdown(ctx)（スパンの途中で log.Fatalf／os.Exit を呼び出さないでください）。references/session-tracking.mdを参照してください。
• セッション： 明らかな複数ターンのやり取り（例：複数ターンのチャットボット）やユーザーからの要望がある場合は、session.id を追加して、各ターンがひとつの会話にまとまるようにしてください。references/session-tracking.mdを参照してください。
• アプリのプロジェクト／スペース／ID／エンドポイントを黙って上書きしないでください。不一致があれば明示してください。

検証

完了とするのは、アプリのビルドと型チェックが成功し、トレーシングを有効にして起動し、実際のリクエストを1件以上送信し、Arize でトレースを確認できた場合、またはアプリと Arize 間の具体的な阻害要因を提示した場合のみです。LLM 呼び出しを実行し、arize-trace スキルを使ってスパン（kind、input.value／output.value、親子関係。ツールを実行する場合は CHAIN と TOOL）を確認します。トレースがない場合は、ARIZE_SPACE_ID／ARIZE_API_KEY、初期化の順序、設定済みのコレクターエンドポイント／リージョン、エクスポーターのログ（GRPC_VERBOSITY=debug）を確認してください。よくある原因は、リージョンエンドポイントの誤り、プロジェクト名の不足（500）、短時間で終了するプロセスの未フラッシュ、またはエクスポートと検証での認証情報コンテキストの不一致です（報告し、設定を書き換えないでください — references/credentials-and-config.md）。トレースの決定的な検索手順、阻害要因の分類、到着後のスモークテストについては、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。