Debug with logs and traces

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.

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.

CLI

You can also read logs from the command line:

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 for all flags.

The Dev Console Logs tab and adk logs read from the local log store at .adk/bot/logs/logs.db. adk dev also writes session .log files under .adk/logs/ for durable troubleshooting.

Export to your own tools

To send runtime traces to your own observability stack, start the dev server with OTLP export:

adk dev --otlp                   # export to an OpenTelemetry collector on port 4318
adk dev --otlp --port-otlp 4319  # use a different collector port (Jaeger, otel-tui, etc.)

Understand behavior over time

Traces and logs show individual runs. To see aggregate trends, such as conversation volume, latency, token usage, and cost, use Analytics.

Common errors

Error	Cause	Fix
`NO_DEV_BOT`	You ran a dev command before your dev bot existed	Run `adk dev` first to create it
`BOT_NOT_LINKED`	No production bot is linked	Run `adk link`
Deploy blocked on a dependency	An enabled integration is unconfigured or unconnected	Run `adk integrations status --target prod`, then configure or connect it
A teammate’s integration is missing	Integration state isn’t shared through git	Seed your dev bot: `adk integrations copy --from prod --to dev`