feat(llmobs): track prompt caching for anthropic sdk (#13757)

Tracks number of tokens read from and written to the prompt cache for
anthropic

https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching

anthropic returns `cache_creation/read_input_tokens` in their usage
field.

We map these to `cache_write/read_input_tokens` keys in our `metrics`
field.

Testing is blocked on
DataDog/dd-apm-test-agent#217

### implementation note
Right now, we are using `get_llmobs_metrics_tags` to set metrics for
anthropic, which depends on using `set_metric` and `get_metric`. We do
not want to continue this pattern for prompt caching, so we instead
directly extract it out from `response.usage`field.

The caveat is that for the streamed case, the `usage` field is a
dictionary that is manually constructed by us when parsing out streamed
chunks

### Follow ups
1. Move all the unit tests to use `llmobs_events` fixture
2. De-couple `metrics` parsing from set/get metrics completely

## Checklist
- [x] PR author has checked that all the criteria below are met
- The PR description includes an overview of the change
- The PR description articulates the motivation for the change
- The change includes tests OR the PR description describes a testing
strategy
- The PR description notes risks associated with the change, if any
- Newly-added code is easy to change
- The change follows the [library release note
guidelines](https://ddtrace.readthedocs.io/en/stable/releasenotes.html)
- The change includes or references documentation updates if necessary
- Backport labels are set (if
[applicable](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting))

## Reviewer Checklist
- [x] Reviewer has checked that all the criteria below are met 
- Title is accurate
- All changes are related to the pull request's stated goal
- Avoids breaking
[API](https://ddtrace.readthedocs.io/en/stable/versioning.html#interfaces)
changes
- Testing strategy adequately addresses listed risks
- Newly-added code is easy to change
- Release note makes sense to a user of the library
- If necessary, author has acknowledged and discussed the performance
implications of this PR as reported in the benchmarks PR comment
- Backport labels are set in a manner that is consistent with the
[release branch maintenance
policy](https://ddtrace.readthedocs.io/en/latest/contributing.html#backporting)

Author: lievan

ddtrace/contrib/internal/anthropic/_streaming.py

@@ -198,6 +198,14 @@ def _on_message_start_chunk(chunk, message):
             message["role"] = chunk_role
         if chunk_usage:
             message["usage"] = {"input_tokens": _get_attr(chunk_usage, "input_tokens", 0)}
+
+            cache_write_tokens = _get_attr(chunk_usage, "cache_creation_input_tokens", None)
+            cache_read_tokens = _get_attr(chunk_usage, "cache_read_input_tokens", None)
+            if cache_write_tokens is not None:
+                message["usage"]["cache_creation_input_tokens"] = cache_write_tokens
+            if cache_read_tokens is not None:
+                message["usage"]["cache_read_input_tokens"] = cache_read_tokens
+
     return message
 
 
@@ -250,6 +258,14 @@ def _on_message_delta_chunk(chunk, message):
     if chunk_usage:
         message_usage = message.get("usage", {"output_tokens": 0, "input_tokens": 0})
         message_usage["output_tokens"] = _get_attr(chunk_usage, "output_tokens", 0)
+
+        cache_creation_tokens = _get_attr(chunk_usage, "cache_creation_input_tokens", None)
+        cache_read_tokens = _get_attr(chunk_usage, "cache_read_input_tokens", None)
+        if cache_creation_tokens is not None:
+            message_usage["cache_creation_input_tokens"] = cache_creation_tokens
+        if cache_read_tokens is not None:
+            message_usage["cache_read_input_tokens"] = cache_read_tokens
+
         message["usage"] = message_usage
 
     return message

ddtrace/llmobs/_integrations/anthropic.py

@@ -7,6 +7,8 @@
 from typing import Union
 
 from ddtrace.internal.logger import get_logger
+from ddtrace.llmobs._constants import CACHE_READ_INPUT_TOKENS_METRIC_KEY
+from ddtrace.llmobs._constants import CACHE_WRITE_INPUT_TOKENS_METRIC_KEY
 from ddtrace.llmobs._constants import INPUT_MESSAGES
 from ddtrace.llmobs._constants import INPUT_TOKENS_METRIC_KEY
 from ddtrace.llmobs._constants import METADATA
@@ -184,6 +186,8 @@ def _extract_usage(self, span: Span, usage: Dict[str, Any]):
             return
         input_tokens = _get_attr(usage, "input_tokens", None)
         output_tokens = _get_attr(usage, "output_tokens", None)
+        cache_write_tokens = _get_attr(usage, "cache_creation_input_tokens", None)
+        cache_read_tokens = _get_attr(usage, "cache_read_input_tokens", None)
 
         metrics = {}
         if input_tokens is not None:
@@ -192,6 +196,10 @@ def _extract_usage(self, span: Span, usage: Dict[str, Any]):
             metrics[OUTPUT_TOKENS_METRIC_KEY] = output_tokens
         if input_tokens is not None and output_tokens is not None:
             metrics[TOTAL_TOKENS_METRIC_KEY] = input_tokens + output_tokens
+        if cache_write_tokens is not None:
+            metrics[CACHE_WRITE_INPUT_TOKENS_METRIC_KEY] = cache_write_tokens
+        if cache_read_tokens is not None:
+            metrics[CACHE_READ_INPUT_TOKENS_METRIC_KEY] = cache_read_tokens
         return metrics
 
     def _get_base_url(self, **kwargs: Dict[str, Any]) -> Optional[str]:

releasenotes/notes/ant-p-cache-3d4001a431cedd67.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    LLM Observability: This introduces capturing the number of input tokens read and written to the cache for Anthropic prompt caching use cases.
+

tests/contrib/anthropic/cassettes/anthropic_completion_cache_read.yaml

@@ -0,0 +1,217 @@
+interactions:
+- request:
+    body: '{"max_tokens": 100, "messages": [{"role": "user", "content": "What is a
+      system"}], "model": "claude-sonnet-4-20250514", "system": [{"type": "text",
+      "text": "Hardware engineering best practices guide: farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell farewell farewell farewell farewell farewell
+      farewell farewell farewell farewell ", "cache_control": {"type": "ephemeral"}}],
+      "temperature": 0.1}'
+    headers:
+      accept:
+      - application/json
+      accept-encoding:
+      - gzip, deflate
+      anthropic-beta:
+      - prompt-caching-2024-07-31
+      anthropic-version:
+      - '2023-06-01'
+      connection:
+      - keep-alive
+      content-length:
+      - '9480'
+      content-type:
+      - application/json
+      host:
+      - api.anthropic.com
+      user-agent:
+      - Anthropic/Python 0.28.1
+      x-stainless-arch:
+      - arm64
+      x-stainless-async:
+      - 'false'
+      x-stainless-lang:
+      - python
+      x-stainless-os:
+      - MacOS
+      x-stainless-package-version:
+      - 0.28.1
+      x-stainless-runtime:
+      - CPython
+      x-stainless-runtime-version:
+      - 3.10.13
+    method: POST
+    uri: https://api.anthropic.com/v1/messages
+  response:
+    body:
+      string: !!binary |
+        H4sIAAAAAAAAAwAAAP//ZFJdaxtBDPwrQnkoHOf0bOJS7i02KWmhJfSD0DTFqLuyb/Ge9rqrdZya
+        /PdyZ7t12ieBpBnNDNqhs1hjm1aLavz1y5v86nY+e313fTf7MH/PrX03mWGJ+thxv8Up0YqxxBh8
+        36CUXFISxRLbYNljjcZTtjxKQYR1dDGaVJNpNR1fYIkmiLIo1t92R0rlbQ8eSo2XUBTpMSm3RQEu
+        AQmEuCJxv9iCCd6zURcEwhKcKEfTHzE6DNsuCIsm0IYUHkJcg4YVa8MRNACZxvGGgSB1bNzSGehy
+        7EJiCBGWWQbmc7jmyECRQRuGNT+CaSiSUY4uqTOpvpd7OTuDeYgMV57b4WZYAsGnQXl9LyMoivkf
+        QS9vKGoqihreinUbZzN54CNyUNvSmiF3w829/z3JR/bUy0qN6waG+d5w3wISu0+BDo0frA/McpLF
+        nuVm77PHX/51vwrkT62fHIfEccMH9CxksRQdDwJuG9IXCZwYny33AmCTziFkTc7yfwauZONikN5q
+        j/7cMPBWOQp5GL5hq+AEn76XmDR0i8iUgvSvRtuFhjVLwsMo8c/MYhhryd6XmIdXrHfopMt6XK7H
+        4xINmYYXJvIQ3uL5QnWcRyb7z2xSTaclhqzPGKuqxD4RZ3ihjiPW2D+9pWjx6ek3AAAA//8DAOcF
+        +ytCAwAA
+    headers:
+      CF-RAY:
+      - 95986143ad1fde0e-EWR
+      Connection:
+      - keep-alive
+      Content-Encoding:
+      - gzip
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 03 Jul 2025 18:17:33 GMT
+      Server:
+      - cloudflare
+      Transfer-Encoding:
+      - chunked
+      X-Robots-Tag:
+      - none
+      anthropic-organization-id:
+      - 4257e925-ee99-4ee8-9c62-8e53716d5203
+      anthropic-ratelimit-input-tokens-limit:
+      - '20000000'
+      anthropic-ratelimit-input-tokens-remaining:
+      - '20000000'
+      anthropic-ratelimit-input-tokens-reset:
+      - '2025-07-03T18:17:30Z'
+      anthropic-ratelimit-output-tokens-limit:
+      - '2500000'
+      anthropic-ratelimit-output-tokens-remaining:
+      - '2500000'
+      anthropic-ratelimit-output-tokens-reset:
+      - '2025-07-03T18:17:33Z'
+      anthropic-ratelimit-tokens-limit:
+      - '22500000'
+      anthropic-ratelimit-tokens-remaining:
+      - '22500000'
+      anthropic-ratelimit-tokens-reset:
+      - '2025-07-03T18:17:30Z'
+      cf-cache-status:
+      - DYNAMIC
+      request-id:
+      - req_011CQkYXWEaYLtjyRLVfhAKc
+      strict-transport-security:
+      - max-age=31536000; includeSubDomains; preload
+      via:
+      - 1.1 google
+    status:
+      code: 200
+      message: OK
+version: 1