HTTP api for secondary development of prometheus

Prometheus has opened HTTP interfaces under the path of / api/v1, through which users can carry out secondary development.

1. Request & response format

1.JSON response format

Respond in JSON format.
If the API request succeeds, it returns a 2xx status code.
If the request fails, the following status codes will be returned according to the situation:

  • 400 Bad Request parameter missing or incorrect;
  • 422 Unprocessable Entity cannot execute the expression;
  • 503 Service Unavailable query timeout or abort.

Respond to JSON as follows:

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"]
}

2. Time stamp format

The time stamp in the output is the Unix time stamp in seconds. Therefore, if there is a time stamp in the request, it is recommended to use the Unix time stamp in seconds.

3. Other formats

Parameter names that can be queried repeatedly should be suffixed with [].

The < series {selector > placeholder refers to the Prometheus time series selector, such as HTTP {requests} or http {requests {method = ~ "(get | post)"} and requires URL encoding.

Placeholder refers to the Prometheus duration string. [0-9]+[smhdwy]. For example, 5m means a duration of 5 minutes.

Placeholders are Boolean values (strings true and false).

2. Expression Query

Through the interface, you can use promQL to query the value of an instant or a certain period of time,

1. Instant query

url address:

GET /api/v1/query
POST /api/v1/query

URL query parameters:

  • query= *Prometheus expression query string, required.
  • Time = < rfc3339 | unix_timestamp > * time stamp of the query, optional.
  • Timeout = * timeout, optional. The default is the value of the startup parameter - query.timeout flag, which is limited by the value of the flag.

Note:
If the time parameter is not filled in, the current server time is used.
Use the POST method and the content type: application / x-www-form-urlencoded header to URL these parameters directly in the request body.

Return result format:

{
  "resultType": "matrix" | "vector" | "scalar" | "string",
  "result": <value>
}

Example 1: query the metric provided by Prometheus

$ curl 'http://localhost:9090/api/v1/query?query=up
{
   "status" : "success",
   "data" : {
      "resultType" : "vector",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "value": [ 1435781451.781, "1" ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9100"
            },
            "value" : [ 1435781451.781, "0" ]
         }
      ]
   }
}

Example 2: querying with promQL

$ curl 'http://localhost:9090/api/v1/query?query=sum(time() - node_boot_time_seconds)

{
   "status": "success",
   "data":    {
      "resultType": "vector",
      "result": [      {
         "metric": {},
         "value":          [
            1.581498526305E9,
            "6767484.305000067"
         ]
      }]
   }
}

2. Scope query

ur address:

GET /api/v1/query_range
POST /api/v1/query_range

URL query parameters:

  • query=*Prometheus expression query string, required.
  • Start = < rfc3339| unix_timestamp > * start timestamp, required.
  • End = < rfc3339 | UNIX | timestamp > * end timestamp, required.
  • Step = < duration| float > * query step size in duration format or seconds.
  • Timeout = * timeout, optional. The default is the value of the startup parameter - query.timeout flag, which is limited by the value of the flag

The returned results may have the following fields:

{
  "resultType": "matrix",
  "result": <value>
}

Example 1:

$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
   "status" : "success",
   "data" : {
      "resultType" : "matrix",
      "result" : [
         {
            "metric" : {
               "__name__" : "up",
               "job" : "prometheus",
               "instance" : "localhost:9090"
            },
            "values" : [
               [ 1435781430.781, "1" ],
               [ 1435781445.781, "1" ],
               [ 1435781460.781, "1" ]
            ]
         },
         {
            "metric" : {
               "__name__" : "up",
               "job" : "node",
               "instance" : "localhost:9091"
            },
            "values" : [
               [ 1435781430.781, "0" ],
               [ 1435781445.781, "0" ],
               [ 1435781460.781, "1" ]
            ]
         }
      ]
   }
}

46 original articles published, 28 praised, 30000 visitors+
Private letter follow

Tags: JSON Unix curl encoding

Posted on Wed, 12 Feb 2020 05:25:16 -0800 by atstein