Add cache_write_input_tokens and modality token usage attributes

[lmolkova]

What does this change do?

Adds cache_write_input_tokens (deprecating cache_creation_input_tokens) and modality token breakdown attributes to invocations in opentelemetry-util-genai, updating openai, google-genai, bedrock, and langchain to record them where available.

Deprecated attribute:

• gen_ai.usage.cache_creation.input_tokens (replaced by gen_ai.usage.cache_write.input_tokens)

New attributes:

• gen_ai.usage.cache_write.input_tokens
• gen_ai.usage.text.input_tokens
• gen_ai.usage.image.input_tokens
• gen_ai.usage.audio.input_tokens
• gen_ai.usage.text.output_tokens
• gen_ai.usage.image.output_tokens
• gen_ai.usage.audio.output_tokens
• gen_ai.usage.text.cache_read.input_tokens
• gen_ai.usage.image.cache_read.input_tokens
• gen_ai.usage.audio.cache_read.input_tokens

Why?

Aligns token usage attributes with GenAI semantic conventions (spans spec).

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-09-04 06:25 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

🟡 Changes recommended

OpenAI extraction drops available usage data, Google cache modality handling is incomplete, and the legacy dataclass constructor is broken.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds semantic-convention token usage attributes across GenAI utilities and instrumentations.

Changes:

• Adds cache-write and modality-specific token fields.
• Updates OpenAI and Google GenAI extraction.
• Adjusts downstream tests and changelogs.

File summaries

File	Description
util/opentelemetry-util-genai/tests/test_utils.py	Tests new inference usage attributes.
util/opentelemetry-util-genai/tests/test_handler_agent.py	Updates agent cache-write assertion.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py	Adds and emits token breakdown fields.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_agent_invocation.py	Renames agent cache-write usage.
util/opentelemetry-util-genai/.changelog/613.deprecated	Records the deprecation.
util/opentelemetry-util-genai/.changelog/613.added	Records new attributes.
instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/interactions.py	Extracts modality usage.
instrumentation/opentelemetry-instrumentation-google-genai/.changelog/613.added	Documents Google GenAI support.
instrumentation/opentelemetry-instrumentation-genai-openai/src/opentelemetry/instrumentation/genai/openai/response_extractors.py	Extracts OpenAI usage details.
instrumentation/opentelemetry-instrumentation-genai-openai/.changelog/613.added	Documents OpenAI support.
instrumentation/opentelemetry-instrumentation-genai-langchain/tests/test_llm_call.py	Updates cache-write expectation.
instrumentation/opentelemetry-instrumentation-genai-bedrock/tests/test_invoke_model.py	Updates non-streaming expectation.
instrumentation/opentelemetry-instrumentation-genai-bedrock/tests/test_invoke_model_stream.py	Updates streaming expectation.

Review details

Suppressed comments (3)

instrumentation/opentelemetry-instrumentation-genai-openai/src/opentelemetry/instrumentation/genai/openai/response_extractors.py:592

• This extractor only receives the Responses API's ResponseUsage, whose input/output detail models do not expose audio_tokens, so these new audio assignments remain None for the current SDK. Audio counts are exposed by Chat Completions' prompt/completion token details; wire those through the chat response and stream paths so the advertised attributes are actually recorded.

        audio_input_tokens=(
            getattr(details, "audio_tokens", None)
            if details is not None
            else None
        ),

util/opentelemetry-util-genai/src/opentelemetry/util/genai/_inference_invocation.py:366

• This changes the generated dataclass constructor incompatibly: cache_creation_input_tokens= is no longer accepted because a property does not participate in dataclass.__init__, and inserting the new fields before attributes rebinds existing positional arguments. Preserve the deprecated constructor field/position and append new options after existing parameters, or provide a backward-compatible custom initializer.

    cache_write_input_tokens: int | None = None
    cache_read_input_tokens: int | None = None
    text_input_tokens: int | None = None
    image_input_tokens: int | None = None
    audio_input_tokens: int | None = None

instrumentation/opentelemetry-instrumentation-google-genai/src/opentelemetry/instrumentation/google_genai/interactions.py:162

• No Google GenAI test populates these modality lists or asserts the emitted attribute names and integer value types; the existing token tests only check aggregate input/output counts. Add coverage for text, image, and audio input/output breakdowns (including the shared sync/async paths) so field-name or enum-mapping mistakes are caught.

            if modality and tokens is not None:
                m = str(modality).lower()
                if m == "text":
                    invocation.text_input_tokens = tokens
                elif m == "image":

• Files reviewed: 13/13 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.