Where to find your Agent Logs

During development, your agent logs will be displayed in your terminal window, but once you deploy your agent, you will need to understand where agent logs are stored to debug buildtime and runtime issues.

Build Logs

Agents deployed to LiveKit cloud are built in Docker containers that manage all dependencies. Build logs are available from your cloud dashboard or through the LiveKit CLI.

Please see the documentation for more information about viewing and downloading build-time logs.

For self-hosted agent deployments, build logs will be available from the platform you are using to host.

Runtime Logs

When an agent server accepts a job request, it starts a new process and runs your agent code inside.

When starting your agent, you can pass the log level as an optional argument:

From the command line:

Python: uv run agent.py start --log-level=DEBUG

Node.JS: pnpm run start --log-level=debug

From within your Dockerfile:

Python: CMD ["uv", "run", "src/agent.py", "start", "--log-level=DEBUG"]

Node.JS: CMD ["pnpm", "run", "start", "--log-level=debug"]

If not specified, the default log level will be INFO for agents started with the start command.

During development, when agents are invoked with dev or console, the default log level is DEBUG.

To add your own logs, use the standard Python logging module:

logger = logging.getLogger("myAgent")

…
logger.info("Info message")
logger.warning("Warning message")

Or the agents logger in Node.js

import { log } from '@livekit/agents';
…
log().info(‘Info message’);
log().warn('Warning message');

Accessing logs for deployed agents

There are three ways to view runtime agent logs:

• By forwarding your logs to an external monitoring service such as Datadog, CloudWatch, Sentry, or New Relic.
• Viewing live logs using the LiveKit CLI
• Viewing logs recorded as part of the telemetry recorded by agent insights.

Forwarding logs to an external service

Agents hosted in LiveKit cloud can automatically forward your agent logs to the following platforms: Datadog, CloudWatch, Sentry, or New Relic. Please see the agent log documentation for full details on how to set this up, but it can be as easy as just defining secrets for your chosen monitoring service.

If you are self-hosting your agent, you will need to forward the logs yourself, if desired.

Forwarding logs to an external service provider is a very flexible and powerful approach, especially if you already use an external logging service for other parts of your solution.

It is recommended to set up external forwarding as you start to scale, since only this approach can give you a complete picture across all running agent servers, and it gives you full control over how long your data is retained.

Viewing live logs with the LiveKit CLI

Note: Viewing logs with the LK CLI is only supported by agents hosted in LiveKit cloud

As noted in the log documentation, you can view an ongoing tail of agent logs using the LiveKit CLI as follows:

lk agent logs

This will output the current logs for the current default LiveKit project.

You can only view the logs for one agent at a time, if you need to specify another agent ID you can do so as follows:

lk agent logs --id <agent-id>

To see which agents exist, along with their IDs, you can run lk agent list, or consult your cloud dashboard for the desired project.

Viewing logs through the CLI is a great technique if you are able to consistently reproduce the bug you are investigating, but the technique does not lend itself to storing logs for long-running agents. Please also note that as you scale, only the newest agent server instance is shown (see the documentation note for more information).

Can I view historic logs through the CLI? No, when you first execute the command you will receive a short snapshot of recent logs, but there is no guarantee how much historical data will be returned.

Retrieving logs from Agent Observability

LiveKit agent observability allows you to monitor and analyze your agent’s behaviour through traces, audio recordings, transcripts and logs. Many customers find Observability the most intuitive way to obtain logs, since they are available from the cloud dashboard, but there are some important caveats to this approach.

Agent Observability requirements:

• Your agent must be running a recent version of the Agents SDK (1.3.0 or higher for Python, or 1.0.18 or higher for Node.js). If you created your agent using LiveKit agent builder, you already meet these requirements.
• "Agent observability" needs to be enabled in your project settings dashboard.
• Agents hosted in LiveKit cloud as well as self-hosted agent deployments are supported. Note that sessions using a self-hosted deployment of LiveKit are not supported.

Session logs are available as follows:

1. Select your desired Session in the dashboard.
2. Select the ‘Agent insights’ tab
3. Select the ‘Logs’ tab

Logs can be downloaded in .json format using the ‘Download data’ button, or shared with LiveKit support using the ‘Share’ button.

Caveats to using Agent Observability for logs:

• Observability data is automatically deleted after 30 days. At the time of writing it is not possible to export observability log data to an external provider.
• Observability data will only be uploaded to LiveKit cloud after your session completes, this means you can not view live logs and will see no data at all if your agent crashed before the upload was completed.
• Logs are scoped to your agent session, so you will not see any logs related to agent dispatch or job assignment.
  At the time of writing, it is not possible to select a region where Observability data is stored, it will be stored in the US.

As the name suggests, the primary use for observability logs are to be used alongside other data points such as traces and transcripts to explain agent behaviour, for example your trace might indicate a slow tool call and the log messages might give clues to explain why. Observability logs should not be used as a replacement for forwarding logs to an external service, as described earlier.

Are there any other ways to view historic logs?

No, if you find yourself in a situation where you need to understand a runtime issue, you should enable logging in your environment and then reproduce the issue.