Skip to content
VirtConsole Docs

Metrics export

Metrics Export gives your customers their own telemetry 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, Grafana Cloud, or anything else that scrapes the Prometheus text format at one URL with an API token they already have, and their resources show up as time series they can dashboard and alert on.

What it is

Section titled “What it is”

The endpoints read from the telemetry the platform already collects and re-label it into a stable, customer-safe namespace. Hypervisor names, addresses and internal topology never appear in the output. Nothing is installed anywhere, and there is nothing for you to enable: the endpoints ship active.

Metric families:

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.

Network rates are shown from the guest’s point of view: receive is what the resource downloaded and transmit is what it uploaded. On KVM nodes this view applies from 3.3.1, with the same metric names and labels, so a dashboard built for the earlier KVM values needs adjusting.

Endpoints

Section titled “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
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 team member’s token sees exactly the resources their permissions grant; the account owner’s token sees everything. Managed database and load balancer metrics additionally require billing to be enabled, because both are billed resources.

Limits and caching

Section titled “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.
  • Fail-soft: the endpoints answer HTTP 200 always. A hypervisor or metrics backend that is briefly unreachable shows up as hv_resource_up 0 on the affected resources, never a 5xx, so a platform-side blip cannot flood a customer’s Prometheus with scrape errors.

Example scrape configuration

Section titled “Example scrape configuration”

This is what a customer adds to their Prometheus. Hand it to them together with an API token from their account:

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

Useful first queries:

hv_instance_cpu_percent{name="web-01"}
hv_resource_up == 0

Admin notes

Section titled “Admin notes”
  • There is nothing to configure. The endpoints use the metrics backends already configured per hypervisor group. If a group has no metrics backend, databases and load balancers in it are 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 endpoints expose no internal names. The only identifiers in the output are the customer’s own resource ids and names.

Common problems

Section titled “Common problems”
  • hv_resource_up 0 on a resource. The platform could not reach that resource’s telemetry on that scrape: the agent for instances, the metrics backend for databases and load balancers. Transient zeros resolve on the next scrape. Persistent zeros on a database or load balancer usually mean the resource’s own monitoring needs repair from its metrics tab in the user panel.
  • A customer gets HTTP 429. Their token exceeded 30 requests per minute. Tell them to lengthen the scrape interval; each team member token has its own budget.
  • Databases and load balancers are missing from a scrape while instances are present. Billing is disabled, or the resource’s group has no metrics backend configured.
Section titled “Related”