Monitoring & Metrics

VCAL exposes native Prometheus metrics at /metrics.

Key Metrics

Metric	Type	Description
vcal_cache_hits_total	Counter	Cache Hit Ratio (%)
vcal_tokens_saved_total	Counter	Tokens Saved (range)
vcal_tokens_saved_total	Counter	Cost Savings (range)
vcal_answers_cached	Gauge	Answers Cached
vcal_cache_hits_total	Gauge	Requests (range)
vcal_search_errors_total, vcal_batch_search_errors_total, vcal_insert_errors_total, vcal_upsert_errors_total, vcal_delete_errors_total	Counter	Errors (range)
vcal_search_latency_seconds_bucket	Gauge	Server Search Latency (p50 / p95)
vcal_evictions_total	Gauge	TTL Evictions (10m)
vcal_evictions_total	Gauge	LRU Evictions (10m)

Example Grafana Dashboard

1. Add Prometheus datasource:

   URL: http://vcal-server:8080/metrics

2. Import the provided dashboard JSON from deploy/grafana/vcal-dashboard.json (request the file from VCAL Server Team).

3. Visualize:

   • Cache hit ratio
   • Tokens saved (range)
   • Costs saved (range)
   • Answers cached
   • Requests
   • Errors
   • Server Search Latency (p55 / p95)
   • TTL Evictions
   • LRU Evictions