Data Hooks

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

What（何についてか）

LiveKit Agents SDKに組み込まれたデータ収集API。セッションの文字起こし、メトリクス、使用量データをプログラムから取得し、外部システム（Langfuse、Datadog等）に統合するためのインターフェース。InsightsがCloudダッシュボードでの閲覧用なのに対し、Data Hooksは自分のコードで収集して外部に送るためのもの。

Why（なぜ必要か）

Voice Agentの品質管理において、パイプライン全体のレイテンシ分析とモデル別のコスト追跡が不可欠。Cloudダッシュボードだけでは独自の分析基盤やアラート、長期保存に対応できない。Data Hooksを使えば、Langfuse等の外部オブザーバビリティツールと統合して、本番運用の品質とコストを継続的に監視できる。

How（どう動くか）

データ収集の3つの方法

session.history（会話履歴） フルの会話内容にアクセスできるオブジェクト。セッション終了後に文字起こしとして永続化する用途。「高度なユースケースでありほとんどのアプリでは推奨しない」とドキュメントに明記されている。リアルタイムモデル（STTプラグインなし）では文字起こしが不完全な場合がある（Delayed Transcription問題）。

イベント購読（リアルタイム） SDKが conversation_item_added や user_input_transcribed などのイベントを発火し、これを購読してライブダッシュボードを構築できる。

ctx.make_session_report()（構造化レポート） on_session_end コールバック内で呼び出すと、セッションの全データを1つの SessionReport にまとめる。レポートにはJob/Room/ParticipantのID、タイムスタンプ付き会話履歴、全セッションイベント、音声録音メタデータ、Agent設定が含まれる。llm_node_ttft と tts_node_ttfb はSTT-LLM-TTSパイプラインのみ設定され、Realtimeモデルでは常に空。

セッションレポートのライフサイクル

AgentがRoomに接続しVoice Pipelineが開始される。セッションが終了（参加者の切断等）すると、SDKが on_session_end コールバックを発火する。コールバック内で ctx.make_session_report() を呼ぶと全データが確定済みの状態で取得できる。コールバックがreturnした後、SDKがテレメトリをCloudにフラッシュしてリソースをクリーンアップする。

session_end_timeout（デフォルト5分）がコールバックの最大実行時間で、重い処理をする場合は増やす必要がある。shutdown_process_timeout（デフォルト10秒）はコールバック完了後のジョブプロセス全体のシャットダウン時間。

音声/映像録音

デフォルトのCloud Insights録音（BVC適用後の音声）に加えて、LiveKit Egressを使えばBVCなしの音声や映像を直接外部ストレージ（S3等）に保存できる。Room Composite Recorderをセッション開始時に起動し、OGG等の形式で出力する。

手段	BVC	映像	保存先
デフォルト（Insights）	あり	音声のみ	LiveKit Cloud
Egress	なし	対応	S3等の外部ストレージ

メトリクス収集の4つのスコープ

スコープ	手段	用途
コンポーネントごと	プラグイン単位の metrics_collected イベント	単一STT/LLM/TTS/VAD呼び出しのレイテンシと使用量
ターンごと	ChatMessage.metrics（MetricsReport）	1ターンのレイテンシブレークダウン
セッションごと（リアルタイム）	session_usage_updated イベント	モデル別トークン/時間の累計
セッションごと（最終）	SessionReport	終了時のスナップショット

Conversation Latency（最重要）

Voice Agentの体感品質はレイテンシで決まる。人間の会話の自然な間は200〜500msであり、これを超えるとユーザーにストレスを与える。

e2e_latency はユーザー発話終了からAgent応答開始までのエンドツーエンドレイテンシ。より詳細な内訳が必要な場合は各ステージのメトリクスを合算する。

total_latency = eou.end_of_utterance_delay + llm.ttft + tts.ttfb

graph LR
    A["User stops speaking"] -->|"EOU delay"| B["Turn complete"]
    B -->|"LLM TTFT"| C["First token"]
    C -->|"TTS TTFB"| D["Agent starts speaking"]

各ステージのボトルネック特定には speech_id を使う。同じユーザーターンに対するEOU/LLM/TTSメトリクスを speech_id で紐付けることで、「どのステージが遅かったか」を正確に追跡できる。speech_id がNoneのものはプロアクティブ応答や say() 呼び出しで、ユーザーターンに紐付かない。

Per-Turn Latency

ユーザーメッセージのメトリクス：transcription_delay（文字起こし遅延）、end_of_turn_delay（ターン終了判定遅延）、on_user_turn_completed_delay（コールバック実行時間）。

Assistantメッセージのメトリクス：llm_node_ttft（LLM最初のトークンまで、STT-LLM-TTSのみ）、tts_node_ttfb（TTS最初の音声まで、STT-LLM-TTSのみ）、e2e_latency（エンドツーエンド）。両ロール共通で started_speaking_at / stopped_speaking_at が含まれる。

Session Usage

session_usage_updated イベントでリアルタイムに、または session.usage で随時、モデル別の累計使用量にアクセスできる。model_usage リストの各エントリはプロバイダー/モデルごとに以下の型に分かれる。

LLMModelUsage：provider、model、prompt_tokens、completion_tokens、total_tokens、speech_id。コスト管理に直結する。

TTSModelUsage：provider、model、characters_count、speech_id。文字数ベースの課金モデルに対応。

STTModelUsage：provider、model、audio_duration（秒）、speech_id。音声時間ベースの課金に対応。

InterruptionModelUsage：provider、model、interrupted_speech_count。

Metrics Reference（各コンポーネント）

各プラグインの metrics_collected イベントで取得できるメトリクス。Cloud Insightsのトレースspanと同じデータ。

VAD（VADMetrics）：idle_time、inference_duration_total、inference_count。VAD推論に時間がかかるとターン検出のレイテンシに影響する。

STT（STTMetrics）：audio_duration、duration（ストリーミングでは常に0）、streamed。STTコンポーネント設定時のみ発火し、Realtime APIでは発火しない。

EOU（EOUMetrics）：end_of_utterance_delay、transcription_delay、on_user_turn_completed_delay、speech_id。turn_detectionがVADまたはLiveKit Turn Detectorの場合に利用可能。

LLM（LLMMetrics）：duration、ttft、completion_tokens、prompt_tokens、prompt_cached_tokens、total_tokens、tokens_per_second、speech_id。ttftとtokens_per_secondがレスポンス速度の指標。

Realtime（RealtimeModelMetrics）：duration、session_duration、ttft（音声トークン）、input_tokens、output_tokens、total_tokens、tokens_per_second、input_token_details（audio/text/image/cached）、output_token_details。STT+LLM+TTSが統合されたメトリクス。

TTS（TTSMetrics）：audio_duration、characters_count、duration、ttfb、speech_id、streamed。ttfbがユーザー体感の応答速度に直結。

Interruption（InterruptionMetrics）：total_duration（RTT）、prediction_duration、detection_delay、num_interruptions、num_backchannels、num_requests。Adaptive Interruption Handling有効時のみ発火。

OpenTelemetry Integration（Python限定）

set_tracer_provider() にTracerProviderを渡すことで、LiveKit Cloudと同じspanを任意のOTLP対応バックエンドにエクスポートできる。LangFuseとの連携手順は以下の通り。

1. LangFuseの認証情報（public_key / secret_key / host）を環境変数から取得
2. Basic認証ヘッダーをBase64エンコード
3. OTLPエンドポイントとしてLangFuseの /api/public/otel を設定
4. TracerProviderにBatchSpanProcessor（OTLPSpanExporter）を追加
5. set_tracer_provider() を呼んでSDKのテレメトリをルーティング

Node.js SDKでは未対応。LangFuse以外にもOTLP対応バックエンド（Jaeger、Zipkin、Grafana Tempo等）なら何でも使える。