Metrics & Health
On this page 4 sections
QSCS exposes a Prometheus-style metrics endpoint at /qscs/metrics on the public listening port. To prevent external metric scraping, the endpoint only answers requests that arrive on the loopback interface (127.0.0.1). Requests on the public interface, or with spoofed X-Forwarded-For: 127.0.0.1 headers, return 404.
Scraping safely
If you run Prometheus on the same host, scrape:
scrape_configs:
- job_name: qscs
metrics_path: /qscs/metrics
static_configs:
- targets: ['127.0.0.1:8080']If Prometheus lives elsewhere, run a small loopback-bound exporter on each QSCS host (for example via a node_exporter side process) and have it forward the metrics, or expose them over an authenticated channel of your choice.
Key metrics
| Metric | Type | Meaning |
|---|---|---|
qscs_origin_degraded | gauge | 1 if the upstream for this origin is currently considered failed; 0 otherwise. |
qscs_origin_failures_total | counter | Total upstream failures observed for this origin. |
qscs_origin_headless_requests_total | counter | Responses served from cache while the origin was degraded. |
qscs_origin_probes_total | counter | Background probes sent while degraded. |
qscs_cache_entries | gauge | Number of distinct cached entries currently held. |
qscs_cache_bytes | gauge | Total bytes used by the cache (response bodies). |
qscs_http_requests_total | counter | Total HTTP requests served, labelled by mode and status. |
All metrics are labelled by origin (the hostname) where applicable.
Suggested alerts
max_over_time(qscs_origin_degraded[5m]) == 1sustained for > 2 minutes → alert.rate(qscs_origin_failures_total[5m]) > 0.5for a single origin → warn.rate(qscs_origin_headless_requests_total[1m]) > 0→ notice (HEADLESS is engaging).
Quick health check from the host
# degraded gauge for every origin
curl -s http://127.0.0.1:8080/qscs/metrics | awk '/^qscs_origin_degraded/{print}'
# total bytes cached
curl -s http://127.0.0.1:8080/qscs/metrics | awk '/^qscs_cache_bytes/{print}'