Skip to main content

PromQL Reference

PromQL (Prometheus Query Language) is the query language used to query metrics in Oodle. You write PromQL in Metrics Explore, in monitor definitions, and in dashboard panels.

Oodle's Explore page supports both a visual Builder mode and a raw Code mode. If you are new to PromQL, start with Builder mode - it generates valid PromQL for you.

Basic Concepts​

Metrics​

A metric is a named measurement collected at regular intervals. Examples: http_requests_total, node_memory_MemAvailable_bytes, gcp_compute_instance_cpu_utilization.

Labels​

Labels are key-value pairs that add dimensions to a metric. They let you filter and group results.

http_requests_total{method="GET", status="200"}

Label Matchers​

OperatorMeaning
=Equals
!=Not equals
=~Matches regex
!~Does not match regex
http_requests_total{status=~"5.."}

Selects all requests with a 5xx status code.

Range Vectors​

Append a duration in brackets to query data over a time window:

http_requests_total[5m]

Returns all samples of http_requests_total in the last 5 minutes. Range vectors are required by functions like rate() and increase().

Metric Types​

Counter​

A value that only goes up (resets to zero on restart). Use rate() or increase() to get meaningful values from counters - never plot a raw counter.

Examples: http_requests_total, node_network_receive_bytes_total

Gauge​

A value that can go up or down. Plot directly or use avg_over_time().

Examples: node_memory_MemAvailable_bytes, up

Histogram​

Tracks the distribution of values across buckets. Use histogram_quantile() to compute percentiles.

Examples: http_request_duration_seconds_bucket

Key Functions​

rate()​

Computes the per-second average rate of increase over a time window. Use it with counters.

rate(http_requests_total[5m])

Returns the average requests per second over the last 5 minutes.

increase()​

Returns the total increase in a counter over a time window. Equivalent to rate() multiplied by the window size, but easier to read when you want a count rather than a rate.

increase(http_requests_total[1h])

Returns the total number of requests in the last hour.

When to use rate() vs increase():

Use caseFunction
Requests per second for dashboardsrate()
Total count over a period for alertsincrease()
Comparing throughput across servicesrate()
"How many errors in the last hour?"increase()

sum()​

Adds values across time series. Combine with by to group.

sum(rate(http_requests_total[5m])) by (service)

Total request rate per service.

avg()​

Averages values across time series.

avg(node_cpu_utilization) by (instance)

histogram_quantile()​

Computes a quantile from histogram buckets.

histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

95th percentile request duration over the last 5 minutes.

avg_over_time()​

Averages a gauge over a time window.

avg_over_time(node_memory_MemAvailable_bytes[5m])

Operators​

Arithmetic​

+, -, *, / work between two series or a series and a scalar.

sum(http_requests_total{status="200"}) / sum(http_requests_total)

Success ratio across all requests.

Comparison​

>, >=, <, <=, ==, != filter series by value. Useful in alert conditions.

node_cpu_utilization > 0.8

Aggregation with by and without​

Group results by specific labels:

sum(rate(http_requests_total[5m])) by (status)

Or exclude labels from grouping:

sum(rate(http_requests_total[5m])) without (instance)

Offset Modifier​

Compare the current value to a previous time period:

rate(http_requests_total[5m]) - rate(http_requests_total[5m] offset 1w)

Difference between the current request rate and the same time last week.

Common Patterns​

Error rate as a percentage​

sum(rate(http_requests_total{status=~"5.."}[5m]))
/
sum(rate(http_requests_total[5m]))
* 100

Container CPU throttling​

rate(container_cpu_cfs_throttled_seconds_total[5m])

Memory usage percentage​

1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)

Average request duration from a histogram​

rate(http_request_duration_seconds_sum[5m])
/
rate(http_request_duration_seconds_count[5m])

GCP Metrics​

Metrics from the GCP integration are prefixed with gcp_. Browse available GCP metrics in Metrics Explore by searching for gcp_.

rate(gcp_loadbalancing_https_request_count[5m])

Support

If you need assistance or have any questions, please reach out to us through: