feat: expose cache metrics

src/strands/event_loop/streaming.py

@@ -275,7 +275,7 @@ async def process_stream(
     }
     state["content"] = state["message"]["content"]
 
-    usage: Usage = Usage(inputTokens=0, outputTokens=0, totalTokens=0)
+    usage: Usage = Usage(inputTokens=0, outputTokens=0, totalTokens=0, cacheReadInputTokens=0, cacheWriteInputTokens=0)
     metrics: Metrics = Metrics(latencyMs=0)
 
     async for chunk in chunks:

src/strands/models/anthropic.py

@@ -331,6 +331,8 @@ def format_chunk(self, event: dict[str, Any]) -> StreamEvent:
                             "inputTokens": usage["input_tokens"],
                             "outputTokens": usage["output_tokens"],
                             "totalTokens": usage["input_tokens"] + usage["output_tokens"],
+                            "cacheReadInputTokens": usage.get("cache_read_input_tokens", 0),
+                            "cacheWriteInputTokens": usage.get("cache_creation_input_tokens", 0),
                         },
                         "metrics": {
                             "latencyMs": 0,  # TODO

src/strands/models/litellm.py

@@ -177,7 +177,15 @@ async def stream(
         async for event in response:
             _ = event
 
-        yield self.format_chunk({"chunk_type": "metadata", "data": event.usage})
+        usage = event.usage
+        cache_read = max(
+            getattr(usage, "cache_read_input_tokens", 0),
+            getattr(getattr(usage, "prompt_tokens_details", {}), "cached_tokens", 0),
+        )
+
+        usage.prompt_tokens_details.cached_tokens = cache_read
+
+        yield self.format_chunk({"chunk_type": "metadata", "data": usage})
 
         logger.debug("finished streaming response from model")
 

src/strands/models/llamaapi.py

@@ -308,6 +308,9 @@ def format_chunk(self, event: dict[str, Any]) -> StreamEvent:
                     inputTokens=usage["inputTokens"],
                     outputTokens=usage["outputTokens"],
                     totalTokens=usage["totalTokens"],
+                    # TODO does not seem to support caching as of July 2025
+                    cacheWriteInputTokens=0,
+                    cacheReadInputTokens=0,
                 )
                 return {
                     "metadata": {

src/strands/models/mistral.py

@@ -338,6 +338,9 @@ def format_chunk(self, event: dict[str, Any]) -> StreamEvent:
                             "inputTokens": usage.prompt_tokens,
                             "outputTokens": usage.completion_tokens,
                             "totalTokens": usage.total_tokens,
+                            # TODO does not seem to support caching as of July 2025
+                            "cacheWriteInputTokens": 0,
+                            "cacheReadInputTokens": 0,
                         },
                         "metrics": {
                             "latencyMs": event.get("latency_ms", 0),

src/strands/models/ollama.py

@@ -268,6 +268,9 @@ def format_chunk(self, event: dict[str, Any]) -> StreamEvent:
                             "inputTokens": event["data"].eval_count,
                             "outputTokens": event["data"].prompt_eval_count,
                             "totalTokens": event["data"].eval_count + event["data"].prompt_eval_count,
+                            # TODO add cache metrics
+                            "cacheWriteInputTokens": 0,
+                            "cacheReadInputTokens": 0,
                         },
                         "metrics": {
                             "latencyMs": event["data"].total_duration / 1e6,

src/strands/models/openai.py

@@ -310,6 +310,8 @@ def format_chunk(self, event: dict[str, Any]) -> StreamEvent:
                             "inputTokens": event["data"].prompt_tokens,
                             "outputTokens": event["data"].completion_tokens,
                             "totalTokens": event["data"].total_tokens,
+                            "cacheReadInputTokens": event["data"].prompt_tokens_details.cached_tokens,
+                            "cacheWriteInputTokens": 0,  # OpenAI does not return cache write information
                         },
                         "metrics": {
                             "latencyMs": 0,  # TODO

src/strands/telemetry/metrics.py

@@ -168,7 +168,11 @@ class EventLoopMetrics:
     tool_metrics: Dict[str, ToolMetrics] = field(default_factory=dict)
     cycle_durations: List[float] = field(default_factory=list)
     traces: List[Trace] = field(default_factory=list)
-    accumulated_usage: Usage = field(default_factory=lambda: Usage(inputTokens=0, outputTokens=0, totalTokens=0))
+    accumulated_usage: Usage = field(
+        default_factory=lambda: Usage(
+            inputTokens=0, outputTokens=0, totalTokens=0, cacheReadInputTokens=0, cacheWriteInputTokens=0
+        )
+    )
     accumulated_metrics: Metrics = field(default_factory=lambda: Metrics(latencyMs=0))
 
     @property
@@ -263,6 +267,8 @@ def update_usage(self, usage: Usage) -> None:
         self.accumulated_usage["inputTokens"] += usage["inputTokens"]
         self.accumulated_usage["outputTokens"] += usage["outputTokens"]
         self.accumulated_usage["totalTokens"] += usage["totalTokens"]
+        self.accumulated_usage["cacheReadInputTokens"] += usage.get("cacheReadInputTokens", 0)
+        self.accumulated_usage["cacheWriteInputTokens"] += usage.get("cacheWriteInputTokens", 0)
 
     def update_metrics(self, metrics: Metrics) -> None:
         """Update the accumulated performance metrics with new metrics data.
@@ -320,15 +326,18 @@ def _metrics_summary_to_lines(event_loop_metrics: EventLoopMetrics, allowed_name
         An iterable of formatted text lines representing the metrics.
     """
     summary = event_loop_metrics.get_summary()
+    accumulated_usage = summary["accumulated_usage"]
     yield "Event Loop Metrics Summary:"
     yield (
         f"├─ Cycles: total={summary['total_cycles']}, avg_time={summary['average_cycle_time']:.3f}s, "
         f"total_time={summary['total_duration']:.3f}s"
     )
     yield (
-        f"├─ Tokens: in={summary['accumulated_usage']['inputTokens']}, "
-        f"out={summary['accumulated_usage']['outputTokens']}, "
-        f"total={summary['accumulated_usage']['totalTokens']}"
+        f"├─ Tokens: in={accumulated_usage['inputTokens']}"
+        f" (cache_write={accumulated_usage.get('cacheWriteInputTokens', 0)}), "
+        f"out={accumulated_usage['outputTokens']}, "
+        f"total={accumulated_usage['totalTokens']}"
+        f" (cache_read={accumulated_usage.get('cacheReadInputTokens', 0)})"
     )
     yield f"├─ Bedrock Latency: {summary['accumulated_metrics']['latencyMs']}ms"
 
@@ -421,6 +430,8 @@ class MetricsClient:
     event_loop_latency: Histogram
     event_loop_input_tokens: Histogram
     event_loop_output_tokens: Histogram
+    event_loop_input_tokens_cache_read: Histogram
+    event_loop_input_tokens_cache_write: Histogram
 
     tool_call_count: Counter
     tool_success_count: Counter
@@ -474,3 +485,9 @@ def create_instruments(self) -> None:
         self.event_loop_output_tokens = self.meter.create_histogram(
             name=constants.STRANDS_EVENT_LOOP_OUTPUT_TOKENS, unit="token"
         )
+        self.event_loop_input_tokens_cache_read = self.meter.create_histogram(
+            name=constants.STRANDS_EVENT_LOOP_INPUT_TOKEN_CACHE_READ, unit="token"
+        )
+        self.event_loop_input_tokens_cache_write = self.meter.create_histogram(
+            name=constants.STRANDS_EVENT_LOOP_INPUT_TOKENS_CACHE_WRITE, unit="token"
+        )

src/strands/telemetry/metrics_constants.py

@@ -13,3 +13,5 @@
 STRANDS_EVENT_LOOP_CYCLE_DURATION = "strands.event_loop.cycle_duration"
 STRANDS_EVENT_LOOP_INPUT_TOKENS = "strands.event_loop.input.tokens"
 STRANDS_EVENT_LOOP_OUTPUT_TOKENS = "strands.event_loop.output.tokens"
+STRANDS_EVENT_LOOP_INPUT_TOKEN_CACHE_READ = "strands.event_loop.input.tokens.cache.read"
+STRANDS_EVENT_LOOP_INPUT_TOKENS_CACHE_WRITE = "strands.event_loop.input.tokens.cache.write"

src/strands/telemetry/tracer.py

@@ -259,6 +259,8 @@ def end_model_invoke_span(
         attributes: Dict[str, AttributeValue] = {
             "gen_ai.usage.prompt_tokens": usage["inputTokens"],
             "gen_ai.usage.input_tokens": usage["inputTokens"],
+            "gen_ai.usage.cache_read_input_tokens": usage.get("cacheReadInputTokens", 0),
+            "gen_ai.usage.cache_write_input_tokens": usage.get("cacheWriteInputTokens", 0),
             "gen_ai.usage.completion_tokens": usage["outputTokens"],
             "gen_ai.usage.output_tokens": usage["outputTokens"],
             "gen_ai.usage.total_tokens": usage["totalTokens"],
@@ -492,6 +494,8 @@ def end_agent_span(
                         "gen_ai.usage.input_tokens": accumulated_usage["inputTokens"],
                         "gen_ai.usage.output_tokens": accumulated_usage["outputTokens"],
                         "gen_ai.usage.total_tokens": accumulated_usage["totalTokens"],
+                        "gen_ai.usage.cache_read_input_tokens": accumulated_usage.get("cacheReadInputTokens", 0),
+                        "gen_ai.usage.cache_write_input_tokens": accumulated_usage.get("cacheWriteInputTokens", 0),
                     }
                 )
 

src/strands/types/event_loop.py

@@ -5,18 +5,22 @@
 from typing_extensions import TypedDict
 
 
-class Usage(TypedDict):
+class Usage(TypedDict, total=False):
     """Token usage information for model interactions.
 
     Attributes:
         inputTokens: Number of tokens sent in the request to the model..
         outputTokens: Number of tokens that the model generated for the request.
         totalTokens: Total number of tokens (input + output).
+        cacheReadInputTokens: Number of tokens read from cache.
+        cacheWriteInputTokens: Number of tokens written to cache.
     """
 
     inputTokens: int
     outputTokens: int
     totalTokens: int
+    cacheReadInputTokens: int
+    cacheWriteInputTokens: int
 
 
 class Metrics(TypedDict):

tests/strands/event_loop/test_streaming.py

@@ -250,7 +250,13 @@ def test_handle_message_stop():
 
 def test_extract_usage_metrics():
     event = {
-        "usage": {"inputTokens": 0, "outputTokens": 0, "totalTokens": 0},
+        "usage": {
+            "inputTokens": 0,
+            "outputTokens": 0,
+            "totalTokens": 0,
+            "cacheReadInputTokens": 0,
+            "cacheWriteInputTokens": 0,
+        },
         "metrics": {"latencyMs": 0},
     }
 
@@ -279,7 +285,13 @@ def test_extract_usage_metrics():
                 },
                 {
                     "metadata": {
-                        "usage": {"inputTokens": 1, "outputTokens": 1, "totalTokens": 1},
+                        "usage": {
+                            "inputTokens": 1,
+                            "outputTokens": 1,
+                            "totalTokens": 1,
+                            "cacheReadInputTokens": 1,
+                            "cacheWriteInputTokens": 1,
+                        },
                         "metrics": {"latencyMs": 1},
                     }
                 },
@@ -364,6 +376,8 @@ def test_extract_usage_metrics():
                                     "inputTokens": 1,
                                     "outputTokens": 1,
                                     "totalTokens": 1,
+                                    "cacheReadInputTokens": 1,
+                                    "cacheWriteInputTokens": 1,
                                 },
                             },
                         },
@@ -376,7 +390,13 @@ def test_extract_usage_metrics():
                             "role": "assistant",
                             "content": [{"toolUse": {"toolUseId": "123", "name": "test", "input": {"key": "value"}}}],
                         },
-                        {"inputTokens": 1, "outputTokens": 1, "totalTokens": 1},
+                        {
+                            "inputTokens": 1,
+                            "outputTokens": 1,
+                            "totalTokens": 1,
+                            "cacheReadInputTokens": 1,
+                            "cacheWriteInputTokens": 1,
+                        },
                         {"latencyMs": 1},
                     )
                 },
@@ -398,7 +418,13 @@ def test_extract_usage_metrics():
                             "role": "assistant",
                             "content": [],
                         },
-                        {"inputTokens": 0, "outputTokens": 0, "totalTokens": 0},
+                        {
+                            "inputTokens": 0,
+                            "outputTokens": 0,
+                            "totalTokens": 0,
+                            "cacheReadInputTokens": 0,
+                            "cacheWriteInputTokens": 0,
+                        },
                         {"latencyMs": 0},
                     ),
                 },
@@ -426,7 +452,13 @@ def test_extract_usage_metrics():
                 },
                 {
                     "metadata": {
-                        "usage": {"inputTokens": 1, "outputTokens": 1, "totalTokens": 1},
+                        "usage": {
+                            "inputTokens": 1,
+                            "outputTokens": 1,
+                            "totalTokens": 1,
+                            "cacheReadInputTokens": 1,
+                            "cacheWriteInputTokens": 1,
+                        },
                         "metrics": {"latencyMs": 1},
                     }
                 },
@@ -506,6 +538,8 @@ def test_extract_usage_metrics():
                                     "inputTokens": 1,
                                     "outputTokens": 1,
                                     "totalTokens": 1,
+                                    "cacheReadInputTokens": 1,
+                                    "cacheWriteInputTokens": 1,
                                 },
                             },
                         },
@@ -518,7 +552,13 @@ def test_extract_usage_metrics():
                             "role": "assistant",
                             "content": [{"text": "REDACTED."}],
                         },
-                        {"inputTokens": 1, "outputTokens": 1, "totalTokens": 1},
+                        {
+                            "inputTokens": 1,
+                            "outputTokens": 1,
+                            "totalTokens": 1,
+                            "cacheReadInputTokens": 1,
+                            "cacheWriteInputTokens": 1,
+                        },
                         {"latencyMs": 1},
                     ),
                 },
@@ -584,7 +624,13 @@ async def test_stream_messages(agenerator, alist):
             "stop": (
                 "end_turn",
                 {"role": "assistant", "content": [{"text": "test"}]},
-                {"inputTokens": 0, "outputTokens": 0, "totalTokens": 0},
+                {
+                    "inputTokens": 0,
+                    "outputTokens": 0,
+                    "totalTokens": 0,
+                    "cacheReadInputTokens": 0,
+                    "cacheWriteInputTokens": 0,
+                },
                 {"latencyMs": 0},
             )
         },

tests/strands/models/test_anthropic.py

@@ -597,7 +597,12 @@ def test_format_chunk_message_stop(model):
 def test_format_chunk_metadata(model):
     event = {
         "type": "metadata",
-        "usage": {"input_tokens": 1, "output_tokens": 2},
+        "usage": {
+            "input_tokens": 1,
+            "output_tokens": 2,
+            "cache_read_input_tokens": 4,
+            "cache_creation_input_tokens": 5,
+        },
     }
 
     tru_chunk = model.format_chunk(event)
@@ -607,6 +612,8 @@ def test_format_chunk_metadata(model):
                 "inputTokens": 1,
                 "outputTokens": 2,
                 "totalTokens": 3,
+                "cacheReadInputTokens": 4,
+                "cacheWriteInputTokens": 5,
             },
             "metrics": {
                 "latencyMs": 0,
@@ -656,7 +663,18 @@ async def test_stream(anthropic_client, model, agenerator, alist):
     tru_events = await alist(response)
     exp_events = [
         {"messageStart": {"role": "assistant"}},
-        {"metadata": {"usage": {"inputTokens": 1, "outputTokens": 2, "totalTokens": 3}, "metrics": {"latencyMs": 0}}},
+        {
+            "metadata": {
+                "usage": {
+                    "inputTokens": 1,
+                    "outputTokens": 2,
+                    "totalTokens": 3,
+                    "cacheReadInputTokens": 0,
+                    "cacheWriteInputTokens": 0,
+                },
+                "metrics": {"latencyMs": 0},
+            }
+        },
     ]
 
     assert tru_events == exp_events