Logging and Observability

Obtaining logs and metrics from your agents and sessions

This section of the documentation is currently work in progress. Please check back soon for updates.

Configuring log level

You can control the Pipecat logging level for your deployed agents using the PIPECAT_LOG_LEVEL environment variable. This can be set as a secret or directly in your deployment configuration.

Available log levels:

Level	Description
TRACE	The most detailed information for debugging (includes Frame logging)
DEBUG	Verbose output for debugging (default)
INFO	General operational information
WARNING	Warning messages for potential issues
ERROR	Error messages only

Agent logs

Agent logs are available via both the CLI and Dashboard. You can view logs for a specific agent by running the following command:

pipecat cloud agent logs my-agent

This command accept various filters to help you narrow down the logs you are looking for. For example, you can filter logs by severity level:

pipecat cloud agent logs my-agent -l ERROR

Session logging

We recommend using the loguru library for logging within your agent. This will ensure any logging within your agent associated to the session it is running in.

from loguru import logger

async def bot():
	logger.info("Hello, world!") # will be associated with the session id

If you are handling logging manually, you can obtain the active session ID from the PipecatRunnerArguments object (or subclass alternative) passed to your bot() method:

from pipecat.runner.types import PipecatRunnerArguments

async def bot(args: PipecatRunnerArguments):
	session_id = args.session_id

See the Session Arguments reference for more additional SessionArgument types.

CPU and memory metrics

Pipecat Cloud tracks CPU and memory usage for each session, which can be helpful for troubleshooting performance issues. You can view these metrics in two ways:

Dashboard

Navigate to your agent in the Pipecat Cloud dashboard, then go to Sessions and click on a specific Session ID to view CPU and memory usage graphs.

CLI

Use the sessions command with a specific session ID to see CPU and memory usage with sparkline visualizations and percentile summaries:

pipecat cloud agent sessions my-agent --id <session-id>

See the CLI reference for more details.

Built-in pipeline observability

The base image automatically adds StartupTimingObserver and UserBotLatencyObserver to every PipelineWorker. These observers log structured timing data that helps you understand your agent’s performance:

• Startup timing — how long each processor takes to initialize
• Transport timing — time to connect the bot and client to the transport
• User-bot latency — time between a user finishing speaking and the bot starting to respond
• Latency breakdown — per-service breakdown of where latency is spent (e.g., LLM TTFB, TTS text aggregation)
• First bot speech — time until the bot first speaks after a client connects

All events are logged with the [pcc-observability] prefix and are visible in your agent logs.

This feature requires pipecat-ai>=0.0.104 and pipecat-base>=0.1.16. The feature is enabled automatically when the dependencies are available. No configuration is needed.