Cache Management API
Base path: /api/v1/cache
Implementation reference: internal/cache/handler.go, service in internal/cache/service.go.
The cache system stores Prometheus query results to reduce latency and load on Prometheus data sources. It supports a two-tier architecture: an in-memory sync.Map for hot entries and a database-backed persistent store.
Endpoints
| Method | Path | Description | Auth Required |
|---|---|---|---|
| GET | /cache/statistics | Get cache performance statistics | Yes |
| POST | /cache/invalidate | Invalidate cache entries by key, SLO, pattern, expired, or all | Yes |
| POST | /cache/warmup | Preload cache with specified queries | Yes |
| GET | /cache/config | Get current cache configuration | Yes |
| PUT | /cache/config | Update cache configuration | Yes |
| GET | /cache/entry/:key | Get a specific cache entry by key | Yes |
| POST | /cache/entry | Manually create a cache entry | Yes |
| GET | /cache/entries | List cache entries with filtering | Yes |
| DELETE | /cache/entry/:key | Delete a specific cache entry | Yes |
Routes are registered via internal/cache/handler.go:345 (RegisterRoutes).
GET /cache/statistics
Returns cache performance metrics including hit rate, memory usage, and entry counts.
Response (200 OK):
{
"success": true,
"data": {
"total_entries": 1250,
"total_hits": 15000,
"total_misses": 3500,
"hit_rate": 0.81,
"average_ttl": 300,
"average_entry_size": 2048,
"memory_usage_mb": 2.5,
"is_fresh_count": 1100,
"expired_count": 150,
"hot_entries_count": 300,
"cold_entries_count": 950
}
}Statistics are tracked in-memory (CacheStatistics in internal/cache/service.go:44) and aggregated with database-level stats.
POST /cache/invalidate
Invalidates cache entries based on the specified type. Supports five invalidation strategies:
Request (by exact key):
{
"type": "key",
"key": "query:1:24h:abc123..."
}Request (by SLO ID — invalidates all entries for an SLO):
{
"type": "slo",
"slo_id": 1
}Request (by key pattern — prefix match):
{
"type": "pattern",
"pattern": "query:1:"
}Request (expired entries — cleanup stale data):
{
"type": "expired"
}Request (all cache — full flush):
{
"type": "all"
}Response (200 OK):
{
"success": true,
"message": "Cache invalidated successfully",
"data": {
"type": "slo",
"invalidations": 15,
"timestamp": "2026-06-11T10:00:00Z"
}
}POST /cache/warmup
Pre-populates the cache by executing and storing results for specified Prometheus queries. Useful after deployment or configuration changes.
Request:
{
"queries": [
{
"query": "rate(http_requests_total{job=\"api\"}[5m])",
"slo_id": 1,
"time_window": "24h",
"ttl": 300000000000
},
{
"query": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))",
"slo_id": 2,
"time_window": "1h",
"ttl": 600000000000
}
]
}| Field | Type | Description |
|---|---|---|
query | string | PromQL query string |
slo_id | int | SLO ID this query belongs to |
time_window | string | Time window (e.g. 24h, 7d) |
ttl | int | TTL in nanoseconds (defaults to 5 minutes) |
Response (200 OK):
{
"success": true,
"message": "Cache warmed up successfully",
"data": {
"queries_warmed": 2,
"timestamp": "2026-06-11T10:00:00Z"
}
}GET /cache/config
Returns the current cache configuration.
Response (200 OK):
{
"success": true,
"data": {
"default_ttl": 300000000000,
"max_entries": 10000,
"cleanup_interval": 3600000000000,
"enable_memory_cache": true,
"enable_compression": true,
"compression_threshold": 1024,
"enable_warmup": true,
"analytics_retention": 2592000000000000
}
}Configuration fields and their types (from internal/cache/service.go:69):
| Field | Type | Description |
|---|---|---|
default_ttl | duration | Default TTL for cached entries |
max_entries | int | Maximum number of cache entries before eviction |
cleanup_interval | duration | How often expired entries are cleaned up |
enable_memory_cache | bool | Enable in-memory cache tier |
enable_compression | bool | Compress large cache entries with gzip |
compression_threshold | int | Minimum entry size (bytes) for compression |
enable_warmup | bool | Allow cache warmup operations |
analytics_retention | duration | How long to retain cache analytics |
PUT /cache/config
Updates cache configuration at runtime. Only provided fields are updated.
Request:
{
"default_ttl": 600000000000,
"max_entries": 20000,
"enable_compression": false
}Response (200 OK):
{
"success": true,
"message": "Cache configuration updated successfully"
}GET /cache/entry/:key
Retrieves a specific cache entry by its key. The key is URL-encoded in the path.
Response (200 OK):
{
"success": true,
"data": {
"key": "query:1:24h:abc123...",
"query_hash": "xyz789...",
"query": "rate(http_requests_total[5m])",
"slo_id": 1,
"time_window": "24h",
"result": {
"current_value": 0.998,
"target_value": 0.995,
"status": "healthy"
},
"cached_at": "2026-06-11T09:30:00Z",
"expires_at": "2026-06-11T09:35:00Z",
"hit_count": 250,
"last_hit": "2026-06-11T09:34:55Z",
"is_fresh": true
}
}Cache entry fields (from internal/cache/service.go:14):
| Field | Description |
|---|---|
key | Unique cache key (query:{slo_id}:{time_window}:{hash}) |
query_hash | SHA-256 hash of the query |
query | Original PromQL query string |
slo_id | Associated SLO ID |
result | Cached query result data |
cached_at | When the entry was cached |
expires_at | When the entry expires |
hit_count | Number of cache hits |
is_fresh | Whether the entry is still fresh |
POST /cache/entry
Manually creates a cache entry. Useful for testing or pre-populating specific values.
Request:
{
"key": "manual:entry:1",
"query": "up{job=\"api\"}",
"slo_id": 1,
"time_window": "5m",
"result": {
"value": 1
},
"ttl": 120000000000
}| Field | Type | Required | Description |
|---|---|---|---|
key | string | Yes | Cache key |
query | string | Yes | PromQL query |
slo_id | int | Yes | SLO ID |
time_window | string | Yes | Time window |
result | any | Yes | Result data to cache |
ttl | duration | No | TTL in nanoseconds (default: 5 minutes) |
Response (200 OK):
{
"success": true,
"message": "Cache entry created successfully"
}GET /cache/entries
Lists cache entries with optional filtering and pagination.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | int | 1 | Page number |
page_size | int | 20 | Items per page (max 100) |
slo_id | int | — | Filter by SLO ID |
fresh | bool | — | Filter by fresh/expired status |
Response (200 OK):
{
"success": true,
"data": {
"entries": [
{
"key": "query:1:24h:abc123...",
"query": "rate(http_requests_total[5m])",
"slo_id": 1,
"time_window": "24h",
"cached_at": "2026-06-11T09:30:00Z",
"expires_at": "2026-06-11T09:35:00Z",
"hit_count": 250,
"is_fresh": true
}
],
"total": 1250,
"page": 1,
"page_size": 20,
"has_next": true
}
}DELETE /cache/entry/:key
Deletes a specific cache entry by its key.
Response (200 OK):
{
"success": true,
"message": "Cache entry deleted successfully"
}Cache Eviction
When max_entries is reached, the cache evicts the least recently used (LRU) entry (internal/cache/service.go:365).
Background Cleanup
A background goroutine runs periodically (cleanupInterval) to delete expired entries from the database (internal/cache/service.go:343).
Error Codes
| HTTP Status | Scenario |
|---|---|
400 | Invalid request body, missing required fields |
404 | Cache entry not found |
500 | Database error, service failure |