クエリログの出力と解析

1. クエリログを取る目的

• 性能の可視化: レイテンシやトークン消費量を定量化し、ボトルネックを特定する

• 品質評価: 生成テキスト、取得ノード、プロンプト／コンテキストの対応関係を後で再検証できる

• 本番デバッグ: 例外・失敗パターンを再現しやすくする

---

2. ログ出力のレイヤー

2-1. 最低限の DEBUG ログ

python
import logging, sys
logging.basicConfig(stream=sys.stdout, level=logging.DEBUG)
logging.getLogger().addHandler(logging.StreamHandler(stream=sys.stdout))

これだけで各種コンポーネントの実行順序と簡易メッセージを取得できる docs.llamaindex.ai

2-2. CallbackManager とハンドラ群

python
from llama_index.core.callbacks import CallbackManager, LlamaDebugHandler
handler = LlamaDebugHandler(print_trace_on_end=True)
cb_manager = CallbackManager([handler])
index = VectorStoreIndex.from_documents(docs, callback_manager=cb_manager)
response = index.as_query_engine().query("質問文")

実行後に 階層化されたイベントツリー と各区間の秒数が標準出力に現れる docs.llamaindex.ai

イベント種別一覧は公式ノートブックで確認できる docs.llamaindex.ai

トークン使用量の計測

python
from llama_index.core.callbacks import TokenCountingHandler
token_counter = TokenCountingHandler(tokenizer=my_encode_fn)
CallbackManager([token_counter])
print(token_counter.total_prompt_token_count)

埋め込み・プロンプト・補完それぞれの累積トークン数を取得でき、reset_counts() でリセット可能 docs.llamaindex.ai

カスタムハンドラ

BaseCallbackHandler を継承し、start_trace, end_trace などをオーバーライドすれば
JSON 形式で S3 に書き出す、SQL に流す──など自由に実装できる。

---

3. ログの永続化とフォーマット例

python
import json, datetime
class JsonFileHandler(BaseCallbackHandler):
    def end_trace(self, event, **kwargs):
        fname = f"logs/{event.event_id}.json"
        with open(fname, "w") as f:
            json.dump(event.dict(), f, default=str)

• 時系列 DB（InfluxDB, TimescaleDB など）にメトリクスだけ投入

• オブジェクトストレージに “生成テキスト＋取得ノード＋LLM 入出力” を残して再評価材料に

---

4. ログ解析の実務フロー

1. 指標集計

   • EventStats 経由で平均／最大レイテンシを取得し、異常スパイクを検知

2. 再現テスト

   • ログ内の prompt, context, retrieved_nodes を使い “同一条件で再推論”

3. 品質評価

   • LlamaIndex の Evaluator モジュールや外部評価サービスで BLEU, faithfulness などを算出

4. コスト分析

   • TokenCountingHandler の値 × 料金表 → 月次コストを見積もり、max-token や top-k を調整

---

5. 外部オブザーバビリティ連携

各ツールは CallbackHandler 方式 か OTel インストルメンテーション 方式を採用しているため、
同じコードに複数ハンドラを併用しても衝突しにくい。

---

6. ベストプラクティス

1. 本番ではサンプリング＋PII マスキング

   • 全量ログは高コストかつ個人情報リスクがある

2. CI で“再現テスト＋品質スコア”を自動実行

   • 回帰バグを早期に検知

3. バージョン固定

   • llama-index>=0.11 系と arize-phoenix-otel>=0.5 など、互換性を明示

4. コールバックの粒度を要件に合わせる

   • 開発中: LlamaDebugHandler(print_trace_on_end=True)

   • 本番: TokenCountingHandler と OTel だけ有効にしてオーバーヘッド最小化

---

まとめ — 導入ステップ早見表

1. DEBUG ログをオン

2. CallbackManager に

   • LlamaDebugHandler → 時間・階層トレース

   • TokenCountingHandler → コスト指標

3. 必要に応じて 自作ハンドラ で JSON へ永続化

4. 本番では Phoenix／Graphsignal などを 1 行で装着

5. ログから 性能・品質・コスト を継続的にフィードバックし、Prompt／Retriever 設定を最適化

これで LlamaIndex アプリケーションのクエリ挙動を“見える化”し、品質と運用コストを両立させたデバッグ／評価基盤を構築できます。