API: Metrics

Read every group's gauges in the Prometheus text format

get/metrics

For a Prometheus server, with a token that has the metrics:read ability. The metrics come with the Pro and Team plans, or with a grant from Hetscale; otherwise the answer is 403 plan_required. Every group outside the Archive has its own series, labelled group_id (grp_<ulid>) and group (its name). Every metric is a gauge: hetscale_group_desired_nodes, hetscale_group_min_nodes, hetscale_group_max_nodes, hetscale_group_active_nodes (serving and counted as capacity), hetscale_group_in_flight_nodes (being created, booted, deployed or health-checked), hetscale_group_shortfall_nodes (desired less active and in flight, never below zero), hetscale_group_last_time_to_capacity_seconds and hetscale_group_last_routed_timestamp_seconds for the newest server routed (absent until one is), hetscale_group_state with the label state (1 for the group's state among observe, rehearsing, live and paused) and, for a group past Observe, hetscale_group_capacity_limit with the label limit (1 for each of at_max, cost_guard, node_cap, euro_ceiling, plan_capacity and capacity_deficit that keeps the group from adding a server now). The answer comes from Hetscale's own data, never from Hetzner, and is kept for 60 seconds per organisation: a scrape interval of 60 seconds is enough.

Responses

200

The gauges in the Prometheus text format, version 0.0.4, served as `text/plain; version=0.0.4; charset=utf-8`.

401

The API token is missing, unknown, expired or revoked, or the member it acts for left the organisation (`unauthenticated`).

Body: Error

403

The token lacks the `metrics:read` ability (`forbidden`), or the organisation's plan does not include the metrics (`plan_required`).

Body: Error

429

The organisation's API rate limit, 60 requests a minute by default, is exhausted (`rate_limited`); retry after the seconds in `Retry-After`.

Body: Error

Example

curl -X GET https://api.hetscale.com/v1/metrics \
  -H "Authorization: Bearer $HETSCALE_API_TOKEN"