Prometheus metrics endpoint

Scrape the whole workspace

The fleet endpoint returns the latest value of every metric for every server in your workspace in one response.

GET https://api.getopservo.com/api/v1/metrics/prometheus

Authenticate with a workspace API token. Send it as Authorization: Bearer opv_… or in an X-Opservo-Token header. The response is text/plain; version=0.0.4 with Cache-Control: no-store, so nothing is cached between scrapes.

To scrape one server, use its agent id (the id in the server page URL):

GET https://api.getopservo.com/api/v1/agents/<agent-id>/metrics/prometheus

A server that is not in your workspace returns 404, never another workspace’s data.

scrape_config example

scrape_configs:
  - job_name: opservo
    scheme: https
    metrics_path: /api/v1/metrics/prometheus
    authorization:
      credentials: opv_xxxxxxxxxxxxxxxxxxxxxxxx
    static_configs:
      - targets: ['api.getopservo.com']
    scrape_interval: 60s

The agent sends a heartbeat every 60 seconds, so values change at most once a minute. Scraping faster than that returns the same numbers.

How metrics are named

Every metric is a gauge named opservo_<key>. Every sample carries the labels agent_id, hostname and display_name (the custom name you gave the server, or its hostname). Per-item metrics add one more label such as mount, service, container, instance or domain.

The full list (80+ metrics with unit, group and labels) is available as JSON from GET /api/v1/metrics/catalogue with the same token. The same catalogue drives the Grafana data source and custom dashboards, so a metric you see in one place exists in all of them.

Push instead of pull: the Metrics stream channel

If your collector cannot reach Opservo or you already use Datadog or New Relic, add a Metrics stream channel under Account → Notifications. Opservo then POSTs the catalogue metrics to your endpoint on a schedule.

• •Format: Plain JSON, Datadog (the POST /api/v2/series body shape) or New Relic (the Metric API shape).
• •Interval: every 1, 5 or 15 minutes.
• •Servers: the whole workspace, or a chosen list.
• •Headers: extra request headers such as DD-API-KEY or Api-Key for the receiving service.
• •Target: an https:// URL.

Every body is signed. The header X-Opservo-Signature holds sha256=<hex> where the hex is HMAC-SHA256 of the raw body using the channel’s signing secret. The secret is shown once when you add the channel; copy it then. X-Opservo-Channel carries the channel id so one receiver can tell channels apart.

If a delivery fails, Opservo retries with exponential back-off (the interval doubled per failure, capped at 2 hours) and shows the last status and error on the channel row. A streaming channel is never switched off by itself. The Test button sends a real payload now. Metrics stream channels carry numbers only; alerts and reports are never sent to them.

Limits

• •Values reflect the latest heartbeat; an offline server keeps reporting its last known values with opservo_agent_online at 0.
• •The per-server endpoint and the fleet endpoint accept the same token; there is no per-metric filtering on the Prometheus endpoint itself.
• •Revoking the token stops scrapes immediately with HTTP 401.