feat: first-class context cache metrics in BigQuery analytics plugin

[caohy1988]

Summary

Implements #5210

Promotes context cache token data to first-class BigQuery view columns and logs cache_metadata as a structured attribute, enabling cache hit-rate analysis directly in SQL without manual JSON extraction.

Changes

bigquery_agent_analytics_plugin.py (~25 lines):

1. EventData: Added cache_metadata: Any = None field
2. after_model_callback(): Passes llm_response.cache_metadata through to EventData
3. _enrich_attributes(): Stores truncated cache_metadata in attributes when present
4. _EVENT_VIEW_DEFS["LLM_RESPONSE"]: Three new view columns:
   • usage_cached_tokens — INT64 from attributes.usage_metadata.cached_content_token_count
   • context_cache_hit_rate — FLOAT64 via SAFE_DIVIDE(cached/prompt), NULL when no cache
   • cache_metadata — JSON from attributes.cache_metadata

What does NOT change

• content.usage extraction (still only prompt/completion/total) — no content schema evolution
• No new BigQuery table columns — all data stored in existing JSON columns (content, attributes)
• Existing queries and views unaffected — all changes are additive and NULL-safe

Usage

-- Before: manual JSON extraction
SELECT
  CAST(JSON_VALUE(attributes, '$.usage_metadata.cached_content_token_count') AS INT64)
FROM `project.dataset.agent_events`
WHERE event_type = 'LLM_RESPONSE'

-- After: first-class view columns
SELECT usage_cached_tokens, context_cache_hit_rate, cache_metadata
FROM `project.dataset.v_llm_response`

Test plan

• 196 tests pass, 0 regressions
• test_cache_metadata_stored_in_attributes — verifies cache_metadata appears in attributes with correct fields
• test_no_cache_metadata_when_absent — verifies no cache_metadata key when LlmResponse has none
• test_view_def_includes_cache_columns — verifies view definition contains all three new columns

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[adk-bot]

Response from ADK Triaging Agent

Hello @caohy1988, thank you for creating this PR!

It looks like you have not yet signed the Contributor License Agreement (CLA). Please visit https://cla.developers.google.com/ to sign it.

This information will help reviewers to review your PR more efficiently. Thanks!