phoenix-tracing

Phoenix Tracing

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 などを自動計測します
• instrumentation-auto-typescript - サポート対象のフレームワークを自動計測します
• instrumentation-manual-python - デコレーターを使ってカスタムスパンを作成します
• instrumentation-manual-typescript - ラッパーを使ってカスタムスパンを作成します

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

• span-llm - LLM API 呼び出し（モデル、トークン、メッセージ、コスト）
• span-chain - 複数ステップのワークフローとパイプライン
• span-retriever - ドキュメント検索（ドキュメント、スコア）
• span-tool - 関数／API 呼び出し（名前、パラメーター）
• span-agent - 複数ステップの推論を行うエージェント
• span-embedding - ベクトル生成
• span-reranker - ドキュメントの再ランキング
• span-guardrail - 安全性チェック
• span-evaluator - LLM 評価

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
references/attributes-*         # Attribute specifications

# 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 パッケージ