Configure Prometheus query metrics

Define a metric whose value comes from a PromQL query the agent runs against your Prometheus.

Prometheus is the most common metric source. The agent runs the PromQL query against the Prometheus URL configured at deploy time and reports the scalar result.

Configuration shape

A Prometheus metric carries a source_config of:

{
  "query": "rate(http_requests_total{job=\"checkout-api\",status=~\"5..\"}[5m]) / rate(http_requests_total{job=\"checkout-api\"}[5m])",
  "prometheus_url": "https://prometheus.example/  (optional override)"
}

The optional prometheus_url overrides the agent's PROMETHEUS_SERVER_URL for this single metric. Use it when one agent serves multiple Prometheus servers.

Query requirements

The query must return a single scalar value. Use aggregation (sum, avg, rate, etc.) to collapse vector results.
Empty results are reported as no_data; the metric does not flip status until the query produces a value.
The agent does not interpret the query content. The cloud's push payload contains the precomputed status, not the query string.

Authentication

When Prometheus requires basic auth, set on the agent:

PROMETHEUS_BASIC_AUTH_ENABLED=true
PROMETHEUS_USERNAME=...
PROMETHEUS_PASSWORD=...

These apply to every Prometheus probe the agent runs.

Threshold examples

Query	Healthy	Unhealthy
5xx error ratio (last 5 min)	`under 0.005`	`over 0.02`
p95 latency in ms	`under 500`	`over 2000`
Queue depth	`under 100`	`over 1000`
Replica count	`over 1`	`under 1`

The strict-comparison rule applies (see threshold operators in the Documentation tab).