HTTP API - Prometheusドキュメント

このページは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_totalhttp_requests_total{method=~"(GET|POST)"}のような時系列セレクターを表し、URLエンコードされてなければいけない。

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

プレースホルダ<bool>は、ブール値(文字列でtruefalse)を表す。

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

refers to the query result data, which has varying formats depending on the resultType. See the expression query result formats. <value>は、クエリの結果のデータを表しており、resultTypeに応じて、様々なフォーマットになる。 後述の「結果のフォーマット」を参照すること。

以下の例は、式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クエリパラメーターは以下の通り。

  • match[]=<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"
   ]
}

結果のフォーマット

expressionクエリは、dataセクションのresultプロパティに以下のレスポンスを入れて返す。 プレースホルダ<sample_value>は、数値のサンプル値である。 JSONは、NaNInf-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>" ]
  },
  ...
]

Scalars

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

[ <unix_time>, "<scalar_value>" ]

Strings

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

[ <unix_time>, "<string_value>" ]

Targets

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

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

Rules

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

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

以下のエンドポイントは、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も公開しており、ここに定義がある。 これは、実験的なものであり、将来的には変更される可能性がある。

Snapshot

スナップショットは、TSDBのデータディレクトリの下のsnapshots/<datetime>-<rand>に全ての現在のデータのスナップショットを作成し、そのディレクトリを返す。 It will optionally skip snapshotting data that is only present in the head block, and which has not yet been compacted to disk.

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

Delete Series

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

参考リンク

和訳活動の支援

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

PayPayによる支援用QRコード
上のQRコードからPayPayによる支援
入門 Prometheus ―インフラとアプリケーションのパフォーマンスモニタリング

入門 Prometheus ―インフラとアプリケーションのパフォーマンスモニタリング

 
Prometheus: Up & Running: Infrastructure and Application Performance Monitoring

Prometheus: Up & Running: Infrastructure and Application Performance Monitoring

 
入門 監視 ―モダンなモニタリングのためのデザインパターン

入門 監視 ―モダンなモニタリングのためのデザインパターン

 
SRE サイトリライアビリティエンジニアリング ―Googleの信頼性を支えるエンジニアリングチーム

SRE サイトリライアビリティエンジニアリング ―Googleの信頼性を支えるエンジニアリングチーム