Logs

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

What（何についてか）

LiveKit Cloudが提供するAgent向けログ機能。Runtime logs、Build logs、Session logsの3種類があり、それぞれ確認方法と用途が異なる。

Why（なぜ必要か）

デプロイ後のAgentの動作確認、ビルド失敗のデバッグ、セッション単位の問題追跡にログが不可欠。ログの種類を理解して適切な確認方法を選ぶことで、トラブルシューティングの効率が大きく変わる。

How（どう動くか）

3種類のログ

LiveKit Cloudは以下の3種類のログを提供する。

Runtime logs はAgentプロセスの生の出力（stdout/stderr）。起動、シャットダウン、クラッシュ、ディスパッチエラー等を含む。

Build logs はコンテナビルド時の出力。Dockerfile実行や依存関係のインストールログ。最新デプロイ版のビルドログは無期限保存される。

Session logs はセッション単位のログ。Agent Observabilityの一部として、トランスクリプト、トレース、音声録音と一緒にDashboardで閲覧可能。

重要な区別として、Session logsは「正常に開始できたセッション」のみを対象とする。サーバーレベルのイベント（クラッシュ、起動失敗、ディスパッチエラー）はSession logsに含まれない。それらはRuntime logsまたはLog drainで確認する必要がある。

Runtime logs の確認方法

CLIでリアルタイム追跡：

lk agent logs

最新のAgentサーバーインスタンスのログをストリーミングする。最近のログスナップショットも含まれる。ただし 最新の1インスタンスのみ が対象。スケールアウト環境で全インスタンスのログを取りたい場合はLog drainが必要。

外部サービスへの転送も可能（Datadog、CloudWatch、Sentry、New Relic）。ただし転送されるのはstdout/stderrのみ。traces、build logs、session dataは含まれない。

Log levels

デフォルトは INFO。DockerfileのCMDで変更可能：

CMD ["python", "agent.py", "start", "--log-level=DEBUG"]

利用可能なレベルは4段階：

• DEBUG — デバッグ用の詳細情報
• INFO — デフォルト。一般的な情報
• WARNING — 警告メッセージ
• ERROR — エラーメッセージ

Python標準のloggingと同じ体系。--log-level フラグで指定する。

Build logs の確認方法

lk agent logs --log-type=build

最新デプロイ版のビルドログをstdoutに出力。ライブテールではなく1回の出力。古いバージョンのビルドログはCloud Dashboardで確認可能。

graph TD
    A["Agent Logs"] --> B["Runtime logs"]
    A --> C["Build logs"]
    A --> D["Session logs"]
    B --> E["lk agent logs"]
    B --> F["Log drain"]
    C --> G["lk agent logs --log-type=build"]
    C --> H["Cloud Dashboard"]
    D --> I["Agent Observability Dashboard"]

Key Concepts

用語	説明
Runtime logs	Agentプロセスのstdout/stderr。起動・クラッシュ等
Build logs	コンテナビルド時の出力。最新版は無期限保存
Session logs	セッション単位のログ。Observabilityの一部
lk agent logs	Runtime logsのリアルタイムストリーミング（最新インスタンスのみ）
--log-type=build	Build logsの確認
Log drain	Runtime logsを外部監視サービスに転送
--log-level	DEBUG/INFO/WARNING/ERROR の4段階

一言まとめ

LiveKit Cloudのログは3種類。Runtime logs（lk agent logs）は最新インスタンスのみで全体を見るならLog drainが必要。Build logsは --log-type=build で確認。Session logsはAgent Observability Dashboardでトランスクリプト・トレース・録音と一緒に閲覧可能。ログレベルはDEBUG/INFO/WARNING/ERRORの4段階。