phoenix-tracing

Phoenix トレーシング

Phoenix で OpenInference トレーシングを使用して LLM アプリケーションを計測するための包括的なガイドです。セットアップ、計測、スパンの種類、本番環境へのデプロイを網羅したリファレンスファイルが含まれています。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• Phoenix トレーシングをセットアップするとき（Python または TypeScript）
• LLM 操作用のカスタムスパンを作成するとき
• OpenInference の規約に従って属性を追加するとき
• トレーシングを本番環境にデプロイするとき
• トレースデータをクエリして分析するとき

リファレンスのカテゴリ

優先度	カテゴリ	説明	プレフィックス
1	セットアップ	インストールと設定	setup-*
2	計測	自動および手動トレーシング	instrumentation-*
3	スパンの種類	属性を含む 9 種類のスパン	span-*
4	構成	プロジェクトとセッション	projects-*, sessions-*
5	エンリッチメント	カスタムメタデータ	metadata-*
6	本番環境	バッチ処理、マスキング	production-*
7	フィードバック	アノテーションと評価	annotations-*

クイックリファレンス

1. セットアップ（ここから開始）

• setup-python - arize-phoenix-otel をインストールし、エンドポイントを設定する
• setup-typescript - @arizeai/phoenix-otel をインストールし、エンドポイントを設定する

2. 計測

• instrumentation-auto-python - OpenAI、LangChain などを自動計測する（OTel GenAI のネイティブ計測も対象）
• instrumentation-auto-typescript - 対応フレームワークを自動計測する
• instrumentation-manual-python - デコレーターでカスタムスパンを作成する
• instrumentation-manual-typescript - ラッパーでカスタムスパンを作成する
• instrumentation-atif-python - ATIF エージェントの軌跡をインポートする（Claude Code、OpenHands、Codex など）

3. スパンの種類（属性スキーマの全項目）

• span-llm - LLM API 呼び出し（モデル、トークン、メッセージ、コスト）
• span-chain - 複数ステップのワークフローとパイプライン
• span-retriever - ドキュメント検索（ドキュメント、スコア）
• span-tool - 関数／API 呼び出し（名前、パラメーター）
• span-agent - 複数ステップで推論するエージェント
• span-embedding - ベクトル生成
• span-reranker - ドキュメントの再ランキング
• span-guardrail - 安全性チェック
• span-evaluator - LLM の評価
• span-decision - 意思決定モデルの呼び出し（ルーティング、分類、スコアリング）— 実験的

4. 構成

• projects-python / projects-typescript - アプリケーションごとにトレースをグループ化する
• sessions-python / sessions-typescript - 会話を追跡する

5. エンリッチメント

• metadata-python / metadata-typescript - カスタム属性

6. 本番環境（重要）

• production-python / production-typescript - バッチ処理、個人識別情報（PII）のマスキング

7. フィードバック

• annotations-overview - フィードバックの概念
• annotations-python / annotations-typescript - スパンにフィードバックを追加する

リファレンスファイル

• fundamentals-overview - トレース、スパン、属性の基礎
• fundamentals-required-attributes - スパンの種類ごとの必須フィールド
• fundamentals-universal-attributes - 共通属性（user.id、session.id）
• fundamentals-flattening - JSON のフラット化ルール

一般的なワークフロー

• クイックスタート：setup-{lang} → instrumentation-auto-{lang} → Phoenix を確認
• カスタムスパン：setup-{lang} → instrumentation-manual-{lang} → span-{type}
• セッション追跡：会話をグループ化するパターンについては sessions-{lang} を参照
• 本番環境：バッチ処理、マスキング、デプロイについては production-{lang} を参照

このスキルの使い方

ナビゲーションパターン：

# By category prefix
references/setup-*              # Installation and configuration
references/instrumentation-*    # Auto and manual tracing
references/span-*               # Span type specifications
references/sessions-*           # Session tracking
references/production-*         # Production deployment
references/fundamentals-*       # Core concepts

# By language
references/*-python.md          # Python implementations
references/*-typescript.md      # TypeScript implementations

参照順序：

1. 使用する言語の setup-{lang} から始めます
2. instrumentation-auto-{lang} または instrumentation-manual-{lang} を選択します
3. 必要に応じて、特定の操作に対応する span-{type} ファイルを参照します
4. 属性の仕様については fundamentals-* ファイルを参照します

参考資料

Phoenix ドキュメント：

• Phoenix ドキュメント
• OpenInference 仕様

Python API ドキュメント：

• Python OTEL パッケージ - arize-phoenix-otel API リファレンス
• Python クライアントパッケージ - arize-phoenix-client API リファレンス

TypeScript API ドキュメント：

• TypeScript パッケージ - @arizeai/phoenix-otel、@arizeai/phoenix-client、その他の TypeScript パッケージ