TrainingsPCA CertificationTeam PlansSign In

Query Language

To make use of the collected data, Prometheus implements its own query language called PromQL. PromQL is a functional language that is optimized for evaluating flexible and efficient computations on time series data. In contrast to SQL-like languages, PromQL is only used for reading data, not for inserting, updating, or deleting data (this happens outside of the query engine).

PromQL in the Prometheus architecture

You can learn everything about PromQL in our "Understanding PromQL" training, but we will look at a few simple examples here.

Let's say you have a set of HTTP request counter time series with the metric name http_requests_total, a status label indicating the response status code, and a path label indicating the HTTP path:

http_requests_total{status="200", path="/path-a"}   4714
http_requests_total{status="200", path="/path-b"}   7739
http_requests_total{status="200", path="/path-c"}   9605
http_requests_total{status="403", path="/path-a"}      7
http_requests_total{status="403", path="/path-b"}      3
http_requests_total{status="403", path="/path-c"}      0
http_requests_total{status="500", path="/path-a"}    887
http_requests_total{status="500", path="/path-b"}      5
http_requests_total{status="500", path="/path-c"}    110

The following query would select the total count of all handled HTTP requests that resulted in a 500 status code:

http_requests_total{status="500"}

Since the absolute value of a cumulative counter value is rarely useful, the following query tells you the per-second rate of increase for each selected counter series, as averaged over a window of 5 minutes:

rate(http_requests_total{status="500"}[5m])

And you can calculate the ratio of the various per-path status="500" error rates as compared to the total rate of requests for the same HTTP path like this:

  sum by(path) (rate(http_requests_total{status="500"}[5m]))
/
  sum by(path) (rate(http_requests_total[5m]))

You can also select only the per-path error rates ratios that are larger than 5%:

  sum by(path) (rate(http_requests_total{status="500"}[5m]))
/
  sum by(path) (rate(http_requests_total[5m]))
* 100
> 5

These are some of the more common constructs you will see in PromQL, but the language has many more features and capabilities.

You can learn more about how PromQL works and how you can build queries yourself in our "Understanding PromQL" training.