API 안정성 보장

API 안정성 보장 (API stability guarantees)

프로메테우스의 어떤 기능이 "안정(stable)"하고 어떤 기능이 "불안정(unstable)"한지 공식적으로 정리한 문서예요. 프로메테우스를 운영하면서 버전을 올릴 때 무엇이 깨질 수 있고 무엇이 안전한지 판단하는 기준이 되므로, 업그레이드 전에 꼭 확인하는 게 좋아요.

프로메테우스는 메이저 버전 내에서 API 안정성을 약속하며 핵심 기능의 파괴적 변경을 피하려고 해요. 다만 외형적인 기능, 개발 중이거나 제3자 서비스에 의존하는 일부 기능은 이 보장에서 제외돼요. 아래 목록을 보면서 어떤 기능이 믿고 써도 되는지 파악해 보세요.

출처: 문서

본문

프로메테우스는 메이저 버전 내에서 API 안정성을 약속하며, 핵심 기능의 파괴적 변경을 피하려고 해요. 다만 외형적인 기능, 아직 개발 중이거나 제3자 서비스에 의존하는 일부 기능은 이 보장 대상이 아니에요.

3.x에서 안정적인(stable) 것으로 간주되는 것:

  • 쿼리 언어와 데이터 모델
  • 경고(alerting) 및 기록(recording) 규칙
  • 수집 exposition 형식
  • v1 HTTP API(대시보드와 UI가 사용), 실험적이라고 명시적으로 표시된 엔드포인트 제외
  • 구성 파일 형식(서비스 디스커버리 remote read/write 제외, 아래 참조)
  • 규칙/알림 파일 형식
  • 콘솔 템플릿 구문과 의미
  • 1.0 사양에 따른 remote write 전송과 수신
  • 에이전트 모드
  • OTLP 수신자 엔드포인트

3.x에서 불안정한(unstable) 것으로 간주되는 것:

  • 실험적이거나 변경될 수 있다고 표시된 모든 기능, 다음을 포함:
    • double_exponential_smoothing PromQL 함수
    • Remote read 및 remote read 엔드포인트
    • 서버 측 HTTPS와 기본 인증
    • 서비스 디스커버리 연동(static_configs, file_sd_configs, http_sd_config 제외)
    • 서버의 일부인 패키지의 Go API
    • 웹 UI가 생성하는 HTML
    • 프로메테우스 자체의 /metrics 엔드포인트 메트릭
    • 정확한 디스크상 형식. 다만 잠재적 변경은 정방향 호환되며 프로메테우스가 투명하게 처리해요
    • 로그의 형식

프로메테우스 2.x의 안정성 보장은 2.x 문서에서 찾을 수 있어요.

실험적/불안정으로 표시된 기능을 사용하지 않는 한, 메이저 버전 내 업그레이드는 보통 운영 조정 없이 수행할 수 있고 무엇이 깨질 위험도 거의 없어요. 파괴적 변경은 릴리스 노트에서 CHANGE로 표시돼요.

더 알아보기 (Learn more)