feat(metrics): add overall API usage prompt cache-read percentage

Adds OverallUsagePromptCacheReadPercentMetric, a token-volume-weighted
run-level percentage of input tokens served from prompt cache, derived
from the existing TotalUsagePromptCacheReadTokensMetric and
TotalUsagePromptTokensMetric. The two underlying token totals are
already exported per request, so a per-record variant is intentionally
omitted — averaging per-request percentages weights small and large
requests equally and is misleading.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Signed-off-by: Anthony Casagrande <acasagrande@nvidia.com>

Author: ajcasagrande

docs/metrics-reference.md

@@ -65,6 +65,7 @@ This document provides a comprehensive reference of all metrics available in AIP
     - [Total Usage Total Tokens](#total-usage-total-tokens)
     - [Total Usage Reasoning Tokens](#total-usage-reasoning-tokens)
     - [Total Usage Prompt Cache Read Tokens](#total-usage-prompt-cache-read-tokens)
+    - [Overall Usage Prompt Cache Read %](#overall-usage-prompt-cache-read-)
     - [Total Usage Prompt Cache Write Tokens](#total-usage-prompt-cache-write-tokens)
     - [Total Usage Prompt Cache Miss Tokens](#total-usage-prompt-cache-miss-tokens)
     - [Total Usage Prompt Audio Tokens](#total-usage-prompt-audio-tokens)
@@ -979,6 +980,24 @@ total_usage_prompt_cache_read_tokens = sum(r.usage_prompt_cache_read_tokens for
 
 ---
 
+### Overall Usage Prompt Cache Read %
+
+**Type:** [Derived Metric](#derived-metrics)
+
+Run-aggregate share of input tokens served from prompt cache, weighted by token volume. Computed from the run totals so a request with 10k prompt tokens contributes 100x as much weight as a request with 100 prompt tokens — the resulting number reflects the actual fraction of input tokens the API served from cache across the whole benchmark.
+
+**Formula:**
+```python
+overall_usage_prompt_cache_read_pct = (
+    total_usage_prompt_cache_read_tokens / total_usage_prompt_tokens
+) * 100
+```
+
+**Notes:**
+- No value is produced if `total_usage_prompt_tokens` is zero (e.g. all requests errored before reporting usage).
+
+---
+
 ### Total Usage Prompt Cache Write Tokens
 
 **Type:** [Derived Metric](#derived-metrics)

src/aiperf/metrics/types/usage_total_metrics.py

@@ -8,7 +8,11 @@
 """
 
 from aiperf.common.enums import MetricConsoleGroup
+from aiperf.common.enums.metric_enums import GenericMetricUnit, MetricFlags
+from aiperf.common.exceptions import NoMetricValue
+from aiperf.metrics import BaseDerivedMetric
 from aiperf.metrics.derived_sum_metric import DerivedSumMetric
+from aiperf.metrics.metric_dicts import MetricResultsDict
 from aiperf.metrics.types.usage_cache_metrics import (
     UsagePromptCacheMissTokensMetric,
     UsagePromptCacheReadTokensMetric,
@@ -311,3 +315,48 @@ class TotalUsagePromptAudioSecondsMetric(
     short_header = "Total Usage Prompt Audio Sec"
     console_group = MetricConsoleGroup.USAGE
     display_order = 2040
+
+
+class OverallUsagePromptCacheReadPercentMetric(BaseDerivedMetric[float]):
+    """
+    Overall (run-aggregate) prompt cache-read percentage across all requests.
+
+    Token-volume-weighted: divides the summed cache-read tokens by the summed
+    prompt tokens across the whole benchmark. This differs from the
+    per-request `UsagePromptCacheReadPercentMetric` aggregate stats (which
+    average per-request percentages, treating small and large requests
+    equally) — the overall figure reflects the actual share of input tokens
+    the API served from cache.
+
+    Formula:
+        Overall Usage Prompt Cache Read % =
+            (Total Usage Prompt Cache Read Tokens / Total Usage Prompt Tokens) * 100
+    """
+
+    tag = "overall_usage_prompt_cache_read_pct"
+    header = "Overall Usage Prompt Cache Read %"
+    short_header = "Overall Cache Read %"
+    short_header_hide_unit = True
+    unit = GenericMetricUnit.PERCENT
+    flags = MetricFlags.LARGER_IS_BETTER
+    console_group = MetricConsoleGroup.USAGE
+    display_order = 2012
+    required_metrics = {
+        TotalUsagePromptCacheReadTokensMetric.tag,
+        TotalUsagePromptTokensMetric.tag,
+    }
+
+    def _derive_value(
+        self,
+        metric_results: MetricResultsDict,
+    ) -> float:
+        total_cache_read = metric_results.get_or_raise(
+            TotalUsagePromptCacheReadTokensMetric
+        )
+        total_prompt = metric_results.get_or_raise(TotalUsagePromptTokensMetric)
+        if total_prompt == 0:
+            raise NoMetricValue(
+                "Total usage prompt tokens is zero, "
+                "cannot calculate overall cache-read percentage."
+            )
+        return (total_cache_read / total_prompt) * 100.0

tests/unit/metrics/test_usage_metrics.py

@@ -8,7 +8,7 @@
 from aiperf.common.models import ParsedResponse, ParsedResponseRecord, RequestRecord
 from aiperf.common.models.record_models import TextResponseData, TokenCounts
 from aiperf.common.models.usage_models import Usage
-from aiperf.metrics.metric_dicts import MetricRecordDict
+from aiperf.metrics.metric_dicts import MetricRecordDict, MetricResultsDict
 from aiperf.metrics.types.usage_cache_metrics import (
     UsagePromptCacheMissTokensMetric,
     UsagePromptCacheReadTokensMetric,
@@ -26,13 +26,15 @@
     UsageRejectedPredictionTokensMetric,
 )
 from aiperf.metrics.types.usage_total_metrics import (
+    OverallUsagePromptCacheReadPercentMetric,
     TotalUsageAcceptedPredictionTokensMetric,
     TotalUsageCompletionAudioTokensMetric,
     TotalUsagePromptAudioSecondsMetric,
     TotalUsagePromptAudioTokensMetric,
     TotalUsagePromptCacheMissTokensMetric,
     TotalUsagePromptCacheReadTokensMetric,
     TotalUsagePromptCacheWriteTokensMetric,
+    TotalUsagePromptTokensMetric,
     TotalUsageReasoningTokensMetric,
     TotalUsageRejectedPredictionTokensMetric,
     TotalUsageToolUsePromptTokensMetric,
@@ -447,6 +449,41 @@ def test_metadata(self):
         )
 
 
+class TestOverallUsagePromptCacheReadPercentMetric:
+    """Tests for OverallUsagePromptCacheReadPercentMetric (run-aggregate cache %)."""
+
+    def test_basic_overall_percentage(self):
+        metric_results = MetricResultsDict()
+        metric_results[TotalUsagePromptCacheReadTokensMetric.tag] = 250
+        metric_results[TotalUsagePromptTokensMetric.tag] = 1000
+        result = OverallUsagePromptCacheReadPercentMetric().derive_value(metric_results)
+        assert result == pytest.approx(25.0, rel=1e-9)
+
+    def test_zero_total_prompt_tokens_raises(self):
+        metric_results = MetricResultsDict()
+        metric_results[TotalUsagePromptCacheReadTokensMetric.tag] = 0
+        metric_results[TotalUsagePromptTokensMetric.tag] = 0
+        with pytest.raises(NoMetricValue):
+            OverallUsagePromptCacheReadPercentMetric().derive_value(metric_results)
+
+    def test_metadata(self):
+        assert (
+            OverallUsagePromptCacheReadPercentMetric.tag
+            == "overall_usage_prompt_cache_read_pct"
+        )
+        assert (
+            OverallUsagePromptCacheReadPercentMetric.console_group
+            == MetricConsoleGroup.USAGE
+        )
+        assert OverallUsagePromptCacheReadPercentMetric.has_flags(
+            MetricFlags.LARGER_IS_BETTER
+        )
+        assert OverallUsagePromptCacheReadPercentMetric.required_metrics == {
+            TotalUsagePromptCacheReadTokensMetric.tag,
+            TotalUsagePromptTokensMetric.tag,
+        }
+
+
 class TestUsageToolUsePromptTokensMetric:
     """Tests for UsageToolUsePromptTokensMetric (Gemini-specific)."""