現在の安定版HTTP APIは、Prometheusサーバーの/api/v1でアクセスできます。破壊的ではない追加は、そのエンドポイントに追加されます。
APIレスポンス形式はJSONです。すべての成功したAPIリクエストは2xxステータスコードを返します。
APIハンドラーに到達する無効なリクエストは、JSONエラーオブジェクトと次のHTTPレスポンスコードのいずれかを返します。
400 Bad Request。422 Unprocessable Entity (RFC4918)。503 Service Unavailable。APIエンドポイントに到達する前に発生したエラーに対しては、他の2xx以外のコードが返される場合があります。
リクエストの実行を妨げないエラーがある場合は、警告の配列が返される場合があります。潜在的なクエリの問題（偽陽性である可能性もある）に対しては、情報レベルのアノテーションの配列が追加で返される場合があります。正常に収集されたすべてのデータは、dataフィールドに返されます。
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 set if there were warnings while executing the request.
// There will still be data in the data field.
"warnings": ["<string>"],
// Only set if there were info-level annnotations while executing the request.
"infos": ["<string>"]
}
一般的なプレースホルダーは次のように定義されます。
<rfc3339 | unix_timestamp>: 入力タイムスタンプは、RFC3339形式、または秒単位のUnixタイムスタンプ（小数点以下を含むサブ秒精度も可）のいずれかで指定できます。出力タイムスタンプは常に、秒単位のUnixタイムスタンプとして表されます。<series_selector>: http_requests_totalやhttp_requests_total{method=~"(GET|POST)"}のような、Prometheusの時系列セレクター。URLエンコードする必要があります。<duration>: Prometheusの期間文字列。例：5mは5分間の期間を表します。<bool>: ブール値（文字列trueとfalse）。注：繰り返し可能なクエリパラメーターの名前は、[]で終わります。
クエリ言語式は、単一の時点または時間範囲で評価できます。以下のセクションでは、各タイプの式クエリに対するAPIエンドポイントについて説明します。
次のエンドポイントは、単一の時点でのインスタントクエリを評価します。
GET /api/v1/query
POST /api/v1/query
URLクエリパラメーター
query=<string>: Prometheus式クエリ文字列。time=<rfc3339 | unix_timestamp>: 評価タイムスタンプ。省略可能。timeout=<duration>: 評価タイムアウト。省略可能。-query.timeoutフラグの値をデフォルトとし、その値を上限とします。timeパラメーターを省略した場合は、現在のサーバー時間が使用されます。
POSTメソッドとContent-Type: application/x-www-form-urlencodedヘッダーを使用して、これらのパラメーターをリクエスト本文に直接URLエンコードできます。これは、サーバー側のURL文字数制限を超える可能性のある大きなクエリを指定する場合に役立ちます。
クエリ結果のdataセクションは、次の形式です。
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
<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" ]
}
]
}
}
次のエンドポイントは、時間範囲にわたって式クエリを評価します。
GET /api/v1/query_range
POST /api/v1/query_range
URLクエリパラメーター
query=<string>: Prometheus式クエリ文字列。start=<rfc3339 | unix_timestamp>: 開始タイムスタンプ（包括的）。end=<rfc3339 | unix_timestamp>: 終了タイムスタンプ（包括的）。step=<duration | float>: クエリ解像度のステップ幅（duration形式または秒の浮動小数点数）。timeout=<duration>: 評価タイムアウト。省略可能。-query.timeoutフラグの値をデフォルトとし、その値を上限とします。POSTメソッドとContent-Type: application/x-www-form-urlencodedヘッダーを使用して、これらのパラメーターをリクエスト本文に直接URLエンコードできます。これは、サーバー側のURL文字数制限を超える可能性のある大きなクエリを指定する場合に役立ちます。
クエリ結果のdataセクションは、次の形式です。
{
"resultType": "matrix",
"result": <value>
}
<value>プレースホルダーの形式については、範囲ベクトル結果形式を参照してください。
次の例では、クエリ解像度を15秒として、30秒間の範囲にわたって式upを評価します。
$ 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" ]
]
}
]
}
}
次のエンドポイントは、PromQL式を整形された方法でフォーマットします。
GET /api/v1/format_query
POST /api/v1/format_query
URLクエリパラメーター
query=<string>: Prometheus式クエリ文字列。POSTメソッドとContent-Type: application/x-www-form-urlencodedヘッダーを使用して、これらのパラメーターをリクエスト本文に直接URLエンコードできます。これは、サーバー側のURL文字数制限を超える可能性のある大きなクエリを指定する場合に役立ちます。
クエリ結果のdataセクションは、フォーマットされたクエリ式を含む文字列です。フォーマットされた文字列では、コメントは削除されます。
次の例では、式foo/barをフォーマットします。
$ curl 'http://localhost:9090/api/v1/format_query?query=foo/bar'
{
"status" : "success",
"data" : "foo / bar"
}
Prometheusは、シリーズとそのラベルに関するメタデータをクエリするためのAPIエンドポイントのセットを提供します。
次のエンドポイントは、特定のラベルセットに一致する時系列のリストを返します。
GET /api/v1/series
POST /api/v1/series
URLクエリパラメーター
match[]=<series_selector>: 返すシリーズを選択する、繰り返されるシリーズセレクター引数。少なくとも1つのmatch[]引数を指定する必要があります。start=<rfc3339 | unix_timestamp>: 開始タイムスタンプ。end=<rfc3339 | unix_timestamp>: 終了タイムスタンプ。limit=<number>: 返されるシリーズの最大数。省略可能。0は無効。POSTメソッドとContent-Type: application/x-www-form-urlencodedヘッダーを使用して、これらのパラメーターをリクエスト本文に直接URLエンコードできます。これは、サーバー側のURL文字数制限を超える可能性のある多数の、または動的なシリーズセレクターを指定する場合に役立ちます。
クエリ結果のdataセクションは、各シリーズを識別するラベル名/値のペアを含むオブジェクトのリストで構成されます。
次の例では、セレクターupまたはprocess_start_time_seconds{job="prometheus"}のいずれかに一致するすべてのシリーズを返します。
$ curl -g 'http://localhost:9090/api/v1/series?' --data-urlencode 'match[]=up' --data-urlencode '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
URLクエリパラメーター
start=<rfc3339 | unix_timestamp>: 開始タイムスタンプ。省略可能。end=<rfc3339 | unix_timestamp>: 終了タイムスタンプ。省略可能。match[]=<series_selector>: ラベル名を読み取るシリーズを選択する、繰り返されるシリーズセレクター引数。省略可能。limit=<number>: 返されるシリーズの最大数。省略可能。0は無効。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
URLクエリパラメーター
start=<rfc3339 | unix_timestamp>: 開始タイムスタンプ。省略可能。end=<rfc3339 | unix_timestamp>: 終了タイムスタンプ。省略可能。match[]=<series_selector>: ラベル値を読み取るシリーズを選択する、繰り返されるシリーズセレクター引数。省略可能。limit=<number>: 返されるシリーズの最大数。省略可能。0は無効。JSONレスポンスのdataセクションは、文字列ラベル値のリストです。
この例では、jobラベルのすべてのラベル値をクエリします。
$ curl http://localhost:9090/api/v1/label/job/values
{
"status" : "success",
"data" : [
"node",
"prometheus"
]
}
これは**実験的**であり、将来変更される可能性があります。次のエンドポイントは、特定の時間範囲の有効なPromQLクエリのエクゼンプラーのリストを返します。
GET /api/v1/query_exemplars
POST /api/v1/query_exemplars
URLクエリパラメーター
query=<string>: Prometheus式クエリ文字列。start=<rfc3339 | unix_timestamp>: 開始タイムスタンプ。end=<rfc3339 | unix_timestamp>: 終了タイムスタンプ。$ curl -g 'http://localhost:9090/api/v1/query_exemplars?query=test_exemplar_metric_total&start=2020-09-14T15:22:25.479Z&end=2020-09-14T15:23:25.479Z'
{
"status": "success",
"data": [
{
"seriesLabels": {
"__name__": "test_exemplar_metric_total",
"instance": "localhost:8090",
"job": "prometheus",
"service": "bar"
},
"exemplars": [
{
"labels": {
"trace_id": "EpTxMJ40fUus7aGY"
},
"value": "6",
"timestamp": 1600096945.479
}
]
},
{
"seriesLabels": {
"__name__": "test_exemplar_metric_total",
"instance": "localhost:8090",
"job": "prometheus",
"service": "foo"
},
"exemplars": [
{
"labels": {
"trace_id": "Olp9XHlq763ccsfa"
},
"value": "19",
"timestamp": 1600096955.479
},
{
"labels": {
"trace_id": "hCtjygkIHwAN9vs4"
},
"value": "20",
"timestamp": 1600096965.489
}
]
}
]
}
式クエリは、dataセクションのresultプロパティに次のレスポンス値を返す可能性があります。<sample_value>プレースホルダーは数値サンプル値です。JSONは、NaN、Inf、-Infなどの特殊な浮動小数点値をサポートしていないため、サンプル値は生の数値ではなく、引用符で囲まれたJSON文字列として転送されます。
キー"histogram"と"histograms"は、実験的なネイティブヒストグラムがレスポンスに存在する場合にのみ表示されます。それらのプレースホルダー<histogram>については、下記のセクションで詳しく説明します。
範囲ベクトルは結果型matrixとして返されます。対応するresultプロパティは以下のフォーマットになります。
[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ],
"histograms": [ [ <unix_time>, <histogram> ], ... ]
},
...
]
各時系列は"values"キー、"histograms"キー、またはその両方を持つことができます。特定のタイムスタンプに対しては、浮動小数点数型またはヒストグラム型のサンプルが1つだけ存在します。
時系列はmetricでソートされて返されます。sortやsort_by_labelなどの関数は、範囲ベクトルには影響しません。
インスタントベクトルは結果型vectorとして返されます。対応するresultプロパティは以下のフォーマットになります。
[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ],
"histogram": [ <unix_time>, <histogram> ]
},
...
]
各時系列は"value"キーまたは"histogram"キーを持つことができますが、両方は持つことができません。
時系列は、sortやsort_by_labelなどの関数が使用されない限り、特定の順序で返される保証はありません。
スカラーの結果は結果型scalarとして返されます。対応するresultプロパティは以下のフォーマットになります。
[ <unix_time>, "<scalar_value>" ]
文字列の結果は結果型stringとして返されます。対応するresultプロパティは以下のフォーマットになります。
[ <unix_time>, "<string_value>" ]
上記で使用されている<histogram>プレースホルダーは、以下の形式でフォーマットされます。
ネイティブヒストグラムは実験的な機能であり、以下のフォーマットは変更される可能性があることに注意してください。
{
"count": "<count_of_observations>",
"sum": "<sum_of_observations>",
"buckets": [ [ <boundary_rule>, "<left_boundary>", "<right_boundary>", "<count_in_bucket>" ], ... ]
}
<boundary_rule>プレースホルダーは、0から3までの整数で、以下の意味を持ちます。
現在実装されているバケットスキーマでは、正のバケットは「左端オープン」、負のバケットは「右端オープン」、ゼロバケット（負の左端と正の右端を持つ）は「両端クローズ」であることに注意してください。
次のエンドポイントは、Prometheusのターゲット検出の現在の状態の概要を返します。
GET /api/v1/targets
アクティブなターゲットとドロップされたターゲットの両方が、デフォルトでレスポンスに含まれます。ドロップされたターゲットは、設定されている場合、keep_dropped_targets制限の対象となります。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"
},
"scrapePool": "prometheus",
"scrapeUrl": "http://127.0.0.1:9090/metrics",
"globalUrl": "http://example-prometheus:9090/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 0.050688943,
"health": "up",
"scrapeInterval": "1m",
"scrapeTimeout": "10s"
}
],
"droppedTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9100",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"__scrape_interval__": "1m",
"__scrape_timeout__": "10s",
"job": "node"
},
}
]
}
}
stateクエリパラメータを使用すると、アクティブなターゲットまたはドロップされたターゲットでフィルタリングできます（例：state=active、state=dropped、state=any）。フィルタリングされたターゲットに対しても空の配列が返されることに注意してください。その他の値は無視されます。
$ curl 'http://localhost:9090/api/v1/targets?state=active'
{
"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"
},
"scrapePool": "prometheus",
"scrapeUrl": "http://127.0.0.1:9090/metrics",
"globalUrl": "http://example-prometheus:9090/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 50688943,
"health": "up"
}
],
"droppedTargets": []
}
}
scrapePoolクエリパラメータを使用すると、スクレイププール名でフィルタリングできます。
$ curl 'http://localhost:9090/api/v1/targets?scrapePool=node_exporter'
{
"status": "success",
"data": {
"activeTargets": [
{
"discoveredLabels": {
"__address__": "127.0.0.1:9091",
"__metrics_path__": "/metrics",
"__scheme__": "http",
"job": "node_exporter"
},
"labels": {
"instance": "127.0.0.1:9091",
"job": "node_exporter"
},
"scrapePool": "node_exporter",
"scrapeUrl": "http://127.0.0.1:9091/metrics",
"globalUrl": "http://example-prometheus:9091/metrics",
"lastError": "",
"lastScrape": "2017-01-17T15:07:44.723715405+01:00",
"lastScrapeDuration": 50688943,
"health": "up"
}
],
"droppedTargets": []
}
}
/rules APIエンドポイントは、現在ロードされているアラートルールとレコーディングルールのリストを返します。さらに、各アラートルールによってPrometheusインスタンスによって発生した現在アクティブなアラートも返します。
/rulesエンドポイントは比較的新しいため、上位のAPI v1と同じ安定性保証はありません。
GET /api/v1/rules
URLクエリパラメーター
type=alert|record：アラートルールのみ（例：type=alert）またはレコーディングルールのみ（例：type=record）を返します。パラメータが存在しないか空の場合は、フィルタリングは行われません。rule_name[]=<string>：指定されたルール名を持つルールのみを返します。パラメータが複数回繰り返される場合、指定されたいずれかの名前を持つルールが返されます。グループのすべてのルールがフィルタリングされた場合、そのグループは返されません。パラメータが存在しないか空の場合は、フィルタリングは行われません。rule_group[]=<string>：指定されたルールグループ名を持つルールのみを返します。パラメータが複数回繰り返される場合、指定されたいずれかのルールグループ名を持つルールが返されます。パラメータが存在しないか空の場合は、フィルタリングは行われません。file[]=<string>：指定されたファイルパスを持つルールのみを返します。パラメータが複数回繰り返される場合、指定されたいずれかのファイルパスを持つルールが返されます。パラメータが存在しないか空の場合は、フィルタリングは行われません。exclude_alerts=<bool>：ルールのみを返し、アクティブなアラートは返しません。match[]=<label_selector>：ラベルセレクタを満たす構成済みラベルを持つルールのみを返します。パラメータが複数回繰り返される場合、いずれかのラベルセレクタのセットに一致するルールが返されます。一致は、各ルールの定義内のラベルに対して行われ、テンプレート展開後の値に対しては行われないことに注意してください（アラートルールの場合）。オプションです。$ 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": "1e+00"
}
],
"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 by (job) (http_inprogress_requests)",
"type": "recording"
}
],
"file": "/rules.yaml",
"interval": 60,
"limit": 0,
"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": "1e+00"
}
]
},
"status": "success"
}
次のエンドポイントは、現在ターゲットからスクレイプされているメトリックに関するメタデータを返します。これは実験的な機能であり、将来変更される可能性があります。
GET /api/v1/targets/metadata
URLクエリパラメーター
match_target=<label_selectors>：ラベルセットによってターゲットに一致するラベルセレクタ。空のままの場合、すべてのターゲットが選択されます。metric=<string>：メタデータを取得するメトリック名。空のままの場合、すべてのメトリックメタデータが取得されます。limit=<number>：一致させるターゲットの最大数。クエリ結果のdataセクションは、メトリックメタデータとターゲットラベルセットを含むオブジェクトのリストで構成されています。
次の例は、ラベルjob="prometheus"を持つ最初の2つのターゲットからのgo_goroutinesメトリックのすべてのメタデータエントリを返します。
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": ""
},
// ...
]
}
現在ターゲットからスクレイプされているメトリックに関するメタデータを返します。ただし、ターゲット情報は提供しません。これは実験的な機能であり、将来変更される可能性があります。
GET /api/v1/metadata
URLクエリパラメーター
limit=<number>：返すメトリックの最大数。limit_per_metric=<number>：メトリックごとに返すメタデータの最大数。metric=<string>：メタデータのフィルタリング対象となるメトリック名。空のままの場合、すべてのメトリックメタデータが取得されます。クエリ結果のdataセクションは、各キーがメトリック名であり、各値がすべてのターゲット全体でそのメトリック名に対して公開されている一意のメタデータオブジェクトのリストであるオブジェクトで構成されています。
次の例は、2つのメトリックを返します。http_requests_totalメトリックには、リストに複数のオブジェクトがあることに注意してください。少なくとも1つのターゲットには、残りのものと一致しないHELPの値があります。
curl -G http://localhost:9090/api/v1/metadata?limit=2
{
"status": "success",
"data": {
"cortex_ring_tokens": [
{
"type": "gauge",
"help": "Number of tokens in the ring",
"unit": ""
}
],
"http_requests_total": [
{
"type": "counter",
"help": "Number of HTTP requests",
"unit": ""
},
{
"type": "counter",
"help": "Amount of HTTP requests",
"unit": ""
}
]
}
}
次の例は、メトリックごとに1つのメタデータエントリのみを返します。
curl -G http://localhost:9090/api/v1/metadata?limit_per_metric=1
{
"status": "success",
"data": {
"cortex_ring_tokens": [
{
"type": "gauge",
"help": "Number of tokens in the ring",
"unit": ""
}
],
"http_requests_total": [
{
"type": "counter",
"help": "Number of HTTP requests",
"unit": ""
}
]
}
}
次の例は、http_requests_totalメトリックのメタデータのみを返します。
curl -G http://localhost:9090/api/v1/metadata?metric=http_requests_total
{
"status": "success",
"data": {
"http_requests_total": [
{
"type": "counter",
"help": "Number of HTTP requests",
"unit": ""
},
{
"type": "counter",
"help": "Amount of HTTP requests",
"unit": ""
}
]
}
}
次のエンドポイントは、Prometheus Alertmanager検出の現在の状態の概要を返します。
GET /api/v1/alertmanagers
アクティブなAlertmanagerとドロップされた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"
}
]
}
}
次のステータスエンドポイントは、現在の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
すべての値は結果型stringです。
$ 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",
...
}
}
v2.2の新機能
次のエンドポイントは、Prometheusサーバーに関するさまざまなランタイム情報プロパティを返します。
GET /api/v1/status/runtimeinfo
返される値は、ランタイムプロパティの性質に応じて異なる型になります。
$ curl http://localhost:9090/api/v1/status/runtimeinfo
{
"status": "success",
"data": {
"startTime": "2019-11-02T17:23:59.301361365+01:00",
"CWD": "/",
"reloadConfigSuccess": true,
"lastConfigTime": "2019-11-02T17:23:59+01:00",
"timeSeriesCount": 873,
"corruptionCount": 0,
"goroutineCount": 48,
"GOMAXPROCS": 4,
"GOGC": "",
"GODEBUG": "",
"storageRetention": "15d"
}
}
v2.14の新機能
次のエンドポイントは、Prometheusサーバーに関するさまざまなビルド情報プロパティを返します。
GET /api/v1/status/buildinfo
すべての値は結果型stringです。
$ curl http://localhost:9090/api/v1/status/buildinfo
{
"status": "success",
"data": {
"version": "2.13.1",
"revision": "cb7cbad5f9a2823a622aaa668833ca04f50a0ea7",
"branch": "master",
"buildUser": "julius@desktop",
"buildDate": "20191102-16:19:59",
"goVersion": "go1.13.1"
}
}
v2.14の新機能
次のエンドポイントは、Prometheus TSDBに関するさまざまなカーディナリティ統計を返します。
GET /api/v1/status/tsdb
URLクエリパラメータ：- limit=<number>：各統計セットに対して返される項目数を指定された数に制限します。デフォルトでは、10個の項目が返されます。
クエリ結果のdataセクションは、- headStats：TSDBのヘッドブロックに関する以下のデータを返します：- numSeries：時系列の数。- chunkCount：チャンクの数。- minTime：ミリ秒単位の現在の最小タイムスタンプ。- maxTime：ミリ秒単位の現在の最大タイムスタンプ。- seriesCountByMetricName: メトリック名とその時系列数のリストを提供します。- labelValueCountByLabelName: ラベル名とその値数のリストを提供します。- memoryInBytesByLabelName ラベル名とその使用メモリ量（バイト単位）のリストを提供します。メモリ使用量は、特定のラベル名のすべての値の長さを合計することで計算されます。- seriesCountByLabelPair ラベル値のペアとその時系列数のリストを提供します。
$ curl http://localhost:9090/api/v1/status/tsdb
{
"status": "success",
"data": {
"headStats": {
"numSeries": 508,
"chunkCount": 937,
"minTime": 1591516800000,
"maxTime": 1598896800143,
},
"seriesCountByMetricName": [
{
"name": "net_conntrack_dialer_conn_failed_total",
"value": 20
},
{
"name": "prometheus_http_request_duration_seconds_bucket",
"value": 20
}
],
"labelValueCountByLabelName": [
{
"name": "__name__",
"value": 211
},
{
"name": "event",
"value": 3
}
],
"memoryInBytesByLabelName": [
{
"name": "__name__",
"value": 8266
},
{
"name": "instance",
"value": 28
}
],
"seriesCountByLabelValuePair": [
{
"name": "job=prometheus",
"value": 425
},
{
"name": "instance=localhost:9090",
"value": 425
}
]
}
}
v2.15の新機能
次のエンドポイントは、WAL再生に関する情報を返します。
GET /api/v1/status/walreplay
read：これまで再生されたセグメントの数。total：再生が必要なセグメントの総数。progress：再生の進捗状況（0～100％）。state：再生の状態。可能な状態：- waiting：再生開始を待機中。- in progress：再生中。- done：再生が完了しました。
$ curl http://localhost:9090/api/v1/status/walreplay
{
"status": "success",
"data": {
"min": 2,
"max": 5,
"current": 40,
"state": "in progress"
}
}
v2.28の新機能
これらは、高度なユーザー向けのデータベース機能を公開するAPIです。これらのAPIは、--web.enable-admin-apiが設定されていない限り有効になりません。
スナップショットは、現在のすべてのデータをTSDBのデータディレクトリ内のsnapshots/<datetime>-<rand>にスナップショットとして作成し、ディレクトリをレスポンスとして返します。オプションで、ヘッドブロックのみに存在し、まだディスクに圧縮されていないデータのスナップショット作成をスキップします。
POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot
URLクエリパラメーター
skip_head=<bool>：ヘッドブロックに存在するデータをスキップします。オプションです。$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
"status": "success",
"data": {
"name": "20171210T211224Z-2be650b6d019eb54"
}
}
スナップショットは<data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54に存在します。
v2.1の新機能であり、v2.9からPUTをサポートしています。
DeleteSeries は、時間範囲内の複数の時系列データを選択して削除します。実際のデータはディスク上に依然として存在し、将来の圧縮処理でクリーンアップされるか、Clean Tombstones エンドポイントを呼び出すことで明示的にクリーンアップできます。
成功すると、204が返されます。
POST /api/v1/admin/tsdb/delete_series
PUT /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"}'
v2.1の新機能であり、v2.9からPUTをサポートしています。
CleanTombstones は、削除されたデータをディスクから削除し、既存の墓石をクリーンアップします。これは、時系列を削除した後に領域を解放するために使用できます。
成功すると、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
v2.1の新機能であり、v2.9からPUTをサポートしています。
Prometheusは、Prometheusリモート書き込みプロトコルのレシーバーとして設定できます。これは、サンプルを取り込むための効率的な方法とは見なされていません。特定の低ボリュームのユースケースに注意して使用してください。スクレイピングによる取り込みに置き換えることや、Prometheusをプッシュ型のメトリクス収集システムにすることは適切ではありません。
--web.enable-remote-write-receiverを設定することで、リモート書き込みレシーバーを有効にできます。有効にすると、リモート書き込みレシーバーのエンドポイントは/api/v1/writeになります。詳細はこちらを参照してください。
v2.33の新機能
Prometheusは、OTLPメトリクスプロトコルのレシーバーとして設定できます。これは、サンプルを取り込むための効率的な方法とは見なされていません。特定の低ボリュームのユースケースに注意して使用してください。スクレイピングによる取り込みに置き換えることは適切ではありません。
機能フラグ--enable-feature=otlp-write-receiverでOTLPレシーバーを有効にできます。有効にすると、OTLPレシーバーのエンドポイントは/api/v1/otlp/v1/metricsになります。
v2.47の新機能
このドキュメントはオープンソースです。問題点やプルリクエストを提出して、改善にご協力ください。