Metrics Export

Overview

Metrics Export lets your customers pull their own telemetry out of the platform in the format the monitoring world already speaks. Every account gets Prometheus-format scrape endpoints on the user API covering its instances, managed databases and load balancers. A customer points their existing Prometheus (or Grafana Cloud, VictoriaMetrics, or anything else that scrapes the Prometheus text format) at one URL with the API token they already have, and their resources show up as time series they can dashboard and alert on.

Nothing new is installed anywhere. The endpoints read from the telemetry the platform already collects - the hypervisor agents' instance statistics and the per-location metrics backends used by managed databases and load balancers - and re-label it into a stable, customer-safe namespace. Hypervisor names, addresses and internal topology never appear in the output.

Concepts

Exposition: the plain-text format Prometheus scrapes (text/plain; version=0.0.4). Each response is a self-contained snapshot of current values; Prometheus turns repeated scrapes into time series.

Metric families: everything is namespaced by resource type.

Family	Metrics
hv_instance_*	CPU percent, memory percent, disk percent, network receive/transmit Mbps, disk read/write IOPS
hv_db_*	CPU percent, memory percent, disk percent, current connections, queries per second
hv_lb_*	active frontend sessions, session rate, backends up
hv_resource_up	1 when the resource's telemetry was reachable on this scrape, 0 when it was not

Every sample carries the resource's id and name as labels, so one dashboard variable covers a whole fleet.

Fail-soft: the endpoints answer HTTP 200 always. A hypervisor or metrics backend being briefly unreachable shows up as hv_resource_up 0 on the affected resources - never a 5xx, so a platform-side blip cannot flood the customer's Prometheus with scrape errors.

Endpoints

Route	Returns
GET /api/metrics	account-wide: every owned instance, managed database and load balancer in one exposition
GET /api/metrics/instances/{id}	one instance (also covers Kubernetes worker VMs and VPN gateway backing VMs)
GET /api/metrics/databases/{id}	one managed database
GET /api/metrics/load-balancers/{id}	one load balancer

/api/metrics is the intended target - one scrape job, every resource, including resources created after the scrape job was configured. The per-resource routes exist for narrowly scoped jobs.

Authentication is the standard user API bearer token. A subuser's token sees exactly the resources the subuser's team permissions grant; the account owner's token sees everything.

Limits and caching

• Rate limit: 30 requests per minute per token. A 15-60 second scrape interval fits comfortably.
• Caching: the account-wide endpoint caches its rendered body for 10 seconds per account, so several Prometheus instances scraping the same account do not multiply backend load. The per-resource endpoints are not cached.
• Time budget: the account-wide endpoint runs under a hard internal deadline; a slow backend degrades those resources to hv_resource_up 0 rather than stalling the scrape.

Example scrape configuration

scrape_configs:
  - job_name: hypervisor
    metrics_path: /api/metrics
    scheme: https
    bearer_token: <your user API token>
    scrape_interval: 30s
    static_configs:
      - targets: ['panel.example.com']

With that in place, a Grafana panel query is as simple as:

hv_instance_cpu_percent{name="web-01"}

or across the fleet:

topk(5, hv_instance_memory_percent)

A useful first alert is on the up metric itself:

hv_resource_up == 0

Admin notes

• There is nothing to enable. The endpoints ship active and use the metrics backends already configured per hypervisor group (the same VictoriaMetrics endpoints managed databases and load balancers chart from). If a group has no metrics backend configured, databases and load balancers in it are simply absent from the exposition rather than erroring.
• Database engine metrics (connections, queries per second) exist only for engines the metrics agent instruments. Every database still gets CPU, memory, disk and hv_resource_up.
• The full endpoint reference, including response examples, is in the generated user API documentation under Metrics Export.

Troubleshooting

A resource shows hv_resource_up 0

The platform could not reach that resource's telemetry on this scrape - hypervisor agent unreachable for instances, metrics backend unreachable for databases and load balancers. Transient blips resolve on the next scrape. Persistent zeros on a managed database or load balancer usually mean the resource's own monitoring agent is broken; the Fix Monitoring action on the resource's metrics tab repairs it.

A database has no hv_db_connections / hv_db_queries_per_second

Expected for engines without a dedicated agent instrumentation, and for any database whose group has no metrics backend. OS-level metrics (CPU, memory, disk) do not depend on the engine.

HTTP 429

The token exceeded 30 requests per minute. Lengthen the scrape interval, or note that each subuser token has its own budget - splitting jobs across tokens also splits the limit.

Related pages

• Managed Databases - setting up the per-group metrics backend these endpoints read from
• Monitoring - the admin-side activity and task pages