Monitoring & Metrics
VCAL Semantic Cache exposes Prometheus metrics at:
/metrics
If authentication is enabled, /metrics can remain public when:
VCAL_ALLOW_METRICS_WITHOUT_AUTH=1
Key Metrics
| Metric | Type | Description |
|---|---|---|
vcal_active_ids | Gauge | Number of active, non-tombstoned IDs |
vcal_answers_cached | Gauge | Number of cached answers |
vcal_search_requests_total | Counter | Total search requests |
vcal_search_errors_total | Counter | Search errors |
vcal_insert_requests_total | Counter | Total insert requests |
vcal_insert_errors_total | Counter | Insert errors |
vcal_upsert_errors_total | Counter | Upsert errors |
vcal_delete_errors_total | Counter | Delete errors |
vcal_cache_hits_total | Counter | Cache hits |
vcal_cache_misses_total | Counter | Cache misses |
vcal_tokens_saved_total | Counter | Estimated tokens saved |
vcal_evictions_total | Counter | TTL/LRU evictions, usually labeled by reason |
vcal_snapshot_saves_total | Counter | Successful snapshot saves |
vcal_snapshot_pause_ms | Gauge/summary depending on build | Pause time for quiescent shutdown snapshots |
vcal_license_valid | Gauge | Whether the active license is valid |
vcal_license_days_until_expiry | Gauge | Days until license expiration |
Snapshot Logs in v0.6.0
Normal autosave and manual snapshot saves log messages similar to:
INFO background paired snapshot completed bytes=4929 entries=1
Graceful shutdown logs the quiescent path:
INFO quiescent paired snapshot completed pause_ms=3 bytes=4929 entries=1
INFO Final snapshots saved successfully (paired).
entries may refer to underlying index entries rather than active returned IDs. When tombstones exist, active result counts may be lower than the raw index entry count. Use API checks or metrics such as vcal_active_ids for active cache size.
Example Prometheus Scrape
scrape_configs:
- job_name: vcal-server
metrics_path: /metrics
static_configs:
- targets: ["vcal-server:8080"]
Example Grafana Panels
Recommended panels:
- Active IDs:
vcal_active_ids - Answers cached:
vcal_answers_cached - Search request rate:
rate(vcal_search_requests_total[5m]) - Insert request rate:
rate(vcal_insert_requests_total[5m]) - Cache hit/miss rate:
rate(vcal_cache_hits_total[5m])andrate(vcal_cache_misses_total[5m]) - Snapshot saves:
increase(vcal_snapshot_saves_total[1h]) - License days remaining:
vcal_license_days_until_expiry - Errors by operation:
rate(vcal_search_errors_total[5m]),rate(vcal_insert_errors_total[5m]),rate(vcal_delete_errors_total[5m])
Quick Check
curl -s http://localhost:8080/metrics | head
With authentication enabled and metrics not public:
curl -s -H "X-VCAL-Key: <admin_key>" http://localhost:8080/metrics | head