MCP Cache Testing Guide

Comprehensive guide for testing, debugging, and optimizing cache behavior on Azion Platform using MCP tools and cURL commands.

View as Markdown

This guide provides methods for testing, debugging, and optimizing cache behavior on the Azion Platform using MCP tools and direct cURL commands.

Cache debug headers

Enable cache debug headers by including Pragma: azion-debug-cache in your requests. This returns detailed cache information.

Debug headers reference

HeaderDescriptionExample Values
X-CacheCache status of the requestHIT, MISS, EXPIRED, UPDATING, STALE
X-Cache-KeyThe cache key used to store/retrieve the object/index.html@@cookie_name=value
X-Cache-FileMD5 hash of the cache keya1b2c3d4e5f6789...
X-Cache-SinceUnix timestamp when object was cached1640995200
X-Cache-ExpireUnix timestamp when cache expires1640995800
X-Cache-Expire-InSeconds remaining until cache expires600
X-Cache-ValidConfigured TTL in seconds3600
X-Cache-ConfigAzion configuration ID1595368520
X-Cache-IDUnique identifier for this request#AECFE66100000000C947B9B3...

Basic cache testing with cURL

Test Azion domain

Always start by testing the .map.azionedge.net domain directly:

# Basic cache status check (headers only)
curl -H "Pragma: azion-debug-cache" -I "https://xxxxxx.map.azionedge.net/"
# Full response with cache headers
curl -H "Pragma: azion-debug-cache" -v "https://xxxxxx.map.azionedge.net/"

Test static assets

# Test different asset types
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/style.css"
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/script.js"
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/image.jpg"
# Test with query parameters
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/image.jpg?version=123"
# Test with cookies
curl -H "Pragma: azion-debug-cache" -H "Cookie: session_id=abc123" -I "https://yourdomain.com/"

Test production domain via Azion

# Get the Azion IP from your domain
AZION_IP=(dig +short @8.8.8.8 xxxxxx.map.azionedge.net | head -1)
# Test using production hostname via Host header override
curl -H "Host: yourproductiondomain.com" -H "Pragma: azion-debug-cache" -I "http://$AZION_IP/"
# Or use curl's resolve feature (cleaner)
curl --resolve "yourproductiondomain.com:443:$AZION_IP" -H "Pragma: azion-debug-cache" -I "https://yourproductiondomain.com/"

Cache key testing

Query parameter variations

# Test cache key variations with query parameters
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/api/data?city=SP&user=john"
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/api/data?user=john&city=SP" # Different order
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/api/data?city=SP&user=john&utm_source=google" # Extra param
# Compare X-Cache-Key headers to understand:
# - If query string sorting is enabled
# - Which parameters affect the cache key
# - If tracking parameters are ignored
# Test cookie-based cache variations
curl -H "Pragma: azion-debug-cache" -H "Cookie: language=en" -I "https://yourdomain.com/"
curl -H "Pragma: azion-debug-cache" -H "Cookie: language=pt" -I "https://yourdomain.com/"
curl -H "Pragma: azion-debug-cache" -H "Cookie: language=en;session_id=123" -I "https://yourdomain.com/"
# Extract and compare cache keys
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/" 2>/dev/null | grep "X-Cache-Key"

Cache performance testing

Consistent location testing

Fix the IP to ensure both requests go to the same server:

# Get Azion edge IP
AZION_IP=(dig +short @8.8.8.8 xxxxxx.map.azionedge.net | head -1)
echo "Testing with Azion IP: $AZION_IP"
# First request (should be MISS) - with TTFB measurement
echo "=== FIRST REQUEST (MISS) ==="
curl --resolve "xxxxxx.map.azionedge.net:443:$AZION_IP" \
-H "Pragma: azion-debug-cache" \
-w "TTFB: %{time_starttransfer}s | Total: %{time_total}s\n" \
-I "https://xxxxxx.map.azionedge.net/style.css"
# Second request (should be HIT) - with TTFB measurement
echo "=== SECOND REQUEST (HIT) ==="
curl --resolve "xxxxxx.map.azionedge.net:443:$AZION_IP" \
-H "Pragma: azion-debug-cache" \
-w "TTFB: %{time_starttransfer}s | Total: %{time_total}s\n" \
-I "https://xxxxxx.map.azionedge.net/style.css"

The TTFB should be significantly lower on the second request when content is served from cache.

Provider comparison

# Get edge IP for testing
AZION_IP=(dig +short @8.8.8.8 xxxxxx.map.azionedge.net | head -1)
# Test Azion performance
echo "=== AZION PERFORMANCE ==="
curl --resolve "yourproductiondomain.com:443:$AZION_IP" \
-H "Pragma: azion-debug-cache" \
-w "DNS: %{time_namelookup}s | Connect: %{time_connect}s | TTFB: %{time_starttransfer}s | Total: %{time_total}s\n" \
-s -o /dev/null "https://yourproductiondomain.com/"
# Test current provider (for comparison)
echo "=== CURRENT PROVIDER PERFORMANCE ==="
curl -w "DNS: %{time_namelookup}s | Connect: %{time_connect}s | TTFB: %{time_starttransfer}s | Total: %{time_total}s\n" \
-s -o /dev/null "https://yourproductiondomain.com/"

Network information

Get network information including your IP, resolver, and location:

curl -L http://netinfo.azion.com/json

This provides:

  • Your public IP (useful for searching in Azion logs)
  • DNS resolver being used
  • Azion location serving the request
  • Network health status

Real-Time Events monitoring

Using Azion CLI

# View HTTP logs with cache information
azion logs http --tail --pretty
# View specific application logs
azion logs http --application-id YOUR_APP_ID --limit 100

Key log variables for cache analysis

VariableDescriptionExample
Cache KeyCache key used/index.html@@cookie_name=value
Cache TTLCache duration in seconds31536000
Upstream Cache StatusCache statusHIT, MISS, BYPASS, EXPIRED, STALE
Upstream Response TimeOrigin response time- for cached content
Bytes SentTotal bytes delivered1024
Request TimeTotal processing time0.001

GraphQL queries for cache analysis

Use MCP’s create_graphql_query tool or run directly:

query CacheAnalysis {
httpMetrics(
limit: 1000,
filter: {
tsRange: { begin: "2024-01-01T00:00:00", end: "2024-01-01T23:59:59" }
domain: "yourdomain.com"
}
) {
cacheStatus
bytesSent
requestTime
status
requestMethod
uri
}
}

Key performance indicators

  • Cache Hit Ratio: Should be >80% for static content
  • Edge Offload: Percentage of requests served from cache vs origin
  • Origin Response Time: Compare cached vs non-cached requests
  • Bandwidth Savings: Bytes served from cache vs origin

Cache configuration via CLI

Create cache settings

# Static assets cache
azion create cache-setting \
--application-id YOUR_APP_ID \
--name "Static Assets" \
--browser-cache-settings "honor" \
--cdn-cache-settings "override" \
--cdn-cache-settings-maximum-ttl 2592000 \
--cache-by-query-string "ignore" \
--cache-by-cookies "ignore" \
--enable-caching-for-post "false"
# Dynamic content cache
azion create cache-setting \
--application-id YOUR_APP_ID \
--name "API Cache" \
--browser-cache-settings "honor" \
--cdn-cache-settings "override" \
--cdn-cache-settings-maximum-ttl 300 \
--cache-by-query-string "all" \
--cache-by-cookies "whitelist" \
--cookie-names "session_id,language"

Apply via Rules Engine

# Cache static assets
azion create rule \
--application-id YOUR_APP_ID \
--name "Cache Static Assets" \
--criteria "uri matches \.(jpg|jpeg|png|gif|svg|css|js|woff|woff2|ttf|ico)$" \
--behavior "set_cache_policy" \
--value "Static Assets"
# Bypass cache for authenticated users
azion create rule \
--application-id YOUR_APP_ID \
--name "Bypass Auth Users" \
--criteria "cookie exists session_id" \
--behavior "bypass_cache" \
--value "true"

Cache optimization strategies

Query string strategy

StrategyUse caseConfiguration
Ignore allStatic assets--cache-by-query-string "ignore"
WhitelistAPIs with functional params--cache-by-query-string "whitelist" with specific params
BlacklistIgnore tracking params--cache-by-query-string "blacklist" with utm_*, fbclid, gclid
StrategyUse caseConfiguration
Ignore allStatic content--cache-by-cookies "ignore"
WhitelistPersonalized content--cache-by-cookies "whitelist" with language, currency

TTL strategy by content type

Content TypeRecommended TTLExample
Static assets30 days2592000 seconds
Semi-static1 hour3600 seconds
Dynamic5 minutes300 seconds
Real-time30 seconds30 seconds

Automated cache health check script

#!/bin/bash
# cache-health-check.sh
EDGE_DOMAIN="xxxxxx.map.azionedge.net" # Replace with your edge domain
ENDPOINTS=("/style.css" "/script.js" "/api/data" "/image.jpg")
echo "Cache Health Check for $EDGE_DOMAIN"
echo "================================"
echo "$(date)"
# Get and fix Azion IP for consistent testing
AZION_IP=(dig +short @8.8.8.8 "$EDGE_DOMAIN" | head -1)
echo "Using Azion IP: $AZION_IP"
echo
for endpoint in "${ENDPOINTS[@]}"; do
echo "Testing: $endpoint"
# First request - expect MISS
echo -n " Request 1 (MISS): "
RESPONSE1=(curl --resolve "$EDGE_DOMAIN:443:$AZION_IP" \
-H "Pragma: azion-debug-cache" \
-w "TTFB:%{time_starttransfer}s|Total:%{time_total}s" \
-s -I "https://$EDGE_DOMAIN$endpoint")
CACHE1=(echo "$RESPONSE1" | grep "X-Cache:" | cut -d' ' -f2)
TIMING1=(echo "$RESPONSE1" | tail -1)
echo "$CACHE1 ($TIMING1)"
sleep 1
# Second request - expect HIT
echo -n " Request 2 (HIT): "
RESPONSE2=(curl --resolve "$EDGE_DOMAIN:443:$AZION_IP" \
-H "Pragma: azion-debug-cache" \
-w "TTFB:%{time_starttransfer}s|Total:%{time_total}s" \
-s -I "https://$EDGE_DOMAIN$endpoint")
CACHE2=(echo "$RESPONSE2" | grep "X-Cache:" | cut -d' ' -f2)
TIMING2=(echo "$RESPONSE2" | tail -1)
echo "$CACHE2 ($TIMING2)"
# Show cache key
CACHE_KEY=(echo "$RESPONSE2" | grep "X-Cache-Key:" | cut -d' ' -f2-)
echo " Cache Key: $CACHE_KEY"
echo
done
echo "Cache Health Check Complete"
echo "Summary: Static assets should show MISS -> HIT pattern"

Troubleshooting cache issues

Low cache hit ratio (< 60%)

Diagnosis:

# Check cache keys being generated
azion logs http --tail | grep "Cache Key"

Solutions:

  • Configure cache-by-query-string to ignore for static content
  • Use whitelist for cookies instead of caching by all cookies
  • Implement bypass rules for authenticated users

Stale content not updating

Diagnosis:

# Check TTL configuration
curl -H "Pragma: azion-debug-cache" -I "https://yourdomain.com/content"
# Look at X-Cache-Valid and X-Cache-Expire headers

Solutions:

# Purge specific content
azion purge --urls "https://yourdomain.com/content"
# Purge with wildcard
azion purge --wildcard "https://yourdomain.com/api/*"
# Purge by cache key
azion purge --cache-key "yourdomain.com/api/data@@lang=en,region=US"

Dynamic content being cached

Diagnosis:

# Test with different user scenarios
curl -H "Cookie: user_id=123" "https://yourdomain.com/profile"
curl -H "Cookie: user_id=456" "https://yourdomain.com/profile"
# If both return same content, it's incorrectly cached

Solutions:

  • Add bypass rule for personalized content paths
  • Configure proper cacheByCookie settings
  • Use shorter TTLs for user-specific content

Best practices

  1. Use Pragma: azion-debug-cache for immediate cache debugging
  2. Monitor Real-Time Events for cache behavior analysis
  3. Test cache key variations with different parameters/cookies
  4. Implement tiered TTL strategy based on content type
  5. Use stale-while-revalidate for better availability
  6. Monitor cache hit ratios and optimize configurations
  7. Purge strategically using wildcards and cache keys
  8. Test from multiple locations using direct IP connections
  9. Automate cache health checks with shell scripts
  10. Measure performance differences between cached and non-cached requests

Next steps