Log Drains
参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ
What（何についてか）
AgentのRuntime logs（stdout/stderr）を外部監視サービスに転送する機能。sidecarプロセスとしてAgentの横で動き、Agentコードには影響しない。
Why（なぜ必要か）
lk agent logs は最新の1インスタンスのみ対象。スケールアウト環境で全レプリカのログを集めるにはLog drainが唯一の手段。クラッシュ、起動失敗、ディスパッチエラー等のサーバーレベルイベントはSession logsに含まれないため、Log drainで Runtime logs を外部に集約する必要がある。
How（どう動くか）
対応サービスと必要なSecret
設定は Secretを登録するだけ で転送が開始される。コード変更不要。
- Datadog —
DATADOG_TOKEN（必須）、DATADOG_REGION（任意、default: us1） - CloudWatch —
AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY（必須）、AWS_REGION（任意、default: us-west-2） - Sentry —
SENTRY_DSN（必須） - New Relic —
NEW_RELIC_LICENSE_KEY（必須）
転送されないもの
Log drainが転送するのはRuntime logs（stdout/stderr）のみ。以下は別手段で確認する。
- Traces → OpenTelemetry統合でAgentコードから直接エクスポート
- Transcripts / Audio / Session data → Agent Observability Dashboard
- Build logs →
lk agent logs --log-type=buildまたはCloud Dashboard
各サービスのログフィールド
全サービスで共通して stream（stdout/stderr）とAgent/Server IDによる識別が可能。
Datadog: host（サーバーID）、source（Agent ID）、service（cloud.livekit.io）、stream
CloudWatch: ロググループ livekit/<agent-id> が自動作成、ログストリーム <agent-server-id>。IAM権限として logs:CreateLogGroup、logs:CreateLogStream、logs:PutLogEvents が必要。
Sentry: logger（Agent ID）、server_name（サーバーID）、environment（“production”固定）
New Relic: hostname（サーバーID）、service_name（Agent ID）、source（cloud.livekit.io）
Troubleshooting
ログが外部サービスに届かない場合の確認事項：
lk agent list-secretsでSecret名が正しく設定されているか確認- CloudWatchは
AWS_REGION、DatadogはDATADOG_REGIONが合っているか - CloudWatchのIAM権限が十分か
- CloudWatchなら
livekit/<agent-id>ロググループを探す - Secret変更後は再デプロイが必要（変更は次回デプロイで反映）
graph LR A["Agent Process"] -->|"stdout/stderr"| B["Sidecar"] B --> C["Datadog"] B --> D["CloudWatch"] B --> E["Sentry"] B --> F["New Relic"]
Key Concepts
| 用語 | 説明 |
|---|---|
| Log drain | Runtime logsを外部監視サービスに転送するsidecarプロセス |
| Sidecar | Agentの横で動く転送プロセス。Agentコードから不可視 |
DATADOG_TOKEN | Datadog転送に必要なクライアントトークン |
SENTRY_DSN | Sentry転送に必要なDSN |
AWS_ACCESS_KEY_ID | CloudWatch転送に必要なAWS access key |
一言まとめ
Log drainはSecret登録だけでRuntime logsをDatadog/CloudWatch/Sentry/New Relicに転送するsidecar機能。スケールアウト環境で全レプリカのログを集める唯一の手段。Traces/Build logs/Session dataは別途対応が必要。