토리맘의 한글라이즈 프로젝트 logo 토리맘의 한글라이즈 프로젝트

프로메테우스 공식 레퍼런스를 한글로 번역한 문서입니다.

전체 목차는 여기에 있습니다.


HTTP API의 현재 stable 버전은 프로메테우스 서버에서 /api/v1로 접근할 수 있다. 호환에 문제가 없는 추가 기능은 이 엔드포인트 아래에 추가된다.

목차


Format overview

API 응답 형식은 JSON이다. 성공한 API 요청은 모두 상태 코드 2xx를 반환한다.

API 핸들러에 잘못된 요청을 보내면 JSON 에러 객체와 함께 아래 HTTP 응답 코드 중 하나를 반환한다:

API 엔드포인트에 도달하기 전에 에러가 발생했을 땐 그외 다른 2xx 이외의 코드를 반환할 수도 있다.

오류가 있더라도 요청은 실행됐을 경우 warnings 배열을 반환할 수 있다. 수집을 완료한 모든 데이터는 data 필드에 담겨서 반환된다.

JSON 응답 형식은 다음과 같다:

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

  // status가 "error"일 때만 설정한다.
  // error가 있더라도 data 필드에 데이터를 가지고 있을 수도 있다.
  "errorType": "<string>",
  "error": "<string>",

  // 요청을 실행하는 동안 warning이 생겼을 때만.
  // data 필드에 데이터를 가지고 있을 수도 있다.
  "warnings": ["<string>"]
}

공통으로 사용하는 플레이스홀더는 다음과 같다:

참고: 여러 번 반복할 수 있는 쿼리 파라미터들은 이름이 []로 끝난다.


Expression queries

쿼리 언어 표현식은 특정한 순간instant에 평가할 수도 있고, 일정 기간range of time 동안 평가할 수도 있다. 아래 섹션에선 각 표현식 쿼리 타입별 API 엔드포인트를 설명한다.

Instant queries

다음 엔드포인트에선 단일 시점에 instant 쿼리를 평가한다:

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

URL 파라미터:

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

Range queries

다음 엔드포인트에선 일정 기간 동안의 표현식 쿼리를 평가한다:

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

URL 파라미터:

POST 메소드와 Content-Type: application/x-www-form-urlencoded 헤더를 사용하면 위 파라미터들을 요청 바디에서 바로 URL 인코딩할 수 있다. 서버 측 URL 문자 제한을 위반할 수도 있는 쿼리를 대량으로 지정할 때 유용할 거다.

쿼리 결과에 있는 data 필드에선 다음과 같은 형식을 사용한다:

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

<value> 플레이스홀더 형식은 range-vector 결과 형식을 참고해라.

다음은 15초의 쿼리 해상도resolution로 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" ]
            ]
         }
      ]
   }
}

Querying metadata

프로메테우스는 시계열과 레이블에 관한 메타데이터를 질의할 수 있는 API 엔드포인트 셋을 제공한다.

참고: 이 API 엔드포인트들은 선택한 시간 범위 내에 샘플이 없는 시계열이나, 삭제 API를 통해 샘플이 삭제된 것으로 마킹된 시계열의 메타데이터도 반환할 수 있다. 부가적으로 반환하는 시계열 메타데이터의 정확한 범위는 세부 구현을 따르고 있으며, 향후 변경될 수 있다.

Finding series by label matchers

다음 엔드포인트에선 특정 레이블 셋과 매칭되는 시계열 목록을 반환한다:

GET /api/v1/series
POST /api/v1/series

URL 파라미터:

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

Getting label names

다음 엔드포인트는 레이블 이름 목록을 반환한다:

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

URL 파라미터:

문자열로된 레이블 이름 목록은 JSON 응답의 data 필드에 들어있다.

다음은 api 예시다.

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

Querying label values

다음 엔드포인트에선 지정한 레이블 이름에 저장돼 있는 레이블 값들의 목록을 반환한다:

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

URL 파라미터:

문자열로된 레이블 값 목록은 JSON 응답의 data 필드에 들어있다.

다음은 job 레이블에 저장된 모든 값들을 질의하는 예시다:

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

Querying exemplars

이 엔드포인트는 실험적인 기능으로, 향후 변경될 수 있다. 다음 엔드포인트는 특정한 시간 범위에서 유효한 PromQL 쿼리의 exemplar 목록을 반환한다:

GET /api/v1/query_exemplars
POST /api/v1/query_exemplars

URL 파라미터:

$ 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": {
                        "traceID": "EpTxMJ40fUus7aGY"
                    },
                    "value": "6",
                    "timestamp": 1600096945.479,
                }
            ]
        },
        {
            "seriesLabels": {
                "__name__": "test_exemplar_metric_total",
                "instance": "localhost:8090",
                "job": "prometheus",
                "service": "foo"
            },
            "exemplars": [
                {
                    "labels": {
                        "traceID": "Olp9XHlq763ccsfa"
                    },
                    "value": "19",
                    "timestamp": 1600096955.479,
                },
                {
                    "labels": {
                        "traceID": "hCtjygkIHwAN9vs4"
                    },
                    "value": "20",
                    "timestamp": 1600096965.489,
                },
            ]
        }
    ]
}

Expression query result formats

표현식 쿼리는 data 필드의 result 속성에 다음과 같은 응답 값들을 반환할 수 있다. <sample_value> 플레이스홀더는 숫자로 된 샘플 값을 나타낸다. JSON은 NaN, Inf, -Inf같은 특수 float 값을 지원하지 않으므로, 샘플 값은 숫자 그대로 전달하지 않고 따옴표로 감싼 JSON 문자열로 전송한다.

Range vectors

Range 벡터는 result type을 matrix로 반환한다. 이때 result 속성에 사용하는 형식은 다음과 같다:

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

Instant vectors

Instant 벡터는 result type을 vector로 반환한다. 이때 result 속성에 사용하는 형식은 다음과 같다:

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

Scalars

결과가 스칼라일 땐 result type을 scalar로 반환한다. 이때 result 속성에 사용하는 형식은 다음과 같다:

[ <unix_time>, "<scalar_value>" ]

Strings

결과가 문자열일 땐 result type을 string으로 반환한다. 이때 result 속성에 사용하는 형식은 다음과 같다:

[ <unix_time>, "<string_value>" ]

Targets

다음 엔드포인트는 프로메테우스 타겟 디스커버리의 현재 상태를 요약해서 보여준다:

GET /api/v1/targets

기본적으로 활성화된 타겟과 삭제된 타겟 모두 응답에 포함된다. labels는 레이블 relabelling을 적용한 이후 설정한 레이블을 나타낸다. discoveredLabels는 relabelling을 적용하기 전, 서비스 디스커버리 과정에서 조회한 레이블을 그대로 담고 있다.

$ 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를 지정하면 직접 활성 타겟이나 삭제된 타겟만 필터링할 수 있다 (ex. 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": []
  }
}

Rules

API 엔드포인트 /rules는 현재 로드돼 있는 alerting/recording rule 목록을 반환한다. alerting rule에선 프로메테우스 인스턴스에서 시행된fire 현재 활성 상태인 alert도 함께 반환한다.

/rules 엔드포인트는 완전히 새로운 엔드포인트이기 때문에, 전반적인 API v1과 같은 안정성을 보장하지 않는다.

GET /api/v1/rules

URL 파라미터:

$ 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,
                "name": "example"
            }
        ]
    },
    "status": "success"
}

Alerts

/alerts 엔드포인트는 활성 상태에 있는 모든 alert 목록을 반환한다.

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

Querying target metadata

다음 엔드포인트는 현재 타겟에서 스크랩한 메트릭에 관한 메타데이터를 반환한다. 이 엔드포인트는 실험적인 기능으로, 향후 변경될 수 있다.

GET /api/v1/targets/metadata

URL 파라미터:

쿼리 결과에 있는 data 필드는 객체 목록으로 구성되며, 각각은 메트릭 메타데이터와 타겟 레이블 셋을 포함하고 있다.

다음은 job="prometheus" 레이블을 가지고 있는 처음 두 타겟에서, 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": ""
    },
    // ...
  ]
}

Querying metric metadata

이 엔드포인트는 현재 타겟에서 스크랩한 메트릭에 관한 메타데이터를 반환한다. 하지만 이번엔 타겟 정보는 제공하지 않는다. 이 엔드포인트는 실험적인 기능으로, 향후 변경될 수 있다.

GET /api/v1/metadata

URL 파라미터:

쿼리 결과에 있는 data 필드는 객체로 구성돼 있다. 이 객체의 키는 메트릭명이고, 값에는 모든 타겟에서 해당 메트릭 이름으로 노출하는 고유한 메타데이터 객체 목록이 담겨있다.

아래 예시에선 두 개의 메트릭을 반환한다. http_requests_total 메트릭의 목록에는 객체가 여러 개 들어있다. 최소 하나의 타겟에선 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": ""
      }
    ]
  }
}

다음 예시는 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": ""
      }
    ]
  }
}

Alertmanagers

다음 엔드포인트는 프로메테우스 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"
      }
    ]
  }
}

Status

아래 있는 status 엔드포인트는 현재 프로메테우스 설정을 보여준다.

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

다음 엔드포인트는 프로메테우스를 설정한 플래그 값들을 반환한다.

GET /api/v1/status/flags

모든 값들의 result type은 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에서 추가됐다

Runtime Information

다음 엔드포인트는 프로메테우스 서버에 관한 다양한 런타임 정보 프로퍼티를 반환한다:

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에서 추가됐다

Build Information

다음 엔드포인트는 프로메테우스 서버에 관한 다양한 빌드 정보 프로퍼티를 반환한다:

GET /api/v1/status/buildinfo

모든 값들의 result type은 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에서 추가됐다

TSDB Stats

다음 엔드포인트는 프로메테우스 TSDB의 다양한 카디널리티 관련 통계치를 반환한다:

GET /api/v1/status/tsdb
$ 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 Replay Stats

다음 엔드포인트는 WAL 리플레이에 관한 정보를 반환한다:

GET /api/v1/status/walreplay
$ curl http://localhost:9090/api/v1/status/walreplay
{
  "status": "success",
  "data": {
    "min": 2,
    "max": 5,
    "current": 40,
    "state": "in progress"
  }
}

참고: 이 엔드포인트는 서버를 ready 상태로 마킹하기 전에도 사용할 수 있으며, WAL 리플레이 진행 상황을 쉽게 모니터링할 수 있도록 실시간으로 업데이트된다.

v2.28에서 추가됐다


TSDB Admin APIs

여기서 설명하는 API들은 상급자용 API로, 데이터베이스 기능들을 노출한다. --web.enable-admin-api를 설정하지 않았다면 이 API들은 활성화되지 않는다.

Snapshot

Snapshot은 TSDB의 데이터 디렉토리 밑에 있는 snapshots/<datetime>-<rand>에 현재 모든 데이터들의 스냅샷을 생성하며, 이 디렉토리를 응답으로 반환한다. 원한다면 헤드 블록에만 존재하며 아직 디스크에 쓰지 않은 데이터는 스냅샷을 만들지 않고 건너뛸 수 있다.

POST /api/v1/admin/tsdb/snapshot
PUT /api/v1/admin/tsdb/snapshot

URL 파라미터:

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

이제 <data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54에 스냅샷이 저장돼있을 거다.

v2.1에서 추가됐으며, PUT 메소드는 v2.9부터 지원한다

Delete Series

DeleteSeries는 특정 시간 범위에서 선택한 시계열 데이터를 삭제한다. 삭제하더라도 실제 데이터는 디스크에 그대로 존재하며, 향후 디스크 컴팩션compaction에서 정리되거나 Clean Tombstones 엔드포인트를 요청해 직접 정리할 수 있다.

삭제에 성공하면 204를 반환한다.

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

URL 파라미터:

시작 시간과 종료 시간을 모두 지정하지 않으면 데이터베이스에서 매칭되는 시계열의 모든 데이터가 지워진다.

예시:

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

참고: 이 엔드포인트는 시계열에 있는 샘플들을 삭제한 것으로 마킹하지만, 영향 범위에 있는 메타데이터를 질의할 땐 관련 시계열 메타데이터가 그대로 반환되는 것을 반드시 막아주진 않는다 (톰스톤tombstone을 정리했더라도). 정확한 메타데이터 삭제 범위는 세부 구현을 따르고 있으며, 향후 변경될 수 있다.

v2.1에서 추가됐으며, PUT 메소드는 v2.9부터 지원한다

Clean Tombstones

CleanTombstones는 디스크에서 삭제된 데이터를 제거하고 기존 톰스톤tombstone을 정리한다. 시계열을 삭제한 뒤 공간을 확보할 때 사용할 수 있다.

삭제에 성공하면 204를 반환한다.

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

이 API에선 파라미터나 바디를 받지 않는다.

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

v2.1에서 추가됐으며, PUT 메소드는 v2.9부터 지원한다


Next :
Storage
프로메테우스 로컬 스토리지 구조, 리모트 스토리지 통합, 데이터 backfill 가이드

전체 목차는 여기에 있습니다.

<< >>

TOP