grafana +Prometheus API 使用

Prometheus API 使用了 JSON 格式的响应内容。 输入时间戳可以由 RFC3339 格式或者 Unix 时间戳提供，后面可选的小数位可以精确到亚秒级别。输出时间戳以 Unix 时间戳的方式呈现。所有的 API请求返回的格式均使用以下的 JSON 格式：

{
  "status": "success" | "error",
  "data": <data>,
  
  // Only set if status is "error". 
  // additional data.
  "errorType": "<string>",
  "error": "<string>"
}

表达式查询

我们可以分别通过 /api/v1/query 和 /api/v1/query_range 查询 PromQL 表达式瞬时或者一定时间范围内的查询结果。当 API 调用成功后，Prometheus 会返回 JSON 格式的响应内容。

表达式查询结果会在 data 部分的 result 字段中返回以下的响应值。响应数据格式一共分为四种：

瞬时向量

通过使用 QUERY API 我们可以查询 PromQL 在特定时间点下的计算结果。

URL 请求参数：

query=<string> : PromQL 表达式。
time=<rfc3339 | unix_timestamp> : 用于指定用于计算 PromQL的时间戳。可选参数，默认情况下使用当前系统时间。

当 API 调用成功后，Prometheus 会返回 JSON 格式的响应内容，并且在 data 部分返回查询结果。data 部分格式如下：

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

data 返回查询结果。value指的是查询结果数据，具体的格式取决于resultType，不同的结果类型，会有不同的结果数据格式。瞬时数据的resultType为vector。区间数据的resultType为matrix。当返回数据类型 resultType 为 vector 时，是一组时间序列，每个时间序列包含单个样本。result 响应格式如下：

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "value": [ <unix_time>, "<sample_value>" ]
  },
  ...
]

这个 url 的查询结果为当前时间node_disk_io_now指标的查询结果。

Url="http://10.4.**.**:32075/api/v1/query?query=node_disk_io_now";

{
    "status":"success",
    "data":{
        "resultType":"vector",
        "result":[
            {
                "metric":{
                    "__name__":"node_disk_io_now",
                    "app":"prometheus",
                    "component":"node-exporter",
                    "device":"dm-0",
                    "instance":"10.4.**.**:9100",
                    "job":"kubernetes-endpoints",
                    "kubernetes_name":"prometheus-node-exporter",
                    "kubernetes_namespace":"monitoring"
                },
                "value":[
                    1542939382.369,
                    "0"
                ]
            },
            {
                "metric":{
                    "__name__":"node_disk_io_now",
                    "app":"prometheus",
                    "component":"node-exporter",
                    "device":"dm-1",
                    "instance":"10.4.**.**:9100",
                    "job":"kubernetes-endpoints",
                    "kubernetes_name":"prometheus-node-exporter",
                    "kubernetes_namespace":"monitoring"
                },
                "value":[
                    1542939382.369,
                    "0"
                ]
            }
        ]
    }
}

注1：如果只是简单输入 http://ip:port/api/v1/query 会返回：

{"status":"error","errorType":"bad_data","error":"parse error at char 1: no expression found in input"}

• 1

注2：如果 time 参数缺省，则使用当前服务器时间。

注3：value 的值是时间戳和当前的值

区间向量

通过使用 QUERY_RANGE API 我们则可以直接查询 PromQL表达式在一段时间内返回的计算结果。

URL 请求参数：

query=<string> : PromQL 表达式。
start=<rfc3339 | unix_timestamp> : 起始时间戳。
end=<rfc3339 | unix_timestamp> : 结束时间戳。
step=<duration | float> : 查询时间步长，时间区间内每 step 秒执行一次。

当使用 QUERY_RANGE API 查询 PromQL 表达式时，返回结果一定是一个区间向量：

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

当返回数据类型 resultType 为 matrix 时，是一组时间序列，每个时间序列包含一段时间范围内的样本数据。result 响应格式如下：

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ]
  },
  ...
]

这个 url 的查询结果为2018-11-22 17:20:23到2018-11-22 17:20:33这十秒内 ，指标http_requests_total的查询结果：

Url="http://10.4.54.31:32075/api/v1/query_range?query=http_requests_total&start=1542878423.447&end=1542878433.447&step=10s";

{
    "status":"success",
    "data":{
        "resultType":"matrix",
        "result":[
            {
                "metric":{
                    "__name__":"http_requests_total",
                    "code":"200",
                    "handler":"prometheus",
                    "instance":"node1",
                    "job":"kubernetes-nodes",
                    "method":"get"
                },
                "values":[
                    [
                        1542878423.447,
                        "86031"
                    ],
                    [
                        1542878433.447,
                        "86032"
                    ]
                ]
            }
        ]
    }
}

 

标量

当返回数据类型 resultType 为 scalar 时，是一个浮点型的数据值。result 响应格式如下：

[ <unix_time>, "<scalar_value>" ]

字符串

当返回数据类型 resultType 为 string 时，是一个简单的字符串值。result 响应格式如下：

[ <unix_time>, "<string_value>" ]

字符串类型的响应内容格式和标量相同。

元数据查询

标签选择器查询

我们可以通过 /api/v1/series 返回与特定标签集匹配的时间序列列表。

URL 请求参数：

match[]=<series_selector> : 表示标签选择器是 series_selector。必须至少提供一个 match[] 参数。
start=<rfc3339 | unix_timestamp> : 起始时间戳。
end=<rfc3339 | unix_timestamp> : 结束时间戳。

如我们查出所有job名为kubernetes-cadvisor的up指标和所有kubernetes_name名为kube-state-metrics的process_start_time_seconds指标：

Url="http://10.4.**.**:32075/api/v1/series?match[]=up{job="kubernetes-cadvisor"}&match[]=process_start_time_seconds{kubernetes_name="kube-state-metrics"}";

{
    "status":"success",
    "data":[
        {
            "__name__":"process_start_time_seconds",
            "app":"prometheus",
            "component":"node-exporter",
            "instance":"10.4.**.**:9100",
            "job":"kubernetes-endpoints",
            "kubernetes_name":"prometheus-node-exporter",
            "kubernetes_namespace":"monitoring"
        },
        {
            "__name__":"up",
            "app":"kube-state-metrics",
            "instance":"10.233.102.139:8080",
            "job":"kubernetes-endpoints",
            "kubernetes_name":"kube-state-metrics",
            "kubernetes_namespace":"monitoring"
        }
    ]
}

标签值查询

我们可以通过 /api/v1/label/‘label_name’/values 返回带有指定标签的标签值列表。

如我们查出所有标签名为 job 的标签值:

Url="http://10.4.**.**:32075/api/v1/label/job/values";

{
    "status":"success",
    "data":[
        "kubernetes-cadvisor",
        "kubernetes-endpoints",
        "kubernetes-nodes",
        "kubernetes-pods"
    ]
}