Skip to main content

Log collection

Monitor and debug your deployed agents with comprehensive logging.

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. You can also view some logs with the LiveKit CLI. LiveKit Cloud does not store runtime logs.

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.

Single instance

The LiveKit CLI only shows logs from the newest worker instance of your agent, which can include multiple jobs. All logs from this worker are included, but it is not a comprehensive view of all logs from all instances for agents running at scale. To collect logs from all instances, use the Datadog integration.

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.

Forward runtime logs

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

Currently, the only supported external service is Datadog.

Datadog integration

Add a Datadog client token as a secrets 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"
DATADOG_TOKENstringRequired

Your Datadog client token.

DATADOG_REGIONstringOptionalDefault: us1

Your Datadog region. Supported regions are us1, us3, us5, us1-fed, eu, and ap1.

Log levels

Your agent worker 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"]

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

Log retention

LiveKit Cloud does not store runtime logs. Build logs are stored indefinitely for the most recently deployed version.

Additional resources

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