HTTP API

HTTP API

Prometheus는 데이터를 쿼리하고, 지표·레이블 메타데이터를 조회하고, TSDB를 관리하기 위한 다양한 HTTP API를 제공해요. 이 문서는 현재 안정(stable) 버전의 HTTP API인 /api/v1 엔드포인트 전체를 다루는 핵심 참조 문서예요. 프로메테우스 서버에 저장된 시계열 데이터를 프로그래밍 방식으로 읽고 싶다면, 바로 이 API부터 시작하는 게 정석이에요. 이 문서를 차근차근 따라가면 인스턴트 쿼리, 범위 쿼리부터 메타데이터 조회, 어드민 API까지 프로메테우스 API의 거의 모든 기능을 익힐 수 있어요.

이 API는 JSON 형식으로 응답하며, 요청 방식과 파라미터, 응답 구조까지 사양이 명확하게 정의되어 있어요. 그래서 클라이언트 라이브러리를 만들거나 Grafana 같은 도구와 연동할 때도 이 문서를 기준으로 삼아요. 아래에서 각 엔드포인트가 무엇을 하는지, 어떤 파라미터를 받는지, 어떤 형식으로 응답하는지 하나씩 살펴볼게요.

출처: 문서

본문

현재 안정 버전 HTTP API는 프로메테우스 서버의 /api/v1 경로에서 접근할 수 있어요. 비호환(non-breaking) 추가 사항은 모두 이 엔드포인트 아래에 추가돼요.

OpenAPI 스펙

HTTP API에 대한 OpenAPI 스펙은 /api/v1/openapi.yaml에서 제공돼요. 기본적으로는 더 넓은 호환성을 위해 OpenAPI 3.1을 반환하고, ?openapi_version=3.2를 쓰면 /api/v1/notifications/live 같은 고급 기능과 엔드포인트를 포함한 OpenAPI 3.2를 받을 수 있어요.

이 머신이 읽을 수 있는 스펙은 모든 엔드포인트, 요청 파라미터, 응답 형식, 스키마를 설명해요. 이 OpenAPI 스펙은 다음과 같은 용도로 쓸 수 있어요:

• 다양한 프로그래밍 언어의 클라이언트 라이브러리 생성
• API 요청·응답 검증
• 인터랙티브 API 문서 생성
• API 엔드포인트 테스트

형식 개요

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

API 핸들러까지 도달했지만 유효하지 않은 요청은 JSON 에러 객체와 함께 다음 중 하나의 HTTP 응답 코드를 반환해요:

• 파라미터가 없거나 잘못된 경우 400 Bad Request
• 표현식(expression)을 실행할 수 없는 경우 422 Unprocessable Entity (RFC4918)
• 쿼리가 타임아웃되거나 중단된 경우 503 Service Unavailable

API 엔드포인트에 도달하기 전에 발생한 에러는 다른 2xx가 아닌 코드로 반환될 수도 있어요.

요청 실행을 막지 않는 에러가 있으면 경고(warnings) 배열이 함께 반환될 수 있어요. 잠재적인 쿼리 문제(오탐일 수도 아닐 수도 있는)에 대해서는 info 레벨 어노테이션 배열이 추가로 반환될 수 있어요. 성공적으로 수집된 모든 데이터는 data 필드에 담겨 반환돼요.

JSON 응답 엔벨로프(envelope) 형식은 다음과 같아요:

{
  "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 annotations while executing the request.
  "infos": ["<string>"]
}

일반적인 플레이스홀더는 다음과 같이 정의돼요:

• <rfc3339 | unix_timestamp>: 입력 타임스탬프는 RFC3339 형식이거나 초 단위의 Unix 타임스탬프(초 미만 정밀도를 위해 소수 자리 선택 가능)로 제공할 수 있어요. 출력 타임스탬프는 항상 초 단위 Unix 타임스탬프로 표현돼요.
• <series_selector>: http_requests_total 또는 http_requests_total{method=~"(GET|POST)"} 같은 프로메테우스 시계열 셀렉터로, URL 인코딩이 필요해요.
• <duration>: 시간 단위를 사용하는 프로메테우스 float 리터럴의 부분집합이에요. 예를 들어 5m은 5분의 기간을 뜻해요.
• <bool>: 불리언 값(문자열 true와 false)이에요.

참고: 반복될 수 있는 쿼리 파라미터의 이름은 []로 끝나요.

표현식 쿼리

쿼리 언어 표현식은 단일 시점(instant) 또는 시간 범위(range)에 대해 평가할 수 있어요. 아래 섹션에서 각 유형의 표현식 쿼리용 API 엔드포인트를 설명해요.

인스턴트 쿼리 (Instant queries)

다음 엔드포인트는 단일 시점에서 인스턴트 쿼리를 평가해요:

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

URL 쿼리 파라미터:

• query=<string>: 프로메테우스 표현식 쿼리 문자열
• time=<rfc3339 | unix_timestamp>: 평가 타임스탬프. 선택 사항
• timeout=<duration>: 평가 타임아웃. 선택 사항. 기본값은 -query.timeout 플래그 값이고 최대치도 그것으로 제한돼요
• limit=<number>: 반환되는 시리즈의 최대 개수. 스칼라나 문자열에는 영향을 주지 않지만 matrix와 vector의 시리즈 수는 잘라내요. 선택 사항. 0이면 비활성화
• lookback_delta=<duration>: duration 형식 또는 초 단위 float 숫자로 이 쿼리에서만 룩백 기간을 덮어써요. 선택 사항
• stats=<true|all>: 응답에 쿼리 통계를 포함해요. true(기본 통계)와 all(타이밍과 샘플 수를 포함한 상세한 스텝별 통계를 추가 포함)을 지원해요. 그 외의 다른 비어 있지 않은 값은 현재 true처럼 동작하지만 deprecated이고 응답에 경고를 추가하며 다음 메이저 릴리스에서 거부될 거예요. 선택 사항. 쿼리 통계를 참고하세요

time 파라미터를 생략하면 현재 서버 시간이 사용돼요.

이 파라미터들을 POST 메서드와 Content-Type: application/x-www-form-urlencoded 헤더를 사용해 요청 본문에 직접 URL 인코딩할 수 있어요. 서버 측 URL 문자 제한을 넘을 수 있는 큰 쿼리를 지정할 때 유용해요.

쿼리 결과의 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
POST /api/v1/query_range

URL 쿼리 파라미터:

• query=<string>: 프로메테우스 표현식 쿼리 문자열
• start=<rfc3339 | unix_timestamp>: 시작 타임스탬프, 포함
• end=<rfc3339 | unix_timestamp>: 종료 타임스탬프, 포함
• step=<duration | float>: duration 형식 또는 초 단위 float 숫자로 된 쿼리 해상도 스텝 폭
• timeout=<duration>: 평가 타임아웃. 선택 사항. 기본값은 -query.timeout 플래그 값이고 최대치도 그것으로 제한돼요
• limit=<number>: 반환되는 시리즈의 최대 개수. 선택 사항. 0이면 비활성화
• lookback_delta=<duration>: duration 형식 또는 초 단위 float 숫자로 이 쿼리에서만 룩백 기간을 덮어써요. 선택 사항
• stats=<true|all>: 응답에 쿼리 통계를 포함해요. 선택 사항. 쿼리 통계를 참고하세요

이 파라미터들을 POST 메서드와 Content-Type: application/x-www-form-urlencoded 헤더를 사용해 요청 본문에 직접 URL 인코딩할 수 있어요.

쿼리 결과의 data 섹션 형식은 다음과 같아요:

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

<value> 플레이스홀더의 형식에 대해서는 범위-벡터 결과 형식을 참고하세요.

다음 예시는 30초 범위에 걸쳐 up 표현식을 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" ]
            ]
         }
      ]
   }
}

쿼리 통계 (Query statistics)

stats 파라미터를 설정하면(예: stats=all) 응답 data에 다음 구조의 stats 객체가 포함돼요:

• timings: 쿼리 실행의 여러 단계에 대한 기간(초 단위, 예: evalTotalTime, execQueueTime)
• samples:
  • totalQueryableSamples: 쿼리 중 로드된 총 샘플 수. 여러 스텝에 걸친 range-vector 함수의 경우 각 스텝이 전체 윈도우를 계산해요
  • totalQueryableSamplesPerStep: (stats=all이고 스텝별 통계가 활성화된 경우에만) 스텝별 로드된 샘플 수. 스텝별 totalQueryableSamples와 같은 의미예요
  • samplesRead: 읽은(Read, I/O) 총 샘플 수. 범위 쿼리의 range-vector 함수에서는 스텝별로 새 지점만 계산하고, 다른 쿼리에서는 totalQueryableSamples와 같아요
  • samplesReadPerStep: (stats=all이고 스텝별 통계가 활성화된 경우에만) 스텝별 읽은 샘플 수(range-vector에 대한 델타 의미)
  • peakSamples: 평가 중 메모리에 있었던 샘플의 최대 수

서버는 또한 prometheus_engine_query_samples_total(로드된 샘플)과 prometheus_engine_query_samples_read_total(읽은 샘플) 두 개의 프로메테우스 지표를 노출해요. promql-per-step-stats 기능 플래그에 대한 내용은 스텝별 통계를 참고하세요.

쿼리 표현식 포매팅

다음 엔드포인트는 PromQL 표현식을 보기 좋게(prettify) 포맷해요:

GET /api/v1/format_query
POST /api/v1/format_query

URL 쿼리 파라미터:

• query=<string>: 프로메테우스 표현식 쿼리 문자열

이 파라미터들을 POST 메서드와 Content-Type: application/x-www-form-urlencoded 헤더를 사용해 요청 본문에 직접 URL 인코딩할 수 있어요.

쿼리 결과의 data 섹션은 포맷된 쿼리 표현식을 담은 문자열이에요. 포맷된 문자열에서는 주석이 모두 제거된다는 점에 주의하세요.

다음 예시는 foo/bar 표현식을 포맷해요:

curl 'http://localhost:9090/api/v1/format_query?query=foo/bar'

{
   "status" : "success",
   "data" : "foo / bar"
}

PromQL 표현식을 추상 구문 트리(AST)로 파싱

이 엔드포인트는 실험적이며 향후 변경될 수 있어요. 현재는 프로메테우스 자체 웹 UI에서만 사용하도록 만들어졌고, 엔드포인트 이름과 반환 형식은 프로메테우스 버전에 따라 바뀔 수 있어요. UI에서 더 이상 필요하지 않게 되면 제거될 수도 있어요.

다음 엔드포인트는 PromQL 표현식을 파싱해 JSON 형식의 AST(추상 구문 트리) 표현으로 반환해요:

GET /api/v1/parse_query
POST /api/v1/parse_query

URL 쿼리 파라미터:

• query=<string>: 프로메테우스 표현식 쿼리 문자열

이 파라미터들을 POST 메서드와 Content-Type: application/x-www-form-urlencoded 헤더를 사용해 요청 본문에 직접 URL 인코딩할 수 있어요.

쿼리 결과의 data 섹션은 파싱된 쿼리 표현식의 AST를 담은 문자열이에요.

다음 예시는 foo/bar 표현식을 파싱해요:

curl 'http://localhost:9090/api/v1/parse_query?query=foo/bar'

{
   "data" : {
      "bool" : false,
      "lhs" : {
         "matchers" : [
            {
               "name" : "__name__",
               "type" : "=",
               "value" : "foo"
            }
         ],
         "name" : "foo",
         "offset" : 0,
         "startOrEnd" : null,
         "timestamp" : null,
         "type" : "vectorSelector"
      },
      "matching" : {
         "card" : "one-to-one",
         "include" : [],
         "labels" : [],
         "on" : false
      },
      "op" : "/",
      "rhs" : {
         "matchers" : [
            {
               "name" : "__name__",
               "type" : "=",
               "value" : "bar"
            }
         ],
         "name" : "bar",
         "offset" : 0,
         "startOrEnd" : null,
         "timestamp" : null,
         "type" : "vectorSelector"
      },
      "type" : "binaryExpr"
   },
   "status" : "success"
}

메타데이터 쿼리

프로메테우스는 시리즈와 레이블에 대한 메타데이터를 쿼리하는 API 엔드포인트 세트를 제공해요.

참고: 이 API 엔드포인트들은 선택된 시간 범위 내에 샘플이 없거나, 삭제 API 엔드포인트를 통해 샘플이 삭제된 것으로 표시된 시리즈에 대한 메타데이터도 반환할 수 있어요. 추가로 반환되는 시리즈 메타데이터의 정확한 범위는 구현 세부사항이며 향후 변경될 수 있어요.

레이블 매처로 시리즈 찾기

다음 엔드포인트는 특정 레이블 세트와 일치하는 시계열 목록을 반환해요:

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

URL 쿼리 파라미터:

• match[]=<series_selector>: 반환할 시리즈를 선택하는 반복되는 시리즈 셀렉터 인자. match[] 인자를 적어도 하나는 제공해야 해요
• start=<rfc3339 | unix_timestamp>: 시작 타임스탬프
• end=<rfc3339 | unix_timestamp>: 종료 타임스탬프
• limit=<number>: 반환되는 시리즈의 최대 개수. 선택 사항. 0이면 비활성화

이 파라미터들을 POST 메서드와 Content-Type: application/x-www-form-urlencoded 헤더를 사용해 요청 본문에 직접 URL 인코딩할 수 있어요.

쿼리 결과의 data 섹션은 각 시리즈를 식별하는 레이블 이름/값 쌍을 포함하는 객체 목록으로 구성돼요. start와 end 시간은 근사치이며 결과에는 주어진 구간에 샘플이 없는 시리즈의 레이블 값도 포함될 수 있다는 점에 주의하세요.

다음 예시는 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 섹션은 문자열 레이블 이름의 목록이에요. start와 end 시간은 근사치이며 결과에는 주어진 구간에 샘플이 없는 시리즈의 레이블 이름도 포함될 수 있다는 점에 주의하세요.

예시는 다음과 같아요:

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 섹션은 문자열 레이블 값의 목록이에요. start와 end 시간은 근사치이며 결과에는 주어진 구간에 샘플이 없는 시리즈의 레이블 값도 포함될 수 있다는 점에 주의하세요.

이 예시는 http_status_code 레이블의 모든 레이블 값을 쿼리해요:

curl http://localhost:9090/api/v1/label/http_status_code/values

{
   "status" : "success",
   "data" : [
      "200",
      "504"
   ]
}

레이블 이름은 선택적으로 자동 이스케이프(Values Escaping) 방식을 사용해 인코딩할 수 있고, 이름에 / 문자가 포함된 경우 반드시 필요해요. 다음과 같이 인코딩해요:

• 레이블 앞에 U__를 붙여요
• 문자, 숫자, 콜론은 그대로 표시돼요
• 단일 밑줄은 이중 밑줄로 변환해요
• 그 외의 모든 문자는 밑줄로 둘러싼 UTF-8 코드포인트 16진수 정수를 사용해요. 그래서 (공백)은 _20_이 되고 .은 _2e_가 돼요

텍스트 이스케이프에 대한 더 자세한 내용은 원본 UTF-8 Proposal 문서에서 확인할 수 있어요.

이 예시는 http.status_code 레이블의 모든 레이블 값을 쿼리해요:

curl http://localhost:9090/api/v1/label/U__http_2e_status_code/values

{
   "status" : "success",
   "data" : [
      "200",
      "404"
   ]
}

메트릭 이름, 레이블 이름, 레이블 값 검색

이 엔드포인트들은 실험적이며 --enable-feature=search-api로 활성화해야 해요.

다음 엔드포인트들은 메트릭 이름, 레이블 이름, 레이블 값에 대한 스트리밍 검색 결과를 제공해요:

GET /api/v1/search/metric_names
POST /api/v1/search/metric_names
GET /api/v1/search/label_names
POST /api/v1/search/label_names
GET /api/v1/search/label_values
POST /api/v1/search/label_values

이 엔드포인트들은 application/x-ndjson 콘텐츠 타입의 newline-delimited JSON을 반환해요. 스트림 계약은 다음과 같아요:

• 0개 이상의 배치(batch) 줄. 각 줄은 results 배열과 선택적인 warnings 배열을 가져요
• 스트림은 트레일러(trailer) 줄(status, has_more, 선택적 warnings) 또는 첫 배치가 보내진 후 중간에 반복이 실패하면 에러 줄(status, errorType, error)로 끝나요

{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}
{"status":"success","has_more":false}

스트리밍이 시작되기 전에 에러가 발생하면 API는 4xx/5xx 상태 코드와 함께 일반 프로메테우스 JSON 에러 객체를 반환해요. 스트리밍 시작 후에 에러가 발생하면 트레일러 대신 NDJSON 에러 줄로 스트림이 끝나요.

클라이언트는 트레일러 없이 갑작스러운 EOF(예: 전송 실패나 서버 종료)를 견뎌야 하고, 향후 호환성을 위해 트레일러의 알 수 없는 필드는 무시해야 해요.

트레일러의 has_more 필드는 정보 제공용이에요. 이 버전의 API는 페이지네이션 커서를 제공하지 않아요. 더 많은 결과를 얻으려면 limit를 올리거나(운영자가 설정한 --web.search.max-limit에 따라) match[]로 요청을 좁혀야 해요. 향후 버전에서 커서가 추가될 수도 있어요.

공통 URL 쿼리 파라미터:

• match[]=<series_selector>: 검색 범위를 좁히는 데 사용하는 반복되는 시리즈 셀렉터. 선택 사항
• search[]=<string>: 이름이나 값과 대조되는 반복되는 검색 문자열. 여러 값은 OR 의미를 사용해요. 선택 사항
• fuzz_threshold=<number>: 0부터 100까지의 퍼지 임계값. 선택 사항. 0이 가장 낮은 퍼지 임계값이에요
• fuzz_alg=<string>: 일치 알고리즘. 선택 사항. 기본값은 subsequence예요
• case_sensitive=<bool>: 대소문자 구분 일치 전환. 선택 사항
• sort_by=<string>: 정렬 모드. 지원 값은 엔드포인트에 따라 달라요
• sort_dir=<string>: 정렬 방향. 선택 사항. sort_by=alpha에서만 유효해요
• include_score=<bool>: 각 결과에 관련성 점수 포함. 선택 사항
• start=<rfc3339 | unix_timestamp>: 시작 타임스탬프. 선택 사항
• end=<rfc3339 | unix_timestamp>: 종료 타임스탬프. 선택 사항
• limit=<number>: 반환되는 결과의 최대 개수. 선택 사항. 기본값은 100
• batch_size=<number>: NDJSON 배치당 선호 결과 수. 선택 사항. 기본값은 100

start와 end 파라미터는 결과를 선택한 시간 윈도우로 좁혀요. 프로메테우스가 데이터를 고정 크기 블록(보통 각각 2시간)에 저장하기 때문에 결과에는 해당 윈도우 밖에서 활성 상태인 시리즈의 값이 포함될 수 있어요.

/api/v1/search/metric_names 추가 파라미터:

• include_metadata=<bool>: 각 결과에 메트릭 메타데이터 포함
• sort_by=<string>

/api/v1/search/label_names 추가 파라미터:

• sort_by=<string>

/api/v1/search/label_values 추가 파라미터:

• label=<string>: 값을 검색할 레이블 이름. 필수
• sort_by=<string>

이 예시는 자동완성을 위해 메트릭 이름을 검색해요:

curl -g 'http://localhost:9090/api/v1/search/metric_names?search[]=http_req&sort_by=score&include_metadata=true&limit=5'

{"results":[{"name":"http_requests_total","type":"counter","help":"Total HTTP requests."}]}
{"status":"success","has_more":false}

이 예시는 up 메트릭 내 instance 레이블의 레이블 값을 검색해요:

curl -g 'http://localhost:9090/api/v1/search/label_values?label=instance&match[]=up&search[]=909&sort_by=score'

{"results":[{"value":"localhost:9090"},{"value":"localhost:9091"}]}
{"status":"success","has_more":true}

예시자(Exemplar) 쿼리

이는 실험적이며 향후 변경될 수 있어요. 다음 엔드포인트는 특정 시간 범위에 대한 유효한 PromQL 쿼리의 exemplar 목록을 반환해요:

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

URL 쿼리 파라미터:

• query=<string>: 프로메테우스 표현식 쿼리 문자열
• 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 같은 특수 float 값을 지원하지 않으므로, 샘플 값은 원시 숫자가 아니라 따옴표로 감싼 JSON 문자열로 전송돼요.

"histogram"과 "histograms" 키는 응답에 네이티브 히스토그램이 있는 경우에만 나타나요. 해당 플레이스홀더 <histogram>은 아래 별도 섹션에서 자세히 설명해요.

범위 벡터 (Range vectors)

범위 벡터는 결과 타입 matrix로 반환돼요. 해당 result 속성의 형식은 다음과 같아요:

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

각 시리즈는 "values" 키, "histograms" 키, 또는 둘 다를 가질 수 있어요. 주어진 타임스탬프에는 float 또는 histogram 유형 중 하나의 샘플만 있어요.

시리즈는 metric으로 정렬되어 반환돼요. sort나 sort_by_label 같은 함수는 범위 벡터에는 효과가 없어요.

인스턴트 벡터 (Instant vectors)

인스턴트 벡터는 결과 타입 vector로 반환돼요. 해당 result 속성의 형식은 다음과 같아요:

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

각 시리즈는 "value" 키 또는 "histogram" 키 중 하나만 가질 수 있어요.

sort나 sort_by_label 같은 함수를 사용하지 않는 한 시리즈가 특정 순서로 반환된다는 보장은 없어요.

스칼라 (Scalars)

스칼라 결과는 결과 타입 scalar로 반환돼요. 해당 result 속성의 형식은 다음과 같아요:

[ <unix_time>, "<sample_value>" ]

문자열 (Strings)

문자열 결과는 결과 타입 string으로 반환돼요. 해당 result 속성의 형식은 다음과 같아요:

[ <unix_time>, "<string_value>" ]

네이티브 히스토그램 (Native histograms)

위에서 사용된 <histogram> 플레이스홀더는 다음과 같이 포맷돼요:

{
  "count": "<int>",
  "sum": "<float>",
  "buckets": [ [ <lower_bound>, "<upper_bound>", "<count>", "<offset>" ], ... ]
}

<bound_type> 플레이스홀더는 0에서 3 사이의 정수로 의미는 다음과 같아요:

• 0: "open left" (왼쪽 경계 제외, 오른쪽 경계 포함)
• 1: "open right" (왼쪽 경계 포함, 오른쪽 경계 제외)
• 2: "open both" (양쪽 경계 제외)
• 3: "closed both" (양쪽 경계 포함)

현재 구현된 버킷 스키마에서는 양수 버킷이 "open left", 음수 버킷이 "open right", 제로 버킷(음수 왼쪽 경계와 양수 오른쪽 경계)은 "closed both"라는 점에 주의하세요.

스크레이프 풀 (Scrape pools)

다음 엔드포인트는 구성된 모든 스크레이프 풀의 목록을 반환해요:

GET /api/v1/scrape_pools

JSON 응답의 data 섹션은 문자열 스크레이프 풀 이름의 목록이에요.

curl http://localhost:9090/api/v1/scrape_pools

{
  "status": "success",
  "data": {
    "scrapePools": [
      "prometheus",
      "node_exporter",
      "blackbox"
    ]
  }
}

v2.42에서 새로 추가됨

타깃 (Targets)

다음 엔드포인트는 프로메테우스 타깃 디스커버리의 현재 상태에 대한 개요를 반환해요:

GET /api/v1/targets

기본적으로 활성(active) 타깃과 드롭(dropped)된 타깃이 모두 응답에 포함돼요. 드롭된 타깃은 설정된 경우 keep_dropped_targets 제한의 적용을 받아요. labels는 relabeling 후의 레이블 세트를 나타내고, discoveredLabels는 relabeling 전에 서비스 디스커버리 동안 가져온 수정되지 않은 레이블을 나타내요.

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",
          "__always_scrape_classic_histograms__": "false",
          "__convert_classic_histograms_to_nhcb__": "false",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "__scrape_interval__": "1m",
          "__scrape_native_histograms__": "false",
          "__scrape_timeout__": "10s",
          "job": "node"
        },
        "scrapePool": "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": []
  }
}

Relabel 단계

이 엔드포인트는 실험적이며 향후 변경될 수 있어요. 현재는 프로메테우스 자체 웹 UI에서만 사용하도록 만들어졌고, 엔드포인트 이름과 반환 형식은 프로메테우스 버전에 따라 바뀔 수 있어요. UI에서 더 이상 필요하지 않게 되면 제거될 수도 있어요.

다음 엔드포인트는 주어진 타깃의 레이블 세트에 대한 relabeling 규칙과 그 효과를 단계별 목록으로 반환해요:

GET /api/v1/targets/relabel_steps

URL 쿼리 파라미터:

• scrapePool=<string>: 적용할 relabeling 규칙을 결정하는 데 사용되는 타깃의 스크레이프 풀 이름. 필수
• labels=<string>: relabeling이 적용되기 전 타깃의 레이블 세트를 담은 JSON 객체. 필수

다음 예시는 {"__address__": "localhost:9090", "job": "prometheus"} 레이블 세트를 가진 prometheus 스크레이프 풀의 발견된 타깃에 대한 relabeling 단계를 반환해요:

curl -g 'http://localhost:9090/api/v1/targets/relabel_steps?scrapePool=prometheus&labels={"__address__":"localhost:9090","job":"prometheus"}'

{
   "data" : {
      "steps" : [
         {
            "keep" : true,
            "output" : {
               "__address__" : "localhost:9090",
               "env" : "development",
               "job" : "prometheus"
            },
            "rule" : {
               "action" : "replace",
               "regex" : "(.*)",
               "replacement" : "development",
               "separator" : ";",
               "target_label" : "env"
            }
         },
         {
            "keep" : false,
            "output" : {},
            "rule" : {
               "action" : "drop",
               "regex" : "localhost:.*",
               "replacement" : "$1",
               "separator" : ";",
               "source_labels" : [
                  "__address__"
               ]
            }
         }
      ]
   },
   "status" : "success"
}

규칙 (Rules)

/rules API 엔드포인트는 현재 로드된 경고(alerting) 및 기록(recording) 규칙 목록을 반환해요. 또한 각 경고 규칙이 프로메테우스 인스턴스에서 발화시킨 현재 활성 알림도 반환해요.

/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>: 구성된 레이블이 레이블 셀렉터를 충족하는 규칙만 반환. 파라미터가 반복되면 레이블 셀렉터 세트 중 아무거나와 일치하는 규칙을 반환해요. 일치는 각 규칙 정의의 레이블에 대한 것이지, 템플릿 확장 후의 값(경고 규칙의 경우)이 아니라는 점에 주의하세요. 선택 사항
• group_limit=<number>: group_limit 파라미터로 단일 응답에서 반환되는 규칙 그룹 수의 한도를 지정할 수 있어요. 총 규칙 그룹 수가 지정된 group_limit을 초과하면 응답에 groupNextToken 속성이 포함돼요. 이후 요청에서 이 groupNextToken 값을 group_next_token 파라미터에 사용해 나머지 규칙 그룹을 페이지네이션할 수 있어요. 마지막 응답에는 groupNextToken 속성이 없으며, 이는 모든 규칙 그룹을 가져왔다는 뜻이에요. 페이지네이션 중 규칙 그룹이 수정되는 경우 응답의 일관성은 보장되지 않는다는 점에 유의하세요
• group_next_token=<string>: group_limit 속성이 설정되었을 때 이전 요청에서 반환된 페이지네이션 토큰. 많은 수의 규칙 그룹을 반복적으로 페이지네이션하는 데 사용돼요. group_next_token 파라미터를 사용하려면 group_limit 파라미터도 함께 있어야 해요. 페이지네이션 중 다음 토큰과 일치하는 규칙 그룹이 제거되면 상태 코드 400의 응답이 반환돼요

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 엔드포인트는 모든 활성 알림의 목록을 반환해요.

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

타깃 메타데이터 쿼리

다음 엔드포인트는 타깃에서 현재 스크레이프된 메트릭에 대한 메타데이터를 반환해요. 이 엔드포인트는 타깃에서 직접 스크레이프된 메타데이터만 반환한다는 제한이 있고, Remote-Write나 OTLP로 프로메테우스에 보내진 메타데이터는 이 엔드포인트에 포함되지 않으며 UI의 "Explore Metrics"에도 나타나지 않아요. 이는 실험적이며 향후 변경될 수 있어요.

GET /api/v1/targets/metadata

URL 쿼리 파라미터:

• match_target=<label_selectors>: 레이블 세트로 타깃을 일치시키는 레이블 셀렉터. 비워 두면 모든 타깃이 선택돼요
• metric=<string>: 메타데이터를 가져올 메트릭 이름. 비워 두면 모든 메트릭 메타데이터를 가져와요
• limit=<number>: 일치시킬 타깃의 최대 개수

쿼리 결과의 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": ""
    },
    // ...
  ]
}

메트릭 메타데이터 쿼리

타깃에서 현재 스크레이프된 메트릭에 대한 메타데이터를 반환해요. 하지만 타깃 정보는 제공하지 않아요. 이는 실험적인 것으로 간주되며 향후 변경될 수 있어요.

GET /api/v1/metadata

URL 쿼리 파라미터:

• limit=<number>: 반환할 메트릭의 최대 개수
• limit_per_metric=<number>: 메트릭당 반환할 메타데이터의 최대 개수
• metric=<string>: 메타데이터를 필터링할 메트릭 이름. 비워 두면 모든 메트릭 메타데이터를 가져와요

쿼리 결과의 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": ""
      }
    ]
  }
}

다음 예시는 각 메트릭에 대해 하나의 메타데이터 항목만 반환해요:

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

Alertmanagers

다음 엔드포인트는 프로메테우스 alertmanager 디스커버리의 현재 상태에 대한 개요를 반환해요:

GET /api/v1/alertmanagers

활성 및 드롭된 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)

다음 상태 엔드포인트들은 현재 프로메테우스 구성을 노출해요.

Config

다음 엔드포인트는 현재 로드된 구성 파일을 반환해요:

GET /api/v1/status/config

구성은 덤프된 YAML 파일로 반환돼요. YAML 라이브러리 제한 때문에 YAML 주석은 포함되지 않아요.

curl http://localhost:9090/api/v1/status/config

{
  "status": "success",
  "data": {
    "yaml": "<content>",
  }
}

Flags

다음 엔드포인트는 프로메테우스가 구성된 플래그 값을 반환해요:

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에서 새로 추가됨

런타임 정보 (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": "/",
    "hostname" : "DESKTOP-717H17Q",
    "serverTime": "2025-01-05T18:27:33Z",
    "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

모든 값은 결과 타입 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 통계 (TSDB Stats)

다음 엔드포인트는 프로메테우스 TSDB에 대한 다양한 카디널리티 통계를 반환해요:

GET /api/v1/status/tsdb

URL 쿼리 파라미터:

• limit=<number>: 각 통계 세트에 대해 반환되는 항목 수를 주어진 수로 제한해요. 기본적으로 10개 항목이 반환돼요. 최대 허용 제한은 10000이에요

쿼리 결과의 data 섹션은 다음으로 구성돼요:

• headStats: TSDB의 head 블록에 대한 다음 데이터를 제공해요:
  • 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
      }
    ]
  }
}

v3.6.0에서 새로 추가됨

TSDB 블록 (TSDB Blocks)

참고: 이 엔드포인트는 실험적이며 향후 변경될 수 있어요. 엔드포인트 이름과 반환 데이터의 정확한 형식은 프로메테우스 버전에 따라 변경될 수 있어요. 이 엔드포인트가 반환하는 정확한 메타데이터는 구현 세부사항이며 향후 프로메테우스 버전에서 변경될 수 있어요.

다음 엔드포인트는 현재 로드된 TSDB 블록과 그 메타데이터 목록을 반환해요:

GET /api/v1/status/tsdb/blocks

이 엔드포인트는 각 블록에 대해 다음 정보를 반환해요:

• ulid: 블록의 고유 ID
• minTime: 블록의 최소 타임스탬프(밀리초)
• maxTime: 블록의 최대 타임스탬프(밀리초)
• stats:
  • numSeries: 블록의 시리즈 수
  • numSamples: 블록의 샘플 수
  • numChunks: 블록의 청크 수
• compaction:
  • level: 블록의 컴팩션 레벨
  • sources: 이 블록을 컴팩트하는 데 사용된 소스 블록의 ULID 목록
• version: 블록 버전

curl http://localhost:9090/api/v1/status/tsdb/blocks

{
  "status": "success",
  "data": {
    "blocks": [
      {
        "ulid": "01JZ8JKZY6XSK3PTDP9ZKRWT60",
        "minTime": 1750860620060,
        "maxTime": 1750867200000,
        "stats": {
          "numSamples": 13701,
          "numSeries": 716,
          "numChunks": 716
        },
        "compaction": {
          "level": 1,
          "sources": [
            "01JZ8JKZY6XSK3PTDP9ZKRWT60"
          ]
        },
        "version": 1
      }
    ]
  }
}

v2.15에서 새로 추가됨

WAL 재생 통계 (WAL Replay Stats)

다음 엔드포인트는 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"
  }
}

참고: 이 엔드포인트는 서버가 ready로 표시되기 전에 사용 가능하며, WAL 재생 진행률을 모니터링하기 위해 실시간으로 업데이트돼요.

v2.28에서 새로 추가됨

자체 메트릭 (Self Metrics)

참고: 이 엔드포인트는 실험적이며 향후 변경될 수 있어요.

다음 엔드포인트는 내부 클라이언트 레지스트리에서 프로메테우스 자체의 계측 메트릭을 구조화된 JSON으로 반환해요. 이는 /metrics 엔드포인트에서 Prometheus text exposition format으로 노출되는 것과 동일한 메트릭이지만, 웹 UI의 프로그램적 접근을 위해 JSON으로 반환되는 것이에요.

응답은 io.prometheus.client.MetricFamily 프로토콜 버퍼 메시지의 표준 ProtoJSON 표현을 사용해요.

GET /api/v1/status/self_metrics

URL 쿼리 파라미터:

• metric_name_pattern=<regex>: 메트릭 이름에 대한 정규식 필터(프로메테우스 레이블 매처처럼 완전히 앵커됨). 이름이 패턴과 완전히 일치하는 메트릭 패밀리만 반환돼요. 예를 들어 metric_name_pattern=prometheus_tsdb_.*는 prometheus_tsdb_로 시작하는 모든 메트릭 패밀리를 반환해요. 선택 사항. 생략하면 모든 메트릭 패밀리가 반환돼요

각 반환된 메트릭 패밀리는 다음을 포함하는 ProtoJSON 인코딩된 MetricFamily예요:

• name: 메트릭 이름
• help: 메트릭 help 문자열
• type: 메트릭 타입(COUNTER, GAUGE, SUMMARY, HISTOGRAM, UNTYPED)
• unit: 설정된 경우 메트릭 단위(선택 사항)
• metric: 각각 다음을 포함하는 개별 메트릭 목록:
  • label: {name, value} 레이블 쌍 목록
  • gauge, counter, summary, histogram, untyped: 타입별 메트릭 데이터

curl 'http://localhost:9090/api/v1/status/self_metrics?metric_name_pattern=prometheus_build_info'

{
  "status": "success",
  "data": [
    {
      "name": "prometheus_build_info",
      "help": "A metric with a constant '1' value labeled by version, revision, branch, goversion from which prometheus was built, and the goos and goarch for the build.",
      "type": "GAUGE",
      "metric": [
        {
          "label": [
            { "name": "branch", "value": "main" },
            { "name": "goarch", "value": "amd64" },
            { "name": "goos", "value": "linux" },
            { "name": "goversion", "value": "go1.26.1-X:nodwarf5" },
            { "name": "revision", "value": "7b5a4090e38d9e1ad7697c7641234f4ed135a6c7" },
            { "name": "tags", "value": "netgo,builtinassets" },
            { "name": "version", "value": "3.11.0-rc.0" }
          ],
          "gauge": {
            "value": 1
          }
        }
      ]
    }
  ]
}

TSDB 어드민 API

이들은 고급 사용자를 위해 데이터베이스 기능을 노출하는 API예요. --web.enable-admin-api를 설정하지 않으면 이 API는 활성화되지 않아요.

스냅샷 (Snapshot)

Snapshot은 모든 현재 데이터의 스냅샷을 TSDB 데이터 디렉토리 아래의 snapshots/<timestamp>-<rand>에 만들고 디렉토리를 응답으로 반환해요. head 블록에만 존재하고 아직 디스크에 컴팩트되지 않은 데이터는 선택적으로 건너뛸 수 있어요.

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

URL 쿼리 파라미터:

• skip_head=<bool>: head 블록에 존재하는 데이터 건너뛰기. 선택 사항

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

{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

스냅샷은 이제 /snapshots/20171210T211224Z-2be650b6d019eb54에 존재해요

v2.1에서 새로 추가되었고 v2.9부터 PUT을 지원해요

시리즈 삭제 (Delete Series)

DeleteSeries는 시간 범위에서 일련의 시리즈 선택에 대한 데이터를 삭제해요. 실제 데이터는 여전히 디스크에 존재하며 향후 컴팩션에서 정리되거나 Clean Tombstones 엔드포인트를 호출해 명시적으로 정리할 수 있어요.

성공하면 204가 반환돼요.

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

URL 쿼리 파라미터:

• match[]=<series_selector>: 삭제할 시리즈를 선택하는 반복되는 레이블 매처 인자. match[] 인자를 적어도 하나는 제공해야 해요
• start=<rfc3339 | unix_timestamp>: 시작 타임스탬프. 선택 사항이며 기본값은 최소 가능 시간
• end=<rfc3339 | unix_timestamp>: 종료 타임스탬프. 선택 사항이며 기본값은 최대 가능 시간

start와 end 시간을 모두 언급하지 않으면 일치하는 시리즈에 대한 데이터베이스의 모든 데이터가 지워져요.

예시:

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에서 새로 추가되었고 v2.9부터 PUT을 지원해요

Tombstone 정리 (Clean Tombstones)

CleanTombstones는 삭제된 데이터를 디스크에서 제거하고 기존 tombstone을 정리해요. 시리즈를 삭제한 후 공간을 확보하기 위해 사용할 수 있어요.

성공하면 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을 지원해요

Remote Write 수신자 (Remote Write Receiver)

프로메테우스는 Prometheus remote write 프로토콜의 수신자(receiver)로 구성될 수 있어요. 이는 샘플을 수집하는 효율적인 방법으로 간주되지는 않아요. 특정 저용량 사용 사례에 주의해서 사용하세요. 스크레이핑을 통한 수집을 대체하고 프로메테우스를 push 기반 메트릭 수집 시스템으로 바꾸는 데는 적합하지 않아요.

--web.enable-remote-write-receiver를 설정해 remote write 수신자를 활성화해요. 활성화되면 remote write 수신자 엔드포인트는 /api/v1/write예요. 더 자세한 내용은 여기에서 확인할 수 있어요.

v2.33에서 새로 추가됨

OTLP 수신자 (OTLP Receiver)

프로메테우스는 OTLP Metrics 프로토콜의 수신자로 구성될 수 있어요. 이는 샘플을 수집하는 효율적인 방법으로 간주되지는 않아요. 특정 저용량 사용 사례에 주의해서 사용하세요. 스크레이핑을 통한 수집을 대체하는 데는 적합하지 않아요.

--web.enable-otlp-receiver를 설정해 OTLP 수신자를 활성화해요. 활성화되면 OTLP 수신자 엔드포인트는 /api/v1/otlp/v1/metrics예요.

v2.47에서 새로 추가됨

OTLP 델타

프로메테우스는 들어오는 메트릭을 delta temporality에서 누적(cumulative) 등가물로 변환할 수 있어요. 이는 OpenTelemetry Collector의 deltatocumulative를 사용해 수행돼요.

활성화하려면 --enable-feature=otlp-deltatocumulative를 전달하세요.

v3.2에서 새로 추가됨

알림 (Notifications)

다음 엔드포인트들은 프로메테우스 서버 자체에 관한 활성 상태 알림에 대한 정보를 제공해요. 알림은 웹 UI에서 사용돼요.

이 엔드포인트들은 실험적이에요. 향후 변경될 수 있어요.

활성 알림 (Active Notifications)

/api/v1/notifications 엔드포인트는 현재 활성인 모든 알림 목록을 반환해요.

GET /api/v1/notifications

예시:

curl http://localhost:9090/api/v1/notifications

{
  "status": "success",
  "data": [
    {
      "text": "Prometheus is shutting down and gracefully stopping all operations.",
      "date": "2024-10-07T12:33:08.551376578+02:00",
      "active": true
    }
  ]
}

v3.0에서 새로 추가됨

실시간 알림 (Live Notifications)

/api/v1/notifications/live 엔드포인트는 Server-Sent Events를 사용해 발생하는 실시간 알림을 스트리밍해요. 삭제된 알림은 active: false로 전송돼요. 엔드포인트에 연결할 때 활성 알림이 전송돼요.

GET /api/v1/notifications/live

예시:

curl http://localhost:9090/api/v1/notifications/live

data: {
  "status": "success",
  "data": [
    {
      "text": "Prometheus is shutting down and gracefully stopping all operations.",
      "date": "2024-10-07T12:33:08.551376578+02:00",
      "active": true
    }
  ]
}

참고: 구독자 최대 수에 도달하면 /notifications/live 엔드포인트는 204 No Content 응답을 반환해요. 수신자 최대 수는 기본값이 16인 --web.max-notifications-subscribers 플래그로 설정할 수 있어요.

GET /api/v1/notifications/live
204 No Content

v3.0에서 새로 추가됨

기능 (Features)

다음 엔드포인트는 프로메테우스 서버에서 활성화된 기능 목록을 반환해요:

GET /api/v1/features

이 엔드포인트는 프로메테우스 인스턴스에서 현재 활성화 또는 비활성화된 기능에 대한 정보를 제공해요. 기능은 api, promql, promql_functions 등과 같은 카테고리로 구성돼요.

data 섹션은 각 키가 기능 카테고리이고 각 값이 기능 이름을 활성 상태(불리언)에 매핑하는 맵인 맵을 포함해요.

curl http://localhost:9090/api/v1/features

{
  "status": "success",
  "data": {
    "api": {
      "admin": false,
      "exclude_alerts": true
    },
    "otlp_receiver": {
      "delta_conversion": false,
      "native_delta_ingestion": false
    },
    "prometheus": {
      "agent_mode": false,
      "auto_reload_config": false
    },
    "promql": {
      "anchored": false,
      "at_modifier": true
    },
    "promql_functions": {
      "abs": true,
      "absent": true
    },
    "promql_operators": {
      "!=": true,
      "!~": true
    },
    "rules": {
      "concurrent_rule_eval": false,
      "keep_firing_for": true
    },
    "scrape": {
      "start_timestamp_zero_ingestion": false,
      "extra_metrics": false
    },
    "service_discovery": {
      "azure": true,
      "consul": true
    },
    "templating": {
      "args": true,
      "externalURL": true
    },
    "tsdb": {
      "delayed_compaction": false,
      "exemplar_storage": false
    }
  }
}

참고:

• 모든 기능 이름은 snake_case 명명 규칙을 사용해요
• false로 설정된 기능은 응답에서 생략될 수 있어요
• 클라이언트는 없는 기능을 false와 동일하게 취급해야 해요
• 클라이언트는 향후 호환성을 위해 알 수 없는 기능 이름과 카테고리를 무시해야 해요

v3.8에서 새로 추가됨

더 알아보기 (Learn more)

• 인스턴트 쿼리와 범위 쿼리 예시 — API로 실제 쿼리를 날려보는 기본 예시
• Remote Read API — 외부 시스템이 프로메테우스 데이터를 읽는 원격 읽기 프로토콜
• PromQL 기초 — 시계열 셀렉터와 float 리터럴 등 쿼리 언어의 기본
• 프로메테우스 저장소(Storage) — TSDB가 데이터를 어떻게 저장하는지, 스냅샷·삭제의 배경
• 프로메테우스 기능 플래그 — promql-per-step-stats 같은 실험 기능 활성화 방법