클라이언트 라이브러리 작성

클라이언트 라이브러리 작성 (Writing client libraries)

이 문서는 Prometheus 클라이언트 라이브러리를 직접 구현하는 사람을 위한 규약 가이드예요. 메트릭 타입(카운터·게이지·히스토그램·요약)의 정확한 동작, 메트릭/라벨 명명 요구사항, 그리고 _total 접미사나 레지스트리 동작 같은 세부 규칙을 설명합니다.

새 언어용 공식 클라이언트를 만들거나 커스텀 라이브러리를 만들 때, 이 가이드를 따라야 Prometheus 에코시스템과 일관되게 동작합니다. 특히 이름 명명과 히스토그램·요약의 수집 규칙이 중요해요.

출처: 문서

본문

메트릭 타입

클라이언트 라이브러리는 네 가지 메트릭 타입을 구현해야 합니다:

  • Counter (카운터) — 단조 증가만 하는 값. .Inc()/.Add()로 증가. _total 접미사 사용이 권장됨.
  • Gauge (게이지) — 증가·감소 모두 가능한 단일 숫자. .Set()으로 설정.
  • Histogram (히스토그램) — 값을 관찰해 미리 정의된 버킷으로 집계. _bucket, _sum, _count를 노출.
  • Summary (요약) — 값을 관찰해 분위수(quantile)를 계산. quantile 라벨과 _sum, _count를 노출.

네이밍 규칙

  • 메트릭 이름은 [a-zA-Z_:][a-zA-Z0-9_:]*을 따라야 합니다(콜론은 레코딩 규칙용 예약).
  • 라벨 이름은 [a-zA-Z_][a-zA-Z0-9_]*을 따라야 합니다. __로 시작하는 라벨은 예약.
  • 카운터는 _total 접미사를 쓰는 것이 관례이며, 히스토그램·요약의 파생 시계열(_bucket, _sum, _count)의 접미사 규칙을 지켜야 합니다.

TYPE/HELP와 힌트

  • 각 메트릭은 HELP와 TYPE 주석을 노출해야 합니다.
  • 히스토그램·요약의 경우 알려진 수집(collection) 힌트도 함께 제공합니다.

레지스트리와 노출

  • 라이브러리는 "레지스트리"(모든 생성된 메트릭이 등록되는 곳) 개념을 제공해야 합니다.
  • 텍스트 익스포지션 시 라벨을 정렬된 순서로 출력하고, 이스케이프 규칙을 지켜야 합니다.
  • 메트릭을 직접 사용하지 않더라도 등록하면 자동으로 수집됩니다.

정렬과 안정성

  • 텍스트 출력에서 시계열은 일관된 순서로 정렬되어야 합니다(테스트와 파싱 안정성).
  • 메트릭이 없다 하더라도 라이브러리가 빈 응답을 만들어내는 대신 표준 구조를 따라야 합니다.

테스트

  • 새 라이브러리는 기존 클라이언트(예: Go)와 동일한 결과를 내는지 상호 테스트가 권장됩니다.
  • 텍스트 형식 출력은 Prometheus가 파싱할 수 있어야 합니다.

더 알아보기 (Learn more)