The current stable HTTP API of Prometheus can be accessed via /api/v1.
API Response Format
The Prometheus API uses JSON format for response content. When the API call is successful, it will return a 2xx HTTP status code. Conversely, when the API call fails, it may return the following different HTTP status codes:
-
404 Bad Request: When parameters are incorrect or missing.
-
422 Unprocessable Entity: When the expression cannot be executed.
-
503 Service Unavailable: When the request times out or is interrupted.
All API requests use the following JSON format:
{"status": "success" | "error","data": <data>, // Only set if status is "error". The data field may still hold // additional data."errorType": "<string>","error": "<string>"}Using PromQL in the HTTP API
Through the HTTP API, we can query the current or a specified time range calculation results of the PromQL expression via /api/v1/query and /api/v1/query_range.
Instant Data Query
By using the QUERY API, we can query the calculation results of PromQL at a specific point in time.
GET /api/v1/queryURL Request Parameters:
-
query=: PromQL expression.
-
time=: Used to specify the timestamp for calculating PromQL. Optional parameter, defaults to the current system time.
-
timeout=: Timeout setting. Optional parameter, defaults to the global setting of -query,timeout.
For example, using the following expression to query the result of the expression up at the time point 2015-07-01T20:10:51.781Z:
Response Data Type
When the API call is successful, Prometheus will return a JSON formatted response, as shown in the previous section. The query results are returned in the data node. The format of the data node is as follows:
{"resultType": "matrix" | "vector" | "scalar" | "string","result": <value>}The PromQL expression may return various data types, indicated by resultType in the response content, including:
Instant Vector: vector
When the returned data type resultType is vector, the result response format is as follows:
[{"metric": { "<label_name>": "<label_value>", ... },"value": [ <unix_time>, "<sample_value>" ]},...]Where metrics represent the characteristic dimensions of the current time series, and value contains only a unique sample.
Range Vector: matrix
When the returned data type resultType is matrix, the result response format is as follows:
Where metrics represent the characteristic dimensions of the current time series, and values contain a set of samples from the current event series.
Scalar: scalar
When the returned data type resultType is scalar, the result response format is as follows:
[ <unix_time>, "<scalar_value>" ]Since scalars do not have a time series, the result represents the value of a scalar at the current system time.
String: string
When the returned data type resultType is string, the result response format is as follows:
[ <unix_time>, "<string_value>" ]The response format for string type is the same as for scalar.
Range Data Query
Using the QUERY_RANGE API, we can directly query the calculation results of the PromQL expression over a period of time.
GET /api/v1/query_rangeURL Request Parameters:
-
query=: PromQL expression.
-
start=: Start time.
-
end=: End time.
-
step=: Query step size.
-
timeout=: Timeout setting. Optional parameter, defaults to the global setting of -query,timeout.
When using the QUERY_RANGE API to query the PromQL expression, the returned result is always a range vector:
{"resultType": "matrix","result": <value>}For example, using the following expression to query the result of the expression up over a 30-second range with a 15-second interval.
Learning arrangements are on!
Remember to ask the teacher for materials!
▲ 《Prometheus Practical Tutorial》 ▲
Scan the QR code below to learn in advance
