OpenMetrics 2.0 마이그레이션

OpenMetrics 2.0 마이그레이션 (Migrating to OpenMetrics 2.0)

이 문서는 Prometheus 엑스포터와 클라이언트 라이브러리를 OpenMetrics 2.0 형식으로 마이그레이션하는 방법을 설명해요. OpenMetrics는 Prometheus가 사용하는 텍스트 익스포지션 형식의 진화 버전으로, 2.0에서는 메트릭 이름에 단위 접미사(suffix)를 명시하는 규칙(_seconds, _bytes, _total 등)과 # UNIT 메타데이터, _info 메트릭 등의 규약이 강화됩니다.

기본적으로 기존 Prometheus 익스포지션 형식(OpenMetrics 1.0 기반)은 계속 지원되지만, 2.0에서는 메트릭 이름의 단위 표기가 표준화되어 메트릭을 더 일관되게 만듭니다.

출처: 문서

본문

OpenMetrics 2.0이란

OpenMetrics 2.0은 메트릭 익스포지션 규약을 확정한 버전입니다. 핵심 변경 사항은 다음과 같습니다:

  • 단위(unit) 접미사: 메트릭 이름은 측정 단위를 이름 끝에 표준 접미사로 표현합니다. 예를 들어 초 단위는 _seconds, 바이트 단위는 _bytes, 비율은 _ratio를 붙입니다.
  • 카운터 접미사: 카운터는 _total 접미사를 권장하며, _total을 붙이면 자동으로 처리됩니다.
  • # UNIT 메타데이터: 시간 단위나 바이트 단위처럼 단위가 이름 접미사로 온전히 표현되지 않는 메트릭에는 # UNIT total <unit> 같은 주석 행으로 단위를 알려줍니다.
  • _info 메트릭: 어떤 대상의 정보(예: 버전, 리비전)를 1이라는 값을 가진 게이지로 노출하는 규약으로, _info 접미사를 사용합니다.

마이그레이션 단계

엑스포터나 클라이언트 라이브러리를 2.0에 맞추려면:

  1. 메트릭 이름 점검: 단위를 나타내는 메트릭의 이름에 표준 단위 접미사를 붙입니다. 예를 들어 http_request_duration은 http_request_duration_seconds로, memory_usage는 memory_usage_bytes로 바꿉니다.
  2. 컬렉터/헬퍼 활용: client_golang 같은 공식 클라이언트가 제공하는 단위 처리 기능을 사용하면 접미사가 자동으로 추가됩니다.
  3. # UNIT 추가: 이름으로 단위가 명확하지 않은 메트릭에 # UNIT 주석을 넣습니다.
  4. 계측 가이드 준수: Prometheus 계측 가이드와 메트릭·라벨 명명을 따릅니다.

표준 단위 접미사 예시

  • 시간: _seconds (예: http_requests_seconds)
  • 바이트: _bytes (예: filesystem_size_bytes)
  • 비율: _ratio (예: cache_hit_ratio)
  • 카운터 총합: _total (예: http_requests_total)

이렇게 이름을 정리하면 PromQL에서 단위가 헷갈리지 않고, promtool과 같은 도구가 메트릭을 더 잘 검증합니다.

호환성

기존처럼 접미사를 붙이지 않은 메트릭도 익스포지션 자체는 동작합니다. 다만 2.0 규약을 따르지 않으면 표준 단위 처리가 적용되지 않으므로, 가능한 빨리 새 규약으로 옮기는 것이 좋습니다.

더 알아보기 (Learn more)