hyperping-exporter

README

hyperping-exporter

Get Hyperping monitor metrics into Prometheus in 30 seconds.

A standalone Prometheus exporter for Hyperping monitoring. Exposes monitor status, healthchecks, SLA ratios, outage metrics, and tenant health scores as Prometheus gauges.

Extracted from develeap/terraform-provider-hyperping to serve as a standalone, reusable exporter. The same battle-tested API client (with circuit breaker, retry, and rate-limit handling) is embedded here with zero runtime dependency on the provider.

Maintained by Develeap.

---

Quick start

[!NOTE] Get your API key first: Log in to Hyperping → Account Settings → API → Create API Key.

docker run -p 9312:9312 \
  -e HYPERPING_API_KEY=your_key \
  khaledsalhabdeveleap/hyperping-exporter:latest

curl -s http://localhost:9312/metrics | grep hyperping_monitor_up

If you see output, you're done.

Other installation methods

Binary download — grab the latest release from the Releases page. Each archive includes an SBOM (*.sbom.json) for supply-chain verification. Then:

HYPERPING_API_KEY=your_key ./hyperping-exporter

Install with Go

go install github.com/develeap/hyperping-exporter@latest
HYPERPING_API_KEY=your_key hyperping-exporter

Metrics are served at http://localhost:9312/metrics.

---

Configuration

All flags can also be set via environment variables.

Flag	Env var	Default	Description
--api-key	HYPERPING_API_KEY	(required)	Hyperping API key
--listen-address	(flag only)	:9312	Address to listen on
--metrics-path	(flag only)	/metrics	Path to expose metrics on
--cache-ttl	(flag only)	60s	How often to refresh data from the API
--log-level	(flag only)	info	Log level: debug, info, warn, error
--log-format	(flag only)	text	Log format: text or json
--namespace	HYPERPING_EXPORTER_NAMESPACE	hyperping	Metric name prefix. Must match [a-zA-Z_][a-zA-Z0-9_]{0,63}.
--mcp-url	(flag only)	(official)	Custom Hyperping MCP server URL.

Only HYPERPING_API_KEY is read from the environment by default; all other options use CLI flags, which map cleanly to Docker command: entries. Use HYPERPING_EXPORTER_NAMESPACE for the namespace flag.

Performance Tuning

Concern	Recommendation
Freshness vs API load	Default 60s TTL makes 5 REST parallel API calls + per-monitor MCP calls. For >100 monitors, keep TTL above 60s to avoid rate limits.
Worker Pool	MCP metrics use a worker pool of 10 concurrent requests to minimize latency while protecting the API.
Cardinality	Each monitor contributes ~13 time series. 100 monitors ≈ 1300 series — negligible for any Prometheus setup.
Scrape interval	Set Prometheus scrape interval ≥ cache-ttl. Scraping faster than the cache refreshes returns identical data.

---

Available metrics

Monitor metrics

Metric	Type	Description	Labels
hyperping_monitor_up	Gauge	1 if the monitor is up, 0 if down.	uuid, name, tenant, tier
hyperping_monitor_paused	Gauge	1 if paused, 0 if active.	uuid, name, tenant, tier
hyperping_monitor_check_interval_seconds	Gauge	Frequency of checks.	uuid, name, tenant, tier
hyperping_monitor_info	Gauge	Metadata about the monitor.	uuid, name, tenant, tier, url, protocol, method
hyperping_monitor_ssl_expiration_days	Gauge	Days until SSL cert expires.	uuid, name, tenant, tier
hyperping_monitor_outage_active	Gauge	1 if currently in outage.	uuid, name, tenant, tier
hyperping_monitor_active_outage_status_code	Gauge	HTTP status code of active outage.	uuid, name, tenant, tier
hyperping_monitor_escalation_tier	Gauge	1 (info only).	uuid, name, tier
hyperping_monitor_in_maintenance	Gauge	1 if in a maintenance window.	uuid, name, tenant, tier
hyperping_monitor_up_by_region	Gauge	1 if up in region, 0 if down.	uuid, name, tenant, tier, region
hyperping_monitor_response_time_avg_seconds	Gauge	Average response time via MCP.	uuid, name, tenant, tier
hyperping_monitor_mtta_seconds	Gauge	Mean Time To Acknowledge via MCP.	uuid, name, tenant, tier
hyperping_monitor_anomaly_count	Gauge	Detected anomalies count via MCP.	uuid, name, tenant, tier
hyperping_monitor_anomaly_score	Gauge	Highest anomaly score via MCP.	uuid, name, tenant, tier
hyperping_monitor_sla_ratio	Gauge	Monitor SLA (0–1).	uuid, name, tenant, tier, period
hyperping_monitor_outages	Gauge	Count of outages in period.	uuid, name, tenant, tier, period
hyperping_monitor_downtime	Gauge	Total downtime seconds in period.	uuid, name, tenant, tier, period
hyperping_monitor_longest_outage	Gauge	Longest outage seconds in period.	uuid, name, tenant, tier, period
hyperping_monitor_mttr	Gauge	Mean Time To Resolve in period.	uuid, name, tenant, tier, period

Healthcheck metrics

Metric	Type	Description	Labels
hyperping_healthcheck_up	Gauge	1 if healthcheck is up.	uuid, name
hyperping_healthcheck_paused	Gauge	1 if paused.	uuid, name
hyperping_healthcheck_period_seconds	Gauge	Expected ping interval.	uuid, name

Tenant & Global metrics

Metric	Type	Description	Labels
hyperping_tenant_monitors_up_ratio	Gauge	Fraction of monitors up (0–1).
hyperping_tenant_active_outages	Gauge	Total active outages.
hyperping_tenant_health_score	Gauge	Composite health score (0–100).
hyperping_incidents_open	Gauge	Count of open incidents.
hyperping_maintenance_windows_active	Gauge	Active maintenance windows.
hyperping_alerts_total	Counter	Total alerts in history via MCP.
hyperping_monitors	Gauge	Total monitors discovered.
hyperping_healthchecks	Gauge	Total healthchecks discovered.
hyperping_scrape_success	Gauge	1 if last API scrape succeeded.
hyperping_scrape_duration_seconds	Gauge	Duration of last scrape.
hyperping_data_age_seconds	Gauge	Seconds since last successful scrape.

---

Docker Compose full stack

Exporter only (bring-your-own Prometheus)

If you already run Prometheus, add just the exporter:

services:
  hyperping-exporter:
    image: khaledsalhabdeveleap/hyperping-exporter:latest
    environment:
      HYPERPING_API_KEY: "${HYPERPING_API_KEY}"
    ports:
      - "127.0.0.1:9312:9312"
    restart: unless-stopped

Then add this scrape config to your prometheus.yml:

scrape_configs:
  - job_name: hyperping
    static_configs:
      - targets: ['localhost:9312']
    scrape_interval: 60s

Full stack

Starts the exporter, Prometheus (with alert + recording rules), and Grafana:

# One-time setup: copy the example and fill in your credentials
cp deploy/.env.example deploy/.env
$EDITOR deploy/.env

# Then start the stack
make compose-up

deploy/.env is gitignored — never commit it. GRAFANA_ADMIN_PASSWORD is required; the stack will fail loudly if it is not set. All services bind to 127.0.0.1 only for local dev safety.

---

Prometheus alerting rules

Pre-configured rules in deploy/prometheus/alerts.yml:

Alert	Severity	Condition
HyperpingMonitorDown	critical	Monitor down for > 2 min
HyperpingMonitorActiveOutage	critical	Active outage for > 1 min
HyperpingMultipleActiveOutages	critical	> 3 concurrent active outages
HyperpingCoreMonitorDown	critical	Core-tier monitor down for > 1 min
HyperpingSSLExpiryWarning	warning	SSL cert expiry < 14 days
HyperpingSSLExpiryCritical	critical	SSL cert expiry < 3 days
HyperpingMonitorSLABreach24h	warning	24h SLA < 99%
HyperpingMonitorSLABreach7d	warning	7d SLA < 99.5%
HyperpingTenantSLADegraded	critical	Fleet-wide 24h SLA < 95%
HyperpingHealthcheckDown	warning	Healthcheck missed for > 5 min
HyperpingTenantHealthDegraded	warning	Health score < 80
HyperpingTenantHealthCritical	critical	Health score < 60
HyperpingExporterScrapeFailure	warning	API unreachable for > 5 min
HyperpingDataStale	warning	Data age > 120s (2× cache TTL)

---

Relationship to terraform-provider-hyperping

This exporter uses the same Hyperping API client as develeap/terraform-provider-hyperping, but the client code is fully vendored here — there is no runtime dependency on the provider.

---

Troubleshooting

Symptom	Cause	Fix
error: API key required at startup	HYPERPING_API_KEY not set	Export the env var or use --api-key
/readyz returns 503	No successful API scrape yet	Wait up to --cache-ttl; check logs
hyperping_scrape_success 0	API unreachable or auth failure	Check API key, network, and logs
hyperping_data_age_seconds rising	Circuit breaker open	Check Hyperping API status; wait 30s
Rate limit errors in logs	--cache-ttl too low	Increase cache-ttl to 60s or higher

---

License

MIT. See LICENSE.