HTTP API

在Prometheus服务器上的/ api / v1路径下可以访问当前稳定的HTTP API。

格式概述

API返回是JSON格式。每个成功的API请求都将返回2xx的状态码。
所有无效的请求，API会返回一个JSON错误对象，并返回以下HTTP响应码：

400 Bad Request。当参数错误或者缺失时。
422 Unprocessable Entity。当一个表达式不能被执行时。
503 Service Unavailable。当查询超时或者中断时。

JSON返回格式如下所示：

{
  "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>"]
}

输入时间戳可以为RFC3339格式或者Unix时间戳格式。输出时间戳以Unix时间戳方式呈现。

<series_selector>占位符提供Prometheus时间序列选择器像http_requests_total或者http_requests_total{method=~"^GET|POST$"}，需要在URL中编码传输。

占位符指的是[0-9] + [smhdwy]形式的Prometheus持续时间字符串。例如，5m表示5分钟的持续时间。
占位符引用布尔值（字符串true和false）。

表达式查询

通过 HTTP API 我们可以分别通过 /api/v1/query 和 /api/v1/query_range 查询 PromQL 表达式当前或者一定时间范围内的计算结果。

瞬时查询

瞬时向量的http restful api查询：

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

url查询参数：

query = ：Prometheus表达式查询字符串。
time= ：执行时间戳。可缺省。
timeout = ：执行超时时间设置，默认由-query.timeout标志设置。

如果省略time参数，则使用当前服务器时间。

您可以使用POST方法和Content-Type：application / x-www-form-urlencoded标头直接在请求正文中对这些参数进行URL编码。在指定可能违反服务器端URL字符限制的大型查询时，这是非常有用的。
查询结果的数据部分具有以下格式：

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

是指查询结果数据，其具有不同的格式，具体取决于resultType。请参阅表达式查询结果格式。

下面例子执行了在2015-07-01T20:10:51.781Z时刻的up表达式：

$ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
   "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" ]
         }
      ]
   }
}

区间数据查询

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

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

url查询参数：

query = ：Prometheus表达式查询字符串。
start = ：开始时间戳。
end= ：结束时间戳。
step = ：查询时间步长，范围时间内每step秒执行一次。
timeout = ：超时设置。可缺省。默认为-query.timeout标志的值并受其限制。

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

有关占位符的格式，请参阅区间向量结果格式。
下面例子评估的查询条件up，且30s范围的查询，步长是15s。

$ 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" ]
            ]
         }
      ]
   }
}

元数据查询

通过标签匹配器找到metric列表

以下表达式返回与特定标签集匹配的时间序列列表：
url查询参数：

match [] = ：选择器是series_selector。这个参数个数必须大于等于1。
start = ：开始时间戳。
end= ：结束时间戳。

您可以使用POST方法和Content-Type：application / x-www-form-urlencoded标头直接在请求正文中对这些参数进行URL编码。在指定可能违反服务器端URL字符限制的大型或动态数量的系列选择器时，这是非常有用的。
查询结果的数据部分包含一个对象列表，这些对象包含标识每个系列的标签名称/值对。
以下示例返回与选择器up或process_start_time_seconds {job =“prometheus”}匹配的所有时间序列数据：

$ curl -g 'http://localhost:9090/api/v1/series?' -d 'match[]=up' -d 'match[]=process_start_time_seconds{job="prometheus"}'
{
   "status" : "success",
   "data" : [
      {
         "__name__" : "up",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      },
      {
         "__name__" : "up",
         "job" : "node",
         "instance" : "localhost:9091"
      },
      {
         "__name__" : "process_start_time_seconds",
         "job" : "prometheus",
         "instance" : "localhost:9090"
      }
   ]
}

获取标签名称

标签名称的http restful api查询：

GET /api/v1/labels
POST /api/v1/labels

JSON响应的数据部分是字符串标签名称的列表。
例如：

$ curl 'localhost:9090/api/v1/labels'
{
    "status": "success",
    "data": [
        "__name__",
        "call",
        "code",
        "config",
        "dialer_name",
        "endpoint",
        "event",
        "goversion",
        "handler",
        "instance",
        "interval",
        "job",
        "le",
        "listener_name",
        "name",
        "quantile",
        "reason",
        "role",
        "scrape_job",
        "slice",
        "version"
    ]
}

查询标签值

下面这个例子，返回了带有指定标签的标签值列表：

GET /api/v1/label/<label_name>/values

这个返回JSON结果的data部分是带有label_name=job的值列表：

$ curl http://localhost:9090/api/v1/label/job/values
{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}

表达式查询结果格式

表达式查询结果，在data部分的result部分中，返回下面的数据。\<sample_value\>占位符有数值样本值。JSON不支持特殊浮点值，例如：NaN, Inf和-Inf。因此样本值返回结果是字符串，不是原生的数值。

区间向量

区间向量查询返回的result类型是一个matrix矩阵。下面返回的结果是result部分的数据格式：

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

瞬时矢量

瞬时向量查询返回result类型是vector。下面是result部分的数据格式

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

标量

标量查询返回result类型是scalar。下面是result部分的数据格式：

[ <unix_time>, "<scalar_value>" ]

字符串

字符串查询返回的result类型是string。下面是result部分的数据格式：

[ <unix_time>, "<string_value>" ]

Targets目标

通过以下路径可返回当前状态下prometheus的目标发现的概述。

GET /api/v1/targets

激活目标和删除目标都是响应的一部分。标签表示重新标记发生后的标签集。 discoveredLabels表示在发生重新标记之前在服务发现期间检索到的未修改标签。

$ curl http://localhost:9090/api/v1/targets
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9090",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "prometheus"
        },
        "labels": {
          "instance": "127.0.0.1:9090",
          "job": "prometheus"
        },
        "scrapeUrl": "http://127.0.0.1:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "health": "up"
      }
    ],
    "droppedTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9100",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "node"
        },
      }
    ]
  }
}

规则

/ rules API端点返回当前加载的警报和记录规则列表。此外，它还返回由每个警报规则的Prometheus实例触发的当前活动警报。
由于/ rules端点为新开发端点，因此它没有像API/v1一样的稳定性保证。

GET /api/v1/rules

$ curl http://localhost:9090/api/v1/rules
{
    "data": {
        "groups": [
            {
                "rules": [
                    {
                        "alerts": [
                            {
                                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                                "annotations": {
                                    "summary": "High request latency"
                                },
                                "labels": {
                                    "alertname": "HighRequestLatency",
                                    "severity": "page"
                                },
                                "state": "firing",
                                "value": 1
                            }
                        ],
                        "annotations": {
                            "summary": "High request latency"
                        },
                        "duration": 600,
                        "health": "ok",
                        "labels": {
                            "severity": "page"
                        },
                        "name": "HighRequestLatency",
                        "query": "job:request_latency_seconds:mean5m{job=\"myjob\"} > 0.5",
                        "type": "alerting"
                    },
                    {
                        "health": "ok",
                        "name": "job:http_inprogress_requests:sum",
                        "query": "sum(http_inprogress_requests) by (job)",
                        "type": "recording"
                    }
                ],
                "file": "/rules.yaml",
                "interval": 60,
                "name": "example"
            }
        ]
    },
    "status": "success"
}

报警

/ alerts端点返回所有活动警报的列表。
由于/ alerts端点为新开发端点，因此它没有像API/v1一样的稳定性保证。

GET /api/v1/alerts

$ curl http://localhost:9090/api/v1/alerts
{
    "data": {
        "alerts": [
            {
                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                "annotations": {},
                "labels": {
                    "alertname": "my-alert"
                },
                "state": "firing",
                "value": 1
            }
        ]
    },
    "status": "success"
}

查询目标元数据

以下端点返回相关target抓取的metric的元数据。实验中，将来可能会发生变化。

GET /api/v1/targets/metadata

url查询参数：

match_target = ：通过标签集匹配目标的标签选择器。如果缺省则选择所有目标。
metric = ：用于检索元数据的metric。如果缺省，则检索所有metric元数据。
limit = ：要匹配的最大目标数。

查询结果的数据部分包括一个含有metric元数据和目标标签集对象列表。
以下示例从前两个目标返回go_goroutines指标的所有元数据条目，标签为job =“prometheus”。

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'metric=go_goroutines' \
    --data-urlencode 'match_target={job="prometheus"}' \
    --data-urlencode 'limit=2'
{
  "status": "success",
  "data": [
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9091",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    }
  ]
}

以下示例返回标签instance=“127.0.0.1:9090”的所有目标的所有metric的元数据。

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'match_target={instance="127.0.0.1:9090"}'
{
  "status": "success",
  "data": [
    // ...
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_treecache_zookeeper_failures_total",
      "type": "counter",
      "help": "The total number of ZooKeeper failures.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_tsdb_reloads_total",
      "type": "counter",
      "help": "Number of times the database reloaded block data from disk.",
      "unit": ""
    },
    // ...
  ]
}

Alertmanagers

以下端点返回Prometheus alertmanager发现的当前状态概述：

GET /api/v1/alertmanagers

激活和丢弃的Alertmanagers都是响应的一部分。

$ curl http://localhost:9090/api/v1/alertmanagers
{
  "status": "success",
  "data": {
    "activeAlertmanagers": [
      {
        "url": "http://127.0.0.1:9090/api/v1/alerts"
      }
    ],
    "droppedAlertmanagers": [
      {
        "url": "http://127.0.0.1:9093/api/v1/alerts"
      }
    ]
  }
}

状态

以下状态端点显示当前的Prometheus配置。

配置

以下端点返回当前加载的配置文件：

GET /api/v1/status/config

配置作为转储的YAML文件返回。由于YAML库的限制，不包括YAML注释。

$ curl http://localhost:9090/api/v1/status/config
{
  "status": "success",
  "data": {
    "yaml": "<content of the loaded config file in YAML>",
  }
}

标志

以下端点返回Prometheus配置的标志值：

GET /api/v1/status/flags

所有值都以“字符串”的形式出现。

$ curl http://localhost:9090/api/v1/status/flags
{
  "status": "success",
  "data": {
    "alertmanager.notification-queue-capacity": "10000",
    "alertmanager.timeout": "10s",
    "log.level": "info",
    "query.lookback-delta": "5m",
    "query.max-concurrency": "20",
    ...
  }
}

TSDB管理API （公测期间暂不开发）

这些是为高级用户公开数据库功能的API。除非设置了—web.enable-admin-api，否则不会启用这些API。
我们还公开了一个gRPC API，其定义可以在这里找到。实验中，将来可能会发生变化。

快照

快照会将所有当前数据的快照创建到TSDB数据目录下的snapshots / - 中，并将该目录作为响应返回。它可以选择跳过仅存在于head block中但尚未压缩到磁盘的快照数据。

POST /api/v1/admin/tsdb/snapshot?skip_head=<bool>
PUT /api/v1/admin/tsdb/snapshot?skip_head=<bool>

$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

快照现在位于 / snapshots / 20171210T211224Z-2be650b6d019eb54

删除系列

DeleteSeries删除时间范围内所选系列的数据。实际数据仍然存在于磁盘上，并在将来的压缩中清除，或者可以通过点击Clean Tombstones端点来明确清理。
如果成功，则返回204。

POST /api/v1/admin/tsdb/delete_series
PUT /api/v1/admin/tsdb/delete_series

网址查询参数：

match [] = ：选择要删除的系列的重复标签匹配器参数。必须至少提供一个match []参数。
start = ：开始时间戳。可选，默认为最短可能时间。
end= ：结束时间戳。可选，默认为最长可能时间。

开始和结束时间缺省将清除数据库中匹配系列的所有数据。
例：

$ curl -X POST \
  -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'

Clean Tombstones

Clean Tombstones从磁盘中删除已删除的数据并清理现有的逻辑。 clean Tombstones删除系列后使用以释放空间。
如果成功，则返回204。

POST /api/v1/admin/tsdb/clean_tombstones
PUT /api/v1/admin/tsdb/clean_tombstones

此端点不需要参数和正文。

$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

HTTP API_promQL参考_时序数据库 Prometheus® 版_时序时空数据库TSDB

HTTP API

HTTP API

格式概述

表达式查询

瞬时查询

区间数据查询

元数据查询

通过标签匹配器找到metric列表

获取标签名称

查询标签值

表达式查询结果格式

区间向量

瞬时矢量

标量

字符串

Targets目标

规则

报警

查询目标元数据

Alertmanagers

状态

配置

标志

TSDB管理API （公测期间暂不开发）

快照

删除系列

Clean Tombstones

版权声明

评论

HTTP API_promQL参考_时序数据库 Prometheus&reg; 版_时序时空数据库TSDB

HTTP API

HTTP API

格式概述

表达式查询

瞬时查询

区间数据查询

元数据查询

通过标签匹配器找到metric列表

获取标签名称

查询标签值

表达式查询结果格式

区间向量

瞬时矢量

标量

字符串

Targets目标

规则

报警

查询目标元数据

Alertmanagers

状态

配置

标志

TSDB管理API （公测期间暂不开发）

快照

删除系列

Clean Tombstones

版权声明

评论

HTTP API_promQL参考_时序数据库 Prometheus® 版_时序时空数据库TSDB