> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug with logs and traces

> Inspect traces, spans, and logs to understand what your agent is doing.

The ADK provides two observability views in the dev console and a CLI command for reading logs.

## Traces

The **Traces** view in the dev console shows a timeline of every span in your agent's execution. Each conversation turn, workflow step, tool call, and LLM request is captured as a span with timing and metadata.

![Traces view in dev console](https://mintcdn.com/botpress/Ed348iUAnzYbpNJA/adk/assets/traces-view.png?fit=max\&auto=format\&n=Ed348iUAnzYbpNJA\&q=85\&s=81fd0a091a67e51021b1612d3997982c)

### What you can see

* **Handler spans** showing conversation and workflow handler execution
* **Autonomous execution** spans for each `execute()` call, including iteration count and model used
* **Tool call spans** with input, output, and duration
* **LLM call spans** with model, token usage, and latency
* **Knowledge search spans** with queries and result counts
* **Error spans** with stack traces

### Filtering

Filter traces by time range, span type, or search for specific content. Click any span to expand its details and see its child spans.

## Logs

The **Logs** view in the dev console shows structured log output from your agent. Any `console.log`, `console.warn`, or `console.error` from your handlers, tools, and actions appears here.

![Logs view in dev console](https://mintcdn.com/botpress/Ed348iUAnzYbpNJA/adk/assets/logs-view.png?fit=max\&auto=format\&n=Ed348iUAnzYbpNJA\&q=85\&s=d27b474f6a539fbcc2ab6a70aa78f2af)

### CLI

You can also read logs from the command line:

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
adk logs                         # Show recent logs
adk logs --follow                # Stream logs in real time
adk logs error                   # Errors only
adk logs warning since=1h        # Warnings and errors from the last hour
adk logs limit=100               # Last 100 entries
```

The positional filter tokens are `error` / `warning` / `info` (cumulative level), `since=<duration>`, and `limit=<n>`. See the [CLI reference](https://botpress.com/docs/adk/cli-reference.md#adk-logs) for all flags.

Logs are stored in `.adk/logs/` while the dev server is running.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.