CDN Cache Key Design That Works

Cache key design determines hit rate. The principles, the pitfalls, and the metrics that prove cache health.

Design principles

The cache key is what determines whether two requests share a cached response. Bad cache key design produces fragmented caches: many unique keys for similar content; low hit rates; the cache providing no value. Good cache key design produces high hit rates without serving wrong content.

What good cache key design looks like:

• Strip query params that do not affect content.: Many query parameters are irrelevant to the response: tracking params (utm_source, utm_campaign), session IDs in URLs, cache-busting timestamps that are different per visit. The cache key should ignore these.
• Tracking params especially.: The most common cache fragmentation source is tracking parameters. Each ad campaign, each referral source produces unique URLs with the same content. Stripping these consolidates the cache.
• Normalize headers: case-insensitive.: HTTP headers are case-insensitive by spec. Cache keys should normalize: Cookie, COOKIE, and cookie all produce the same key. Without normalization, header case variations fragment the cache.
• Sorted.: When headers are part of the cache key, they should be sorted. Different orderings of the same headers should produce the same key. Without sorting, every reorder creates a unique key.
• Vary header used correctly.: The Vary header signals that responses differ based on certain request headers. Using Vary correctly tells the CDN what to include in the cache key; using it incorrectly produces wasted cache entries or wrong responses.

The principles are simple. Applying them consistently produces cache that actually caches.

Pitfalls

Specific recurring mistakes produce predictably bad cache outcomes. The team that recognizes these patterns avoids the most common cache key design errors.

• Including auth headers in cache key.: Authentication tokens are unique per user per session. Including them in the cache key produces unique cache entries per session; the cache fragments completely; the hit rate is essentially zero.
• Cache fragmentation; effectively no caching.: When the cache key has high cardinality unrelated to the content, the cache becomes a per-request store. The system pays for cache infrastructure without getting cache benefits.
• Including user-specific headers.: User-Agent, X-Forwarded-For, and similar headers vary per user. Including them in the cache key fragments by user. Each user gets their own cache slot for the same content.
• Each user gets their own cache slot.: The pattern is the same as cache by user ID: high cardinality, no sharing, no caching value. The fix is to exclude these headers from the cache key.
• Whitelist what matters.: Default behavior should be to exclude headers and parameters from the cache key; explicitly include only what genuinely varies content. The whitelist approach prevents accidental fragmentation.

The pitfalls are predictable; the fixes are well-known. The discipline is reviewing cache key configuration with care.

Metrics

The metrics tell the team whether the cache key design is producing the expected behavior. Bad metrics indicate fragmentation or other design issues; good metrics confirm the cache is working.

• Cache hit rate per route.: Each route's hit rate is tracked separately. Static content routes should have high hit rates; dynamic content routes have lower. The dashboard surfaces routes that are not performing as expected.
• Below 80% is suspect for static content.: Static content (CSS, JS, images, fonts) should cache at 90% or higher. Below 80% indicates a problem: cache key fragmentation, TTL too short, content actually varying when it should not.
• Cache key cardinality.: The number of unique cache keys per route is a key indicator. Cardinality should be roughly equal to the number of distinct content variations. Higher cardinality indicates fragmentation.
• Growing without traffic growing means key design has a leak.: If unique cache keys grow faster than traffic, something in the key includes per-request randomness. The leak is the design issue to find and fix.
• Hit rate by visitor type.: First-time visitors and returning visitors might see different hit rates. Returning visitors benefit from caches warmed by other returning visitors; first-time visitors hit the cache that other first-time visitors warmed. The patterns inform cache strategy.

CDN cache key design is one of those engineering disciplines that pays off proportionally to traffic volume. Nova AI Ops integrates with CDN telemetry, surfaces cardinality and hit rate trends, and produces the per-route diagnosis that the team uses to identify and fix cache key design issues.