adk-observability-guide（adk 可观察性指南）

ADK Observability Guide

Scaffolded project? Cloud Trace and prompt-response logging are pre-configured by Terraform. See references/cloud-trace-and-logging.md for infrastructure details, env vars, and verification commands. No scaffold? Follow the ADK docs links below for manual setup. For production infrastructure, scaffold with /adk-scaffold.

Reference Files

Observability Tiers

Choose the right level of observability based on your needs:

Ask the user which tier(s) they need — they can be combined. Cloud Trace is always on; the others are additive.

Cloud Trace

ADK uses OpenTelemetry to emit distributed traces. Every agent invocation produces spans that track the full execution flow.

Span Hierarchy

invocation
  └── agent_run (one per agent in the chain)
        ├── call_llm (model request/response)
        └── execute_tool (tool execution)

Setup by Deployment Type

View traces: Cloud Console → Trace → Trace explorer

For detailed setup instructions (Agent Engine CLI/SDK, Cloud Run, custom deployments), fetch the ADK docs:

• WebFetch: https://google.github.io/adk-docs/integrations/cloud-trace/index.md

Prompt-Response Logging

Captures GenAI interactions (model name, tokens, timing) and exports to GCS (JSONL), BigQuery (external tables), and Cloud Logging (dedicated bucket).

Privacy Modes

Prompt-response logging is privacy-preserving by default — only metadata is logged. Controlled by OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT:

For Agent Engine: the platform requires true during deployment, but the app overrides to NO_CONTENT at runtime.

Behavior by Environment

To enable locally, set LOGS_BUCKET_NAME and OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=NO_CONTENT before running make playground.

To disable in a deployed environment, set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false in deployment/terraform/service.tf and re-apply.

For scaffolded project infrastructure details (Terraform resources, env vars, verification), see references/cloud-trace-and-logging.md.

For ADK logging docs (log levels, configuration, debugging):

• WebFetch: https://google.github.io/adk-docs/observability/logging/index.md

BigQuery Agent Analytics Plugin

An optional plugin that logs structured agent events directly to BigQuery via the Storage Write API. Enables:

• Conversational analytics — session flows, user interaction patterns
• LLM-as-judge evals — structured data for evaluation pipelines
• Custom dashboards — Looker Studio integration
• Tool provenance tracking — LOCAL, MCP, SUB_AGENT, A2A, TRANSFER_AGENT

Enabling

Infrastructure (BigQuery dataset, GCS offloading) is provisioned automatically by Terraform when enabled at scaffold time.

Key Features

• Auto-schema upgrade (new fields added without migration)
• GCS offloading for multimodal content (images, audio)
• Distributed tracing via OpenTelemetry span context
• SQL-queryable event log for all agent interactions

For full schema, SQL query examples, and Looker Studio setup:

• WebFetch: https://google.github.io/adk-docs/integrations/bigquery-agent-analytics/index.md

Third-Party Integrations

ADK supports several third-party observability platforms. Each uses OpenTelemetry or custom instrumentation to capture agent behavior.

Ask the user which platform they prefer — present the trade-offs and let them choose. For setup details on each, see references/third-party.md.

Troubleshooting

Deep Dive: ADK Docs (WebFetch URLs)

For detailed documentation beyond what this skill covers, fetch these pages: