fix(langchain): emit cache creation tokens

[dvirski]

Summary by CodeRabbit

• New Features
  • Enhanced GenAI cache metrics tracking by reporting both cache read and cache creation token usage (when available).
• Bug Fixes
  • Improved cache token metric handling to avoid setting usage attributes with invalid or missing token values, ensuring metrics are recorded only when the underlying data is numeric and meaningful.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 05921872-6b2f-4c39-acff-56ed275dffa7

📥 Commits

Reviewing files that changed from the base of the PR and between f5272ae and bc84aaf.

📒 Files selected for processing (1)

• packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py

---

📝 Walkthrough

Walkthrough

set_chat_response_usage in the LangChain instrumentation is extended to track cache_creation_tokens. The function initializes both cache token counters to None, extracts and accumulates them from usage metadata only when values are numeric, broadens the write-guard condition to check for non-None values rather than explicit thresholds, and sets the GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS span attribute.

Changes

Cache creation token tracking in LangChain span utilities

Layer / File(s)	Summary
Initialize, parse, gate, and emit cache_creation_tokens packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py	cache_creation_tokens is initialized to None alongside cache_read_tokens, both counters accumulate numeric values from input_token_details["cache_read"] and input_token_details["cache_creation"], the write-guard condition expands from cache_read_tokens > 0 to check if either variable is non-None, and GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS is set in the span attributes.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• traceloop/openllmetry#4240: Updates cache-related span attribute emission in the same span_utils.py file, with this PR adding cache creation token tracking and the related PR adding cache read token tracking.

Poem

🐇 A token was hiding in "cache_create," tucked deep,
The rabbit sniffed it out and tracked it with care—
Now cache_creation_tokens tracks every byte,
Parsed, guarded, and emitted with numeric delight,
No phantom values slip past this careful insight! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(langchain): emit cache creation tokens' accurately describes the main change: adding support for emitting cache creation tokens in the langchain instrumentation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix(langchain)emit-cache-creation-tokens

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py`:
- Around line 428-430: The `cache_creation_tokens` accumulation at the line with
`cache_creation_tokens += input_token_details.get("cache_creation", 0)` assumes
the value is always numeric, but it can be an object, causing a TypeError that
gets caught by the broad exception handler and skips remaining generations. Fix
this by safely extracting the numeric value from the `cache_creation` field,
handling both numeric values and object cases (where you should extract a
numeric property from the object), and provide a sensible default value when the
data is missing or cannot be converted.
- Around line 440-441: The write-guard conditions using `>= 0` for
cache_read_tokens and cache_creation_tokens always evaluate to true since these
counters are initialized to 0, causing the usage metadata block at line 443 to
execute unconditionally. Change the comparison operators from `>= 0` to `> 0`
for both cache_read_tokens and cache_creation_tokens to ensure the block only
executes when actual token values are present. Additionally, set
has_cache_details to True only when input_token_details is actually present and
successfully parsed, not based on these conditions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a1572374-5dd7-4029-bba9-14cb3afbe46a

📥 Commits

Reviewing files that changed from the base of the PR and between 7b886f6 and 8ebc34a.

📒 Files selected for processing (1)

• packages/opentelemetry-instrumentation-langchain/opentelemetry/instrumentation/langchain/span_utils.py

[nina-kollman]

Why not init the 'cache_creation_tokens' to 0 ? same for cache_read_tokens

[dvirski]

cache_creation_tokens and cache_read_tokens might not be provided at all. so we want to distinguish between not provided and 0.

If not provided we omit them, but we do want to log them if they have value of 0.