このページはPrometheus公式ドキュメント和訳+αの一部です。

HTTP API

現状の安定版HTTP APIは、Prometheusサーバーの/api/v1でアクセスできる。非破壊的な追加がこのエンドポイントに追加されることがある。

フォーマット概要

成功したAPIリクエストはステータスコード2xxを返す。

APIハンドラに届いた不正なリクエストは、JSONエラーオブジェクトと以下のHTTPレスポンスコードの1つを返す。

400 Bad Request パラメーターが欠けていたり間違っている場合
422 Unprocessable Entity 式が実行できない場合(RFC4918)
503 Service Unavailable クエリがタイムアウトしたりアボートした場合

APIエンドポイントに到達する前に起きたエラーに対しては、2xxでない他のコードが返される場合もある。

リクエストの実行を妨げなかったエラーがあると、警告の配列が返される場合もある。収集に成功した全てのデータは、データフィールド入れて返される。

JSONレスポンスのフォーマットは以下の通りである。

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

  // statusがerrorの場合のみセットされる。
  // その場合でも、dataフィールドは追加のデータを保持している場合がある。
  "errorType": "<string>",
  "error": "<string>",

  // リクエスト実行中に警告があった場合のみセットされる。
  // その場合でも、dataフィールドは追加のデータを保持している場合がある。
  "warnings": ["<string>"]
}

入力のタイムスタンプは、RFC3339のフォーマットまたは秒で表したUnixタイムスタンプ（オプションで秒未満の精度のために少数をつける）として与えることができる。出力のタイムスタンプは、常に、秒で表されたUnixタイムスタンプである。

繰り返される可能性があるクエリパラメーターの名前は[]で終わる。

プレースホルダー<series_selector>は、http_requests_totalやhttp_requests_total{method=~"(GET|POST)"}のような時系列セレクターを表し、URLエンコードされてなければいけない。

プレースホルダー<duration>は、[0-9]+[smhdwy]という形式の時間幅の文字列を表す。例えば、5mは5分の時間幅を表す。

プレースホルダー<bool>は、ブール値（文字列でtrueとfalse）を表す。

Expression queries

クエリ言語の式は、時間のある一点で評価されるかもしれないし、時間幅に渡って評価されるかもしれない。以下のセクションでは、それぞれのタイプのクエリのためのAPIエンドポイントについて説明する。

Instant queries

以下のエンドポイントは、時間の一点でのinstantクエリを評価する。

GET /api/v1/query

URLクエリパラメーターは以下の通り。

query=<string>: Prometheusのexpressionのクエリの文字列
time=<rfc3339 | unix_timestamp>: 評価時間（オプション）
timeout=<duration>: 評価のタイムアウト（オプション）。-query.timeoutフラグの値がデフォルトであり、かつ上限となる。

timeパラメーターが省略されると、現在のサーバー時間が利用される。

結果のdataセクションは以下のフォーマットである。

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

<value>は、クエリの結果のデータを表しており、resultTypeに応じて、様々なフォーマットになる。後述の「結果フォーマット」を参照すること。

以下の例は、式upを2015-07-01T20:10:51.781Zの時点で評価している。

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

Range queries

以下のエンドポイントは、ある時間幅に渡ってクエリの式を評価する。

GET /api/v1/query_range

URLクエリパラメーターは以下の通り。

query=<string>: Prometheusのexpressionのクエリの文字列
start=<rfc3339 | unix_timestamp>: 開始時刻のタイムスタンプ
end=<rfc3339 | unix_timestamp>: 終了時刻のタイムスタンプ
step=<duration | float>: クエリ解像度のステップ幅（durationフォーマットまたは秒数の少数）
timeout=<duration>: 評価のタイムアウト（オプション）。-query.timeoutフラグの値がデフォルトであり、かつ上限となる。

結果のdataセクションは以下のフォーマットである。

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

プレイスホルダー<value>のフォーマットについては、range-vector結果フォーマットを参照すること。

以下の例は、式upを30秒の時間幅にかけて15秒の解像度で評価している。

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

メタデータのクエリ

ラベルマッチャーによる時系列の検索

以下のエンドポイントはラベル集合にマッチする時系列のリストを返す。

GET /api/v1/series

URLクエリパラメーターは以下の通り。

atch[]=<series_selector>: 時系列を選択するためのセレクター引数。少なくとも1つのmatch[]を指定する必要がある
start=<rfc3339 | unix_timestamp>: 開始時刻のタイムスタンプ
end=<rfc3339 | unix_timestamp>: 終了時刻のタイムスタンプ

結果のdataセクションは、各時系列を特定するラベル名/値を含むオブジェクトのリストである。

以下の例は、セレクターupまたはprocess_start_time_seconds{job="prometheus"}にマッチする全ての時系列を返す。

$ curl -g 'http://localhost:9090/api/v1/series?match[]=up&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"
      }
   ]
}

ラベル名の取得

以下のエンドポイントはラベル名のリストを返す。

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

JSONレスポンスのdataセクションは、ラベル名の文字列のリストである。

以下に例を示す。

$ 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セクションは、ラベル値の文字列のリストである。

この例は、ラベルjobに対する全てのラベル値を取得している。

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

式のクエリの結果フォーマット

式のクエリは、dataセクションのresultプロパティに以下のレスポンスを入れて返す。プレースホルダー<sample_value>は、数値のサンプル値である。 JSONは、NaNやInf、-Infといった特別な値をサポートしないので、生の数値の代わりに、クオートされたJSON文字列として送信される。

Range vectors

Range vectorは、結果タイプmatrixとして返される。対応するresultプロパティは、以下のフォーマットとなる。

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

Instant vectors

Instant vectorは、結果タイプvectorとして返される。対応するresultプロパティは、以下のフォーマットとなる。

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

スカラー

スカラーは、結果タイプscalarとして返される。対応するresultプロパティは、以下のフォーマットとなる。

[ <unix_time>, "<scalar_value>" ]

文字列

文字列は、結果タイプstringとして返される。対応するresultプロパティは、以下のフォーマットとなる。

[ <unix_time>, "<string_value>" ]

監視対象

以下のエンドポイントは、監視対象の検出の現在の状態の概要を返す。

GET /api/v1/targets

activeなターゲットとdropされたターゲットのどちらも含まれる。 labelsは、リラベルが起きた後のラベル集合を表す。 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"
        },
      }
    ]
  }
}

ルール

APIエンドポイント/rulesは、現在読み込まれているアラーティングルールとレコーディングルールのリストを返す。 Prometheusが起こした各アラーティングルールの現在activeなアラートも返す。

エンドポイント/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は、全てのactiveなアラートのリストを返す。

エンドポイント/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"
}

Querying target metadata

下記のエンドポイントは、現在取得ずみのメトリクスに関するメタデータを返す。これは、実験的であり、将来的には変更される可能性がある。

GET /api/v1/targets/metadata

URLクエリパラメーターは以下の通り。

match_target=<label_selectors>: ラベル集合でターゲットとマッチングをするラベルセレクター。空にすると全てのターゲットが選択される
metric=<string>: メタデータを取得する対象のメトリック名。空にすると全てのメトリックのメタデータが選択される
limit=<number>: マッチングするターゲットの最大数

クエリの結果のdata部分は、メトリックのメタデータとターゲットのラベル集合を含むオブジェクトのリストから成る。

以下の例は、最初の2つのターゲットのメトリック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"を持つ全てのターゲットの全てのメトリックに対するメタデータを返す。

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

以下のエンドポイントは、Alertmanager検出の現在の状況の概要を返す。

GET /api/v1/alertmanagers

activeなAlertmanagerとdropされたAlertmanagerのどちらも結果に含まれる。

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

Status

以下のstatusエンドポイントは、Prometheusの設定を出力する。

Config

以下のエンドポイントは、現在読み込まれている設定ファイルを返す。

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>",
  }
}

Flags

以下のエンドポイントは、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",
    ...
  }
}

New in v2.2

TSDB Admin APIs

これらは、上級ユーザーのためにデータベースの機能を出力するAPIである。 --web.enable-admin-apiがセットされていなければ有効ではない。

gRPC APIも公開しており、ここに定義がある。これは、実験的なものであり、将来的には変更される可能性がある。

スナップショット

スナップショットは、TSDBのデータディレクトリの下のsnapshots/<datetime>-<rand>に全ての現在のデータのスナップショットを作成し、そのディレクトリを返す。オプションで、ヘッドブロックだけにありまだディスクにコンパクト化されていないデータのスナップショットをスキップする。

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

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

このスナップショットは<data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54にある。

New in v2.1

時系列の削除

DeleteSeriesは、ある時間幅にある選択された時系列のデータを削除する。実際のデータはディスクに存在し続けて、その後のコンパクションで片付けられるか、Clean Tombstonesエンドポイントを叩くことで片付けられる。

成功すると204が返される。

POST /api/v1/admin/tsdb/delete_series

URLクエリパラメーターは以下の通り。

match[]=<series_selector>: 時系列を選択するためのセレクター引数。少なくとも1つのmatch[]を指定する必要がある
start=<rfc3339 | unix_timestamp>: 開始時刻のタイムスタンプ。オプションでデフォルトは可能な限り最小の時刻
end=<rfc3339 | unix_timestamp>: 終了時刻のタイムスタンプ。オプションでデフォルトは可能な限り最大の時刻

開始時刻と終了時刻を指定しないと、データベース中のマッチした時系列の全てのデータが削除される。

例

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

New in v2.1

Clean Tombstones

CleanTombstonesは、削除済みのデータをディスクから削除し、存在するtombstonesを一掃する。これは、時系列を削除した後に、ディスクスペースを空けるために利用される。

成功すると204が返される。

POST /api/v1/admin/tsdb/clean_tombstones

パラメーターやレスポンスボディはない。

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

New in v2.1

参考リンク

HTTP API | Prometheus

和訳活動の支援

Prometheusドキュメント和訳が役に立った方は、以下QRコードからPayPayで活動を支援して頂けるとありがたいです。

PayPayによる支援用QRコード — 上のQRコードからPayPayによる支援

it-engineer’s blog

HTTP API - Prometheusドキュメント

HTTP API

フォーマット概要

Expression queries

Instant queries

Range queries

メタデータのクエリ

ラベルマッチャーによる時系列の検索

ラベル名の取得

ラベル値のクエリ

式のクエリの結果フォーマット

Range vectors

Instant vectors

スカラー

文字列

監視対象

ルール

アラート

Querying target metadata

Alertmanagers

Status

Config

Flags

TSDB Admin APIs

スナップショット

時系列の削除

Clean Tombstones

参考リンク

おすすめ書籍

和訳活動の支援