Langchain and Langgraph don't report cached/reasoning token usage

[sentry-junior]

The Langchain and Langgraph integrations only record input_tokens, output_tokens, and total_tokens on spans. They don't populate gen_ai.usage.input_tokens.cached or gen_ai.usage.output_tokens.reasoning, even though SPANDATA already defines both and the OpenAI, OpenAI Agents, and Google GenAI integrations already set them from equivalent provider fields (e.g. prompt_tokens_details.cached_tokens, completion_tokens_details.reasoning_tokens).

Without these, cost calculations that rely on cache discounts and reasoning-token pricing are inaccurate for Langchain/Langgraph-instrumented apps.

• sentry_sdk/integrations/langchain.py: _extract_tokens, _extract_tokens_from_generations, and _record_token_usage only read prompt_tokens/input_tokens, completion_tokens/output_tokens, and total_tokens from the token usage dict.
• sentry_sdk/integrations/langgraph.py: token accumulation loop only reads prompt_tokens, completion_tokens, total_tokens from response_metadata["token_usage"].

Both should also extract cached input tokens and reasoning output tokens where the underlying LLM provider surfaces them (e.g. via usage_metadata.input_token_details.cache_read / output_token_details.reasoning in LangChain's newer usage metadata shape) and set SPANDATA.GEN_AI_USAGE_INPUT_TOKENS_CACHED / SPANDATA.GEN_AI_USAGE_OUTPUT_TOKENS_REASONING accordingly.

Related: #5455 (same gap for the LiteLLM integration).

Requested by Connor via Junior.

--

View Junior Session in Sentry

[linear-code]

PY-2606

[sentry-junior]

Update: the customer also flagged gen_ai.usage.input_tokens.cache_write. Confirmed — SPANDATA.GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE also exists and is already populated by the Anthropic integration (from usage.cache_creation_input_tokens) and the Pydantic AI integration (from usage.cache_write_tokens). Langchain and Langgraph don't set it either, so this should be included alongside cached and reasoning in the fix.

[flippingbitss]

Hi, I reported this issue and would like to pick up the implementation work to speed things up. This will be my first PR on the SDK and would appreciate any feedback/guidance.

For the approach, for Langchain, I'm thinking we create a simple _TokenUsage class internal to langchain.py/langgraph.py that is the normalized version of UsageMetadata (source) from Langchain. This is returned in AIMessage from Langchain. It is already being read in _get_token_usage. We need to extend the existing metrics in _extract_tokens/_extract_tokens_from_generations to use the model class and do the aggregation.

I was thinking to use the helper record_token_usage from sentry_sdk.ai.monitoring instead of the existing set_on_span calls being done in a private _record_token_usage function.

For Langgraph, I would like to import the above _TokenUsage class and reuse the _extract_tokens function from langchain.py. I'm not sure if this is okay, maybe I can copy-paste the same logic in langgraph.py to keep it fully separate. Please let me know.

One thing to note, UsageMetadata is supposed to be provider-agnostic but I don't know if we need to support any existing/legacy providers. For e.g. - OpenAI has prompt_tokens_details/completion_tokens_details instead of input_token_details/output_token_details. I can add a fallback for that if we need to support it (please let me know) as I'm not sure if that mapping is already happening internally.

For testing, I'm thinking I can reuse the existing test and add more metrics to the completions and assert them along with existing metrics. As per the contribution guide, I don't want to add any mocks and keep the test E2E.

Thanks and appreciate any suggestions!