Overview
Log drains let you forward runtime logs to your existing monitoring stack. Use a log drain to collect all of your agent's runtime logs — including server-level events like crashes, startup errors, and dispatch failures. This gives you centralized search, alerting, long-term retention, and visibility across all replicas. Log drains are available for agents deployed to LiveKit Cloud.
Log drains forward runtime logs only — the raw stdout and stderr output from your agent process. They don't include traces, build logs, transcripts, or audio recordings. For those, use the following:
- Traces: Export directly from your agent code using the OpenTelemetry integration.
- Transcripts, audio, and session data: Available through Agent Observability in the LiveKit Cloud dashboard.
- Build logs: Available in the LiveKit CLI and the Cloud dashboard.
Log forwarding runs in a sidecar process alongside your agent — it's invisible to your agent code. The lk agent logs CLI command only tails logs from a single agent server instance. If your agent runs at scale across multiple replicas, a log drain is the only way to see logs from all instances.
Supported destinations
Runtime logs can be forwarded to the following external monitoring services. The table lists the required configuration for each destination:
| Destination | Required secrets | Optional secrets |
|---|---|---|
| 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 |
Datadog integration
Automatically forward all runtime logs to your Datadog account. Add a Datadog client token as a secret to enable log forwarding. If your account is in a region other than us1, you can also set the region.
Use the following command to set your Datadog secret:
lk agent update-secrets --secrets "DATADOG_TOKEN=your-client-token" --secrets "DATADOG_REGION=us1"
DATADOG_TOKENstringYour Datadog client token.
DATADOG_REGIONstringDefault: us1Your Datadog region. Supported regions are us1, us3, us5, us1-fed, eu, and ap1.
Log fields
The following log fields are set in Datadog for all log lines sent from LiveKit Cloud:
| Field | Value | Description |
|---|---|---|
| host | <agent-server-id> | A unique identifier for the specific agent server instance emitting the log. |
| source | <agent-id> | The ID of the agent, as in livekit.toml and the dashboard. |
| service | "cloud.livekit.io" | |
| stream | stdout or stderr | Indicates whether the log originated from stdout or stderr. |
CloudWatch integration
Automatically forward all runtime logs to your CloudWatch account. Add your AWS access key ID and secret access key as secrets to enable log forwarding. The AWS region defaults to us-west-2 — set the AWS_REGION secret to use a different region.
Use the following command to set your CloudWatch secrets:
lk agent update-secrets --secrets "AWS_ACCESS_KEY_ID=your-access-key-id" --secrets "AWS_SECRET_ACCESS_KEY=your-secret-access-key" --secrets "AWS_REGION=us-west-2"
AWS_ACCESS_KEY_IDstringYour AWS access key ID.
AWS_SECRET_ACCESS_KEYstringYour AWS secret access key.
AWS_REGIONstringDefault: us-west-2Your AWS region. See the AWS regions page for a list of all supported regions.
Log fields
The following log fields are set in CloudWatch for all log lines sent from LiveKit Cloud:
| Field | Value | Description |
|---|---|---|
| logGroupName | livekit/<agent-id> | The CloudWatch log group, named with your agent ID. |
| logStreamName | <agent-server-id> | A unique identifier for the specific agent server instance emitting the log. |
| message | Log line content | The raw log output from your agent process. |
| stream | stdout or stderr | Indicates whether the log originated from stdout or stderr. |
Sentry integration
Automatically forward all runtime logs to your Sentry account. Add your Sentry DSN as a secret to enable log forwarding.
Use the following command to set your Sentry secret:
lk agent update-secrets --secrets "SENTRY_DSN=your-sentry-dsn"
SENTRY_DSNstringYour Sentry DSN.
Log fields
The following log fields are set in Sentry for all log lines sent from LiveKit Cloud:
| Field | Value | Description |
|---|---|---|
| logger | <agent-id> | The ID of the agent, as in livekit.toml and the dashboard. |
| server_name | <agent-server-id> | A unique identifier for the specific agent server instance emitting the log. |
| environment | "production" | The environment tag for the log entry. |
| stream | stdout or stderr | Indicates whether the log originated from stdout or stderr. |
New Relic integration
Automatically forward all runtime logs to your New Relic account. Add your New Relic license key as a secret to enable log forwarding.
Use the following command to set your New Relic secret:
lk agent update-secrets --secrets "NEW_RELIC_LICENSE_KEY=your-license-key"
NEW_RELIC_LICENSE_KEYstringYour New Relic license key.
Log fields
The following log fields are set in New Relic for all log lines sent from LiveKit Cloud:
| Field | Value | Description |
|---|---|---|
| hostname | <agent-server-id> | A unique identifier for the specific agent server instance emitting the log. |
| service_name | <agent-id> | The ID of the agent, as in livekit.toml and the dashboard. |
| source | "cloud.livekit.io" | Service identifier. |
| stream | stdout or stderr | Indicates whether the log originated from stdout or stderr. |
Troubleshooting
Log forwarding runs in a sidecar process alongside your agent — it's invisible to your agent code. You won't see any log-drain-related configuration or status messages in your agent's own stdout or stderr. If logs aren't appearing in your external service, check the following:
- Verify your secrets are set correctly. Use
lk agent list-secretsto confirm the expected secret names are present. Secret values aren't displayed, so double-check that you set the correct credentials. - Check the region. For CloudWatch, confirm the
AWS_REGIONsecret matches the region you're viewing in the AWS console (defaults tous-west-2). For Datadog, confirmDATADOG_REGIONmatches your Datadog account's region (defaults tous1). - Confirm permissions. For CloudWatch, the IAM user needs
logs:CreateLogGroup,logs:CreateLogStream, andlogs:PutLogEventspermissions. For other services, ensure the API key or token has write access. - Look in the right place. CloudWatch logs appear under the log group
livekit/<agent-id>. The log group is created automatically on first write — if it doesn't exist, logs haven't been delivered yet. - Redeploy after changing secrets. Secret changes take effect on the next deployment. If you added or updated secrets after deploying, redeploy your agent.