Cache Analytics

The CacheAnalyticsService provides comprehensive analytics about cache behavior, efficiency, and access patterns. These analytics power the cache management dashboard and inform optimization decisions.

Analytics Dashboard

curl http://query-engine:8080/v1/cache/analytics/dashboard \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "overallHitRate": 0.42,
  "l1HitRate": 0.28,
  "l2HitRate": 0.14,
  "totalLookups": 45000,
  "totalHits": 18900,
  "totalMisses": 26100,
  "totalEntries": 2450,
  "totalSizeBytes": 134217728,
  "averageEntrySize": 54782,
  "topQueriesByHits": [
    {"queryHash": "a3f2...", "hitCount": 1542, "lastAccessed": "2026-02-12T10:00:00Z"}
  ],
  "evictionRate": 0.05,
  "warmingEfficiency": 0.78
}

Efficiency Report

Generate a detailed efficiency report for a specific time period:

curl "http://query-engine:8080/v1/cache/analytics/efficiency-report?hours=24" \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "period": "PT24H",
  "hitRate": 0.42,
  "byteSavings": 10737418240,
  "timeSavingsMs": 2450000,
  "costSavingsEstimate": 12.50,
  "inefficientEntries": 45,
  "neverHitEntries": 120,
  "singleHitEntries": 340,
  "recommendations": [
    "Consider increasing L1 cache size - eviction rate is high",
    "45 entries have never been hit - consider reducing TTL for low-value patterns"
  ]
}

Per-Query Analysis

Analyze a specific query's cache performance:

curl http://query-engine:8080/v1/cache/analytics/query/a3f2b9c1 \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "found": true,
  "queryHash": "a3f2b9c1",
  "hitCount": 1542,
  "missCount": 23,
  "hitRate": 0.985,
  "averageExecutionTimeMs": 2450,
  "cacheTimeSavingsMs": 3779900,
  "entrySize": 45200,
  "dependencies": ["analytics.orders", "analytics.customers"],
  "lastCachedAt": "2026-02-12T09:45:00Z",
  "expiresAt": "2026-02-12T10:45:00Z"
}

Time-Series Metrics

Retrieve cache metrics as time-series data for visualization:

# Get hit rate time series for the last 24 hours
curl "http://query-engine:8080/v1/cache/analytics/timeseries/hitRate?hours=24" \
  -H "Authorization: Bearer $JWT_TOKEN"

[
  {"timestamp": "2026-02-11T11:00:00Z", "value": 0.38},
  {"timestamp": "2026-02-11T12:00:00Z", "value": 0.41},
  {"timestamp": "2026-02-11T13:00:00Z", "value": 0.45},
  {"timestamp": "2026-02-11T14:00:00Z", "value": 0.43}
]

Available metrics: hitRate, lookupCount, evictionRate, entryCount, sizeBytes.

Access Heatmap

Visualize cache access patterns across time:

curl http://query-engine:8080/v1/cache/analytics/heatmap \
  -H "Authorization: Bearer $JWT_TOKEN"

{
  "hourlyAccess": {
    "0": 120, "1": 45, "2": 23, "3": 12, "4": 8, "5": 15,
    "6": 340, "7": 890, "8": 2100, "9": 3200, "10": 3500,
    "11": 3100, "12": 2800, "13": 3000, "14": 3200, "15": 2900,
    "16": 2600, "17": 2100, "18": 1200, "19": 800, "20": 450,
    "21": 300, "22": 200, "23": 150
  },
  "peakHour": 10,
  "quietHour": 4
}

Export Analytics Data

Export analytics data for external analysis:

curl http://query-engine:8080/v1/cache/analytics/export \
  -H "Authorization: Bearer $JWT_TOKEN"

This endpoint requires ADMIN or QUERY_ADMIN role and returns a comprehensive data export including all cache entries, their statistics, and access patterns.

Cache Warming Invalidation