Metrics API

The gateway exposes a Prometheus-shaped metrics surface on its own endpoint, plus passthrough routes to the bundled VictoriaMetrics (vmsingle) instance so callers can run PromQL without a separate scraper. A self-describing catalog of every metric the gateway emits backs both the dashboard’s observe tab and external automation.

For the metric definitions, label conventions, cardinality model, and example PromQL, see Metrics.

Routes

Route	Behavior
GET /metrics	Prometheus exposition from the gateway.
GET /health	Liveness, NVMe cache connection state, and per-namespace cache state.
GET|POST /v2/metrics/api/v1/query	Proxy Prometheus instant query.
GET|POST /v2/metrics/query	Short-form instant query proxy.
GET|POST /v2/metrics/api/v1/query_range	Proxy Prometheus range query.
GET|POST /v2/metrics/query_range	Short-form range query proxy.
GET /v2/metrics/catalog	List every metric the gateway emits.
GET /v2/metrics/catalog/{name}	Fetch one catalog entry, including labels and example PromQL.

Health

GET /health

{
  "status": "ok",
  "cache": {
    "state": "warm",
    "reconnect_generation": 3
  },
  "namespaces": [
    {"namespace": "products", "state": "warm"}
  ]
}

Health is the gauge the dashboard’s at-a-glance cards read. A 503 here means the gateway is up but degraded — typically NVMe is cold.

Metrics catalog

The catalog is the operator-facing manifest of every metric the gateway emits. Each entry carries name, kind (histogram / counter / gauge), labels, description, example PromQL, and (when applicable) the alert shape it backs.

GET /v2/metrics/catalog

{
  "version": "2026-05",
  "entries": [
    {
      "name": "layer_query_duration_seconds",
      "kind": "histogram",
      "labels": ["pipeline_id", "namespace", "status"],
      "description": "Total wall-clock for a query through layer.",
      "example_promql": "histogram_quantile(0.99, sum by (le) (rate(layer_query_duration_seconds_bucket[5m])))",
      "alert": {"name": "QueryP99High", "condition": "..."}
    }
  ]
}

version bumps when the JSON shape changes incompatibly. The dashboard observes the catalog and groups entries by family so operators don’t have to memorize which prefix lives where.

The same content is also exportable from the repo via cargo run -p metrics-catalog --bin export.

PromQL passthrough

The /v2/metrics/api/v1/query and query_range routes are thin passthroughs to VictoriaMetrics. Response bodies match Prometheus’s HTTP API shape one-for-one. The short-form aliases under /v2/metrics/query exist to make terminal use ergonomic:

curl -sG "$LAYER_GATEWAY_URL/v2/metrics/query" \
  --data-urlencode 'query=sum(layer_pipeline_stage_count{stage="pending"})'

The gateway does not rewrite queries. Auth happens at the gateway edge; the upstream VictoriaMetrics instance is never customer-reachable.