feat: capture Gemini cache and thinking tokens in instrument_google_genai

[JonathanTsen]

Summary

• Patches upstream _GenerateContentInstrumentationHelper to extract cached_content_token_count, thoughts_token_count and tool_use_prompt_token_count from response.usage_metadata and emit them as gen_ai.usage.cache_read.input_tokens, gen_ai.usage.details.thoughts_tokens and gen_ai.usage.details.tool_use_prompt_tokens.
• Computes operation.cost via genai-prices when available (silent failure if the package is missing or the model is unknown).
• Closes the gap where direct google.genai users (not going through pydantic-ai) were missing cache and thinking metrics in their spans.

Implementation notes

• Defensive monkey-patch of two upstream methods (_maybe_update_token_counts, create_final_attributes), following the same pattern already used elsewhere in logfire/_internal/integrations/google_genai.py. Wrapped in try/except at module load so a future upstream rename keeps the base instrumentor working.
• Methods confirmed present in opentelemetry-instrumentation-google-genai 0.7b0; current pinning in pyproject.toml is >= 0.4b0.
• Streaming uses the upstream "keep last non-zero" semantics — walrus operator naturally ignores None/0, so partial chunks don't overwrite a final value.
• Unlike Anthropic, the Gemini API's prompt_token_count already includes cached tokens, so we expose cache_read separately rather than summing.
• genai-prices is invoked with response.model_dump(by_alias=True) because the extractor expects camelCase JSON keys (usageMetadata, modelVersion).

Test plan

• uv run pytest tests/otel_integrations/test_google_genai.py — 8 passing (3 new + 5 existing; existing VCR snapshots updated to include the new attributes that real Gemini responses already carry).
• make lint
• make typecheck

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/integrations/llms/google-genai.md">

<violation number="1" location="docs/integrations/llms/google-genai.md:59">
P2: Documentation for `operation.cost` should clarify that the attribute is only present when `genai-prices` is installed and the model pricing is known, since the implementation silently skips cost calculation otherwise.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Documentation for operation.cost should clarify that the attribute is only present when genai-prices is installed and the model pricing is known, since the implementation silently skips cost calculation otherwise.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At docs/integrations/llms/google-genai.md, line 59:

<comment>Documentation for `operation.cost` should clarify that the attribute is only present when `genai-prices` is installed and the model pricing is known, since the implementation silently skips cost calculation otherwise.</comment>

<file context>
@@ -53,10 +53,13 @@ following attributes may appear depending on the response:
+- `gen_ai.usage.cache_read.input_tokens` — tokens served from [context cache](https://ai.google.dev/gemini-api/docs/caching) (cache hit)
+- `gen_ai.usage.details.thoughts_tokens` — [reasoning tokens](https://ai.google.dev/gemini-api/docs/thinking) (Gemini 2.5 / 3.x)
+- `gen_ai.usage.details.tool_use_prompt_tokens` — tokens used for [tool definitions](https://ai.google.dev/gemini-api/docs/function-calling)
+- `operation.cost` — calculated price in USD using the [official Gemini pricing tables](https://ai.google.dev/gemini-api/docs/pricing) via [`genai-prices`](https://pypi.org/project/genai-prices/)
 
 Note that, unlike Anthropic, the Gemini API's `prompt_token_count` already includes
</file context>

Suggested change

	- `operation.cost` — calculated price in USD using the [official Gemini pricing tables](https://ai.google.dev/gemini-api/docs/pricing) via [`genai-prices`](https://pypi.org/project/genai-prices/)
	- `operation.cost` — calculated price in USD using the [official Gemini pricing tables](https://ai.google.dev/gemini-api/docs/pricing) via [`genai-prices`](https://pypi.org/project/genai-prices/) (only present when the package is installed and model pricing is known)