데이터 모델

데이터 모델 (Data model)

Prometheus는 본질적으로 모든 데이터를 시계열로 저장해요. 시계열은 같은 메트릭과 같은 라벨 차원 집합에 속하는 타임스탬프 값들의 스트림입니다. 저장된 시계열 외에도, Prometheus는 쿼리 결과로 임시 파생 시계열을 생성할 수 있어요.

이 문서는 시계열을 식별하는 메트릭 이름과 라벨의 규칙, 그리고 하나의 값(샘플)을 구성하는 요소를 설명합니다. "라벨이 차원(dimension)이다"라는 핵심을 이해하는 것이 PromQL 쿼리와 계측 설계의 첫걸음이에요.

출처: 문서

본문

Prometheus는 모든 데이터를 시계열로 저장합니다. 이는 같은 메트릭과 같은 라벨 차원의 집합에 속하는 타임스탬프 값들의 스트림입니다. 저장된 시계열 외에도, Prometheus는 쿼리 결과로 임시 파생 시계열을 생성할 수 있습니다.

메트릭 이름과 라벨 (Metric names and labels)

모든 시계열은 메트릭 이름과 라벨이라는 선택적 키-값 쌍으로 고유하게 식별됩니다.

메트릭 이름:

  • 메트릭 이름은 측정되는 시스템의 일반적인 특징을 지정해야 합니다(SHOULD). 예: http_requests_total — 수신된 HTTP 요청의 총 개수.
  • 메트릭 이름은 모든 UTF-8 문자를 사용할 수 있습니다(MAY).
  • 가장 좋은 경험과 호환성을 위해 메트릭 이름은 정규 표현식 [a-zA-Z_:][a-zA-Z0-9_:]*과 일치해야 합니다(SHOULD). 그 범위 밖의 메트릭 이름은 PromQL에서 사용할 때 따옴표가 필요합니다(아래 경고와 UTF-8 가이드 참조).

참고: 콜론(:)은 사용자 정의 레코딩 규칙(recording rules)용으로 예약되어 있습니다. 엑스포터나 직접 계측에서는 사용하면 안 됩니다(SHOULD NOT).

메트릭 라벨:

라벨을 사용하면 같은 메트릭 이름의 서로 다른 인스턴스를 포착할 수 있습니다. 예를 들어 /api/tracks 핸들러에 POST 메서드를 사용한 모든 HTTP 요청을 라벨로 표현할 수 있어요. 우리는 이를 Prometheus의 "차원 데이터 모델(dimensional data model)"이라고 부릅니다. 쿼리 언어는 이 차원들을 기반으로 필터링과 집계를 허용합니다. 어떤 라벨의 값이든 변경(라벨 추가·제거 포함)하면 새 시계열이 생성됩니다.

  • 라벨 이름은 모든 UTF-8 문자를 사용할 수 있습니다(MAY).
  • __(밑줄 두 개)로 시작하는 라벨 이름은 Prometheus 내부용으로 반드시 예약되어야 합니다(MUST).
  • 가장 좋은 경험과 호환성을 위해 라벨 이름은 정규 표현식 [a-zA-Z_][a-zA-Z0-9_]*과 일치해야 합니다(SHOULD). 그 정규 표현식 밖의 라벨 이름은 PromQL에서 사용할 때 따옴표가 필요합니다(UTF-8 가이드 참조).
  • 라벨 값은 모든 UTF-8 문자를 포함할 수 있습니다(MAY).
  • 빈 라벨 값을 가진 라벨은 존재하지 않는 라벨과 동등한 것으로 간주됩니다.

경고: 메트릭·라벨 이름에 대한 UTF-8 지원은 Prometheus v3.0.0에서 비교적 최근에 추가되었습니다. 더 넓은 생태계(다운스트림 PromQL 호환 프로젝트와 벤더, 도구, 서드파티 계측, 수집기 등)가 새 따옴표 메커니즘, 완화된 검증 등을 채택하는 데 시간이 걸릴 수 있습니다. 최상의 호환성을 위해 권장("SHOULD") 문자 집합을 지키는 것이 좋습니다.

INFO: 메트릭과 라벨 명명 모범 사례도 참고하세요.

샘플 (Samples)

샘플은 실제 시계열 데이터를 구성합니다. 각 샘플은 다음으로 구성됩니다:

표기법 (Notation)

메트릭 이름과 라벨 집합이 주어지면, 시계열은 자주 다음 표기법으로 식별됩니다:

<metric name>{<label name>=<label value>, ...}

예를 들어 메트릭 이름 api_http_requests_total과 라벨 method="POST", handler="/messages"를 가진 시계열은 이렇게 씁니다:

api_http_requests_total{method="POST", handler="/messages"}

이것은 OpenTSDB가 사용하는 것과 같은 표기법입니다.

권장 집합 밖의 UTF-8 문자를 가진 이름은 따옴표를 사용해야 합니다:

{"<metric name>", <label name>="<label value>", ...}

메트릭 이름은 특수 라벨 이름(__name__="<metric name>")을 가진 라벨 쌍으로 내부적으로 표현되므로, 다음 표기법을 쓸 수도 있습니다:

{__name__="<metric name>", <label name>="<label value>", ...}

더 알아보기 (Learn more)