Log collection

Overview

LiveKit Cloud provides realtime logging for your deployed agents, helping you monitor performance, debug issues, and understand your agent's behavior in production. Logs are collected from all phases of your agent's lifecycle — from build to runtime — and can be forwarded to external monitoring services such as Datadog , CloudWatch , Sentry , and New Relic . You can also view some logs with the LiveKit CLI.

Log types

LiveKit Cloud collects two types of logs for your agents:

• Runtime logs: Your agent's app logs, including stdout, stderr, and any other logging you implement.
• Build logs: Output from the container build process, including Dockerfile execution and dependency installation.

Follow runtime logs

Use the LiveKit CLI to follow logs from your deployed agents in realtime.

lk agent logs

This command continuously streams logs from the latest running instance of your agent. It also includes a short snapshot of recent logs.

View build logs

Use the LiveKit CLI to view the Docker build logs from the currently deployed version of your agent.

lk agent logs --log-type=build

This command prints the logs to stdout, but does not perform a live tail.

Build logs from more versions of your agent are available in the LiveKit Cloud dashboard .

View runtime logs

Runtime logs are available in three places. Each place covers a different set of logs and keeps them for a different length of time:

• Logs from one session. Open the session on the Sessions  page and select the Agent insights tab. Session logs appear on the timeline beside the transcript, traces, and audio for that session, so you can read a log line against the turn that produced it. Only project admins can read them. See Agent insights.
• Logs from the running instance. Use lk agent logs to tail the most recently started agent server instance, as described in Follow runtime logs. Use it to watch logs that don't belong to a session, such as startup output, as they happen.
• Long-term logs from every instance. Forward runtime logs to an external service with a log drain. A log drain also receives events outside of a session, such as crashes, startup failures, and dispatch errors.

Forward runtime logs

Forward your agent logs to external monitoring services for long-term storage, advanced analytics, and integration with your existing observability stack.

The currently supported destinations are Datadog, CloudWatch, Sentry, and New Relic.

Datadog integration

Add a Datadog client token as a secret to automatically enable log forwarding. If your account is in a region other than us1, you can also set the region. All runtime logs are automatically forwarded to your Datadog account.

lk agent update-secrets --secrets "DATADOG_TOKEN=your-client-token"

Log fields

The following log fields are set in Datadog for all log lines sent from LiveKit Cloud:

CloudWatch integration

Add a CloudWatch AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as secrets to automatically enable log forwarding. The AWS region defaults to us-west-2, you can set it by setting the AWS_REGION secret. All runtime logs are automatically forwarded to your CloudWatch account.

lk agent update-secrets --secrets "AWS_ACCESS_KEY_ID=your-access-key-id" --secrets "AWS_SECRET_ACCESS_KEY=your-secret-access-key"

Sentry integration

Add a Sentry SENTRY_DSN as a secret to automatically enable log forwarding. All runtime logs are automatically forwarded to your Sentry account.

lk agent update-secrets --secrets "SENTRY_DSN=your-sentry-dsn"

New Relic integration

Add a New Relic NEW_RELIC_LICENSE_KEY as a secret to automatically enable log forwarding. All runtime logs are automatically forwarded to your New Relic account.

lk agent update-secrets --secrets "NEW_RELIC_LICENSE_KEY=your-license-key"

Log levels

Your agent server configuration determines the log levels that are collected and forwarded. The default log level is info. To use a different value, set the log level in your Dockerfile:

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

You can also set the log level with the LIVEKIT_LOG_LEVEL environment variable, which is useful when you want to adjust verbosity without rebuilding your image. Set it as a secret:

lk agent update-secrets --secrets "LIVEKIT_LOG_LEVEL=debug"

For more information on log levels, see the agent server options page.

Log retention

Agent build logs are stored indefinitely for the most recently deployed version. To learn about runtime log retention, see the Agent insights page.

Additional resources

The following resources may be helpful to design a logging strategy for your agent: