Docs/FAQ: How does --bq-analytics differ from GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY + OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT? #94

Reader question

Surfaced from a Medium comment thread on the Track every AI agent interaction with one CLI flag post (https://medium.com/google-cloud/track-every-ai-agent-interaction-with-one-cli-flag-cae20ffa5100):

How is it different from the traces which are generated automatically with flags GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY and OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT?

Filing this as a docs/FAQ issue so the answer is searchable on the repo and future readers don't have to chase Medium comments. Also worth pulling into a short section in the SDK docs once it stabilizes.

Answer

Both paths exist; they're complementary, not competing. Quick read on what each does and where to reach for it.

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY + OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT

These wire up ADK's built-in OpenTelemetry instrumentation (ADK ≥ 1.17). They emit:

• Traces → Cloud Trace (OTLP API)
• Logs → Cloud Logging
• Metrics → Cloud Monitoring

You view them in the Vertex AI Agent Engine UI's Traces tab — span DAGs, attributes, prompts/responses inline. Designed for real-time debugging of one trace with a default ~30-day retention window. Filtering is span-name / time-range based; not arbitrary SQL over the events.

Source: Instrument ADK applications with OpenTelemetry — Cloud Observability docs.

--bq-analytics (Agent Starter Pack flag) / the BigQuery Agent Analytics plugin

Wires the BigQueryAgentAnalyticsPlugin (this SDK) into the agent. Every event lands as a typed row in a BigQuery agent_events table (timestamp, session_id, span_id, parent_span_id, event_type, content JSON, latency_ms, status, error_message, …). Designed for fleet-level analytics over long history — arbitrary SQL, dbt models, dashboards, percentile queries, and SDK-driven evaluation (deterministic gates via bq-agent-sdk evaluate --exit-code, LLM-as-Judge via AI.GENERATE against your own traces).

Differences that matter in practice

TL;DR

• Keep OTEL on for live debugging in the Agent Engine UI.
• Add --bq-analytics when you also want a long-term, queryable, evaluatable record of every interaction.
• They write to different destinations and don't conflict.

If you're choosing only one: pick OTEL when your job is debugging individual sessions; pick --bq-analytics when your job is monitoring quality, cost, and regressions across a fleet. Most production agent teams end up wanting both.

Suggested follow-up

• Pull a condensed version of this comparison into the SDK README's "What this is / what this isn't" section.
• Cross-link from docs/ (perhaps a new docs/faq.md) so the answer is reachable without a search through issues.
• Add a one-paragraph compare/contrast box to the Track every AI agent interaction Medium post if a future revision is open.

Related

• Source post: https://medium.com/google-cloud/track-every-ai-agent-interaction-with-one-cli-flag-cae20ffa5100
• ADK OpenTelemetry instrumentation docs: https://docs.cloud.google.com/stackdriver/docs/instrumentation/ai-agent-adk
• Vertex AI Agent Engine tracing: https://docs.cloud.google.com/agent-builder/agent-engine/manage/tracing
• Agent Starter Pack monitoring/observability: https://googlecloudplatform.github.io/agent-starter-pack/guide/observability.html