> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-flows-declarative.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipecat Cloud Logging and Observability

> Obtain logs and metrics from Pipecat Cloud agents and sessions for debugging, monitoring, and production observability.

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

## 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](/pipecat-cloud/fundamentals/secrets) 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:

```bash theme={null}
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:

```bash theme={null}
pipecat cloud agent logs my-agent -l ERROR
```

### Log retention

Agent logs are kept for 30 days by default. Logs older than 30 days are deleted and cannot be recovered. To keep logs longer, forward them to your own logging service. See [Using Datadog](../guides/using-datadog) for an example.

### 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.

```python theme={null}
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 `RunnerArguments` object (or subclass alternative) passed to your `bot()` method:

```python theme={null}
from pipecat.runner.types import RunnerArguments

async def bot(args: RunnerArguments):
	session_id = args.session_id
```

<Note>
  See [the Session Arguments reference](../sdk-reference/session-arguments) for
  more additional SessionArgument types.
</Note>

## 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:

```bash theme={null}
pipecat cloud agent sessions my-agent --id <session-id>
```

See the [CLI reference](/api-reference/cli/cloud/agent#sessions) for more details.

## Built-in pipeline observability

The base image automatically adds [StartupTimingObserver](/api-reference/server/utilities/observers/startup-timing-observer) and [UserBotLatencyObserver](/api-reference/server/utilities/observers/user-bot-latency-observer) 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](#agent-logs).

<Note>
  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.
</Note>