UI cache hit rate shows zero with raw metrics

Applies to:

Plan -
Deployment -

Summary

The UI can show a 0% cache hit rate when custom logging includes provider cache fields but omits the normalized metrics Braintrust expects. Map the provider fields to metrics.prompt_cached_tokens and metrics.prompt_cache_creation_tokens.

What is happening

Braintrust integrations can normalize provider usage fields automatically. With custom logging, raw fields such as cache_read_input_tokens and cache_creation_input_tokens do not populate the normalized metrics automatically. Log these metrics on the LLM span:

prompt_tokens, including uncached input, cache reads, and cache creation tokens.
completion_tokens.
prompt_cached_tokens for cache reads.
prompt_cache_creation_tokens for cache writes.

The UI calculates the cache hit rate as prompt_cached_tokens / prompt_tokens. If prompt_cached_tokens is absent, cached reads are treated as zero. The cache hit label also requires completion_tokens to be reported. This guide assumes the span already reports normalized prompt_tokens and completion_tokens. If your custom logging only reports provider-specific input and output token fields, normalize those fields too. The normalized cache metrics also affect cache token breakdowns and cache-aware cost calculations.

Fix or suggestion

Option 1: add normalized metrics

Map the provider usage fields to the normalized metrics when you log the span. For an Anthropic-style usage response:

const usage = response.usage;
const cachedReadTokens = usage.cache_read_input_tokens ?? 0;
const cacheCreationTokens = usage.cache_creation_input_tokens ?? 0;
const promptTokens =
  usage.input_tokens + cachedReadTokens + cacheCreationTokens;

span.log({
  metrics: {
    prompt_tokens: promptTokens,
    completion_tokens: usage.output_tokens,
    prompt_cached_tokens: cachedReadTokens,
    prompt_cache_creation_tokens: cacheCreationTokens,
  },
});

The resulting span metrics use the following shape:

{
  "prompt_tokens": 1000,
  "completion_tokens": 200,
  "prompt_cached_tokens": 600,
  "prompt_cache_creation_tokens": 100
}

prompt_tokens includes all input tokens. In this example, the cache hit rate is 60% because 600 of 1,000 prompt tokens were cache reads.

Option 2: use an integration or SDK wrapper

If one is available for your provider, use a Braintrust integration or SDK wrapper that normalizes the usage response. For more information about logging token metrics for a custom client, see Wrap a custom LLM client.

How to confirm it worked

Export or view the raw span JSON for the affected span and confirm metrics includes:
- prompt_tokens.
- completion_tokens.
- prompt_cached_tokens.
- prompt_cache_creation_tokens.
Run a SQL query to inspect the normalized metrics:

SELECT
  created,
  id,
  span_id,
  metrics.prompt_tokens,
  metrics.cache_read_input_tokens,
  metrics.cache_creation_input_tokens,
  metrics.prompt_cached_tokens,
  metrics.prompt_cache_creation_tokens
FROM project_logs('<PROJECT_ID>', shape => 'spans')
WHERE created >= now() - INTERVAL 1 DAY
  AND span_attributes.type = 'llm'
ORDER BY created DESC
LIMIT 50

If the raw cache fields contain values but the normalized cache metrics are null or zero, update your custom logging.

Verify that the UI displays the expected cache hit rate.

Notes

This guide applies to custom instrumentation or provider-specific fields that have not been normalized.

​Summary

​What is happening

​Fix or suggestion

​Option 1: add normalized metrics

​Option 2: use an integration or SDK wrapper

​How to confirm it worked

​Notes

Summary

What is happening

Fix or suggestion

Option 1: add normalized metrics

Option 2: use an integration or SDK wrapper

How to confirm it worked

Notes