Deep Dive into Nginx proxy_cache_path: Understanding keys_zone and Cache Expiration Conflicts


2 views

The keys_zone=myCache:8m parameter in your Nginx configuration serves two critical purposes:

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=myCache:8m max_size=100m inactive=1h;

1. Shared Memory Zone: myCache is the name of the shared memory zone where Nginx stores:

  • Active cache keys
  • Metadata about cached responses
  • Cache state information

2. Memory Allocation: The 8m specifies 8 megabytes of shared memory allocated for storing this metadata. A general rule is to allocate about 1MB per 8,000 cache keys.

When you have conflicting expiration settings:

proxy_cache_valid 200 302 12h;
proxy_cache_valid 404 302 1h;
proxy_cache_path ... inactive=1h;

Nginx follows these rules:

1. inactive: Controls when a cache entry is removed from storage if it hasn't been accessed

2. proxy_cache_valid: Determines when a cached response is considered stale and needs refreshing

Key behavior: The inactive timer is independent of the proxy_cache_valid timer. A cached item will be:

  • Served from cache if valid (per proxy_cache_valid)
  • Deleted from disk if inactive (per inactive) even if still valid

Consider this configuration:

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=myCache:8m max_size=100m inactive=30m;

server {
    location / {
        proxy_cache myCache;
        proxy_cache_valid 200 1h;
        proxy_cache_valid 404 5m;
        proxy_pass http://backend;
    }
}

Behavior for a 200 response:

  • Will be served from cache for 1 hour (per proxy_cache_valid)
  • Will be deleted after 30 minutes of inactivity (per inactive)
  • If accessed at minute 29, the inactive timer resets

1. Memory Allocation: For high-traffic sites, monitor cache keys with nginx -T and adjust keys_zone size accordingly.

2. Expiration Strategy:

  • Set inactive based on your content update frequency
  • Use proxy_cache_valid to control freshness requirements
  • For static assets, consider longer periods: proxy_cache_valid 200 302 12h;

When configuring proxy_cache_path, the keys_zone=myCache:8m portion serves two critical functions:

proxy_cache_path /var/cache/nginx 
    levels=1:2 
    keys_zone=myCache:8m 
    max_size=100m 
    inactive=1h;
  • Shared Memory Allocation: The 8m allocates 8MB of shared memory for storing cache keys and metadata. This memory is shared across all worker processes.
  • Performance Impact: Each cache entry requires about 128 bytes in the keys_zone. With 8MB, you can store approximately 65,536 cache keys (8*1024*1024/128).

When both proxy_cache_valid and inactive are specified, Nginx follows these rules:

  1. Freshness Check: Nginx first checks if the cached response is still fresh according to proxy_cache_valid
  2. Activity Check: If not accessed within the inactive period, the item is removed regardless of freshness

Practical example with conflicting values:

proxy_cache_valid 200 302 12h;
proxy_cache_valid 404 302 1h;
proxy_cache_path ... inactive=1h;

In this scenario:

  • A successful response (200) will be removed after 1 hour of inactivity, even though it's valid for 12 hours
  • A 404 response will be removed after 1 hour due to both validity and inactivity settings matching

Here's a complete configuration demonstrating best practices:

http {
    proxy_cache_path /data/nginx/cache 
        levels=1:2 
        keys_zone=STATIC:10m 
        inactive=24h 
        max_size=1g 
        use_temp_path=off;

    server {
        location / {
            proxy_cache STATIC;
            proxy_cache_valid 200 302 12h;
            proxy_cache_valid 404 1h;
            proxy_cache_use_stale error timeout updating;
            proxy_pass http://backend;
        }
    }
}

The keys_zone size significantly impacts performance:

Cache Size Recommended keys_zone
1GB 10-20MB
10GB 80-100MB
100GB 800MB-1GB

Remember to monitor cache hit ratios and adjust these values accordingly:

nginx -T 2>&1 | grep -A10 proxy_cache_path
tail -f /var/log/nginx/cache.log | grep -E 'KEY:|HIT:|MISS:'