Cache API¶

The cache API provides endpoints for monitoring and managing the in-memory caches used by proxbox-api.

Cache Endpoints¶

Endpoint	Description
`GET /cache`	Inspect all caches (Proxbox and NetBox GET cache) with metrics and sample keys
`GET /cache/metrics`	Get NetBox GET cache metrics as JSON
`GET /cache/metrics/prometheus`	Get NetBox GET cache metrics in Prometheus exposition format
`GET /clear-cache`	Clear both Proxbox and NetBox GET caches

Response Schemas¶

GET /cache¶

Returns a combined view of all caches:

{
  "proxbox_cache": { ... },
  "netbox_get_cache_metrics": {
    "hits": 150,
    "misses": 50,
    "hit_rate": 75.0,
    "invalidations": 10,
    "evictions_ttl": 5,
    "evictions_size": 3,
    "evictions_bytes": 2500,
    "current_entries": 50,
    "current_bytes": 5242880,
    "max_entries": 4096,
    "max_bytes": 52428800,
    "ttl_seconds": 60.0,
    "oldest_entry_age_seconds": 45.2
  },
  "netbox_get_cache_sample": [
    {"api_id": 123456, "path": "/api/dcim/devices/", "query": ""}
  ]
}

GET /cache/metrics¶

Returns NetBox GET cache metrics:

{
  "hits": 150,
  "misses": 50,
  "hit_rate": 75.0,
  "invalidations": 10,
  "evictions_ttl": 5,
  "evictions_size": 3,
  "evictions_bytes": 2500,
  "current_entries": 50,
  "current_bytes": 5242880,
  "max_entries": 4096,
  "max_bytes": 52428800,
  "ttl_seconds": 60.0,
  "oldest_entry_age_seconds": 45.2
}

GET /cache/metrics/prometheus¶

Returns cache metrics in Prometheus format:

# HELP proxbox_cache_hits Total number of cache hits
# TYPE proxbox_cache_hits counter
proxbox_cache_hits 150
# HELP proxbox_cache_misses Total number of cache misses
# TYPE proxbox_cache_misses counter
proxbox_cache_misses 50
# HELP proxbox_cache_hit_rate Cache hit rate percentage
# TYPE proxbox_cache_hit_rate gauge
proxbox_cache_hit_rate 75.0
...

Metrics Reference¶

Metric	Type	Description
`hits`	counter	Total cache hits
`misses`	counter	Total cache misses
`hit_rate`	gauge	Cache hit rate percentage
`invalidations`	counter	Number of cache invalidations
`evictions_ttl`	counter	Entries evicted due to TTL expiry
`evictions_size`	counter	Entries evicted due to entry count limit
`evictions_bytes`	counter	Bytes evicted due to byte limit
`current_entries`	gauge	Current number of cached entries
`current_bytes`	gauge	Current cache size in bytes
`max_entries`	gauge	Maximum allowed entries
`max_bytes`	gauge	Maximum allowed bytes
`ttl_seconds`	gauge	Current TTL setting
`oldest_entry_age_seconds`	gauge	Age of oldest entry

Environment Variables¶

Variable	Default	Description
`PROXBOX_NETBOX_GET_CACHE_TTL`	60.0	Cache TTL in seconds (0 to disable)
`PROXBOX_NETBOX_GET_CACHE_MAX_ENTRIES`	4096	Maximum cached entries
`PROXBOX_NETBOX_GET_CACHE_MAX_BYTES`	52428800	Maximum cache size in bytes (50MB)
`PROXBOX_DEBUG_CACHE`	0	Enable debug logging (1 to enable)

Example: Prometheus Scraping¶

Add this to your Prometheus configuration:

scrape_configs:
  - job_name: 'proxbox-api'
    static_configs:
      - targets: ['proxbox-api:8000']
    metrics_path: '/cache/metrics/prometheus'