UTF-8 메트릭 이름

UTF-8 메트릭 이름 (UTF-8 names)

이 문서는 Prometheus 2.x/3.x에서 메트릭 이름·라벨 값에 UTF-8 문자를 사용하는 지원(UTF-8 이름)을 설명해요. 전통적으로 Prometheus 메트릭 이름은 ASCII 알파벳·숫자·콜론·밑줄만 허용했지만, UTF-8 지원이 활성화되면 유니코드 문자를 메트릭 이름과 라벨 값에 쓸 수 있습니다.

이는 OpenMetrics 스펙과의 정렬 및 사용자 정의 도메인(예: 사람이 읽기 좋은 메트릭 이름)을 가능하게 해요. 새 이름 명명 규칙과 함께 몇 가지 호환성 고려 사항이 따릅니다.

출처: 문서

본문

UTF-8 이름 지원

기본적으로 Prometheus 메트릭 이름은 정규 표현식 [a-zA-Z_:][a-zA-Z0-9_:]*을 따라야 합니다. 기능 플래그 utf8-name을 활성화하면 메트릭 이름과 라벨 값에 UTF-8(유니코드) 문자를 사용할 수 있게 됩니다:

prometheus --enable-feature=utf8-name

이 기능을 켜면 메트릭 이름에 한글·이모지 등 유니코드 문자를 포함할 수 있습니다.

nop-utf8와 유효성

UTF-8 기능을 활성화하면:

  • 메트릭 이름에 콜론(:), 밑줄(_)뿐 아니라 공백을 제외한 다양한 UTF-8 문자를 쓸 수 있습니다.
  • 라벨 값도 유니코드를 지원합니다.
  • PromQL에서 UTF-8 메트릭 이름을 사용할 때는 특수 문자가 포함된 경우 따옴표(")로 감싸야 할 수 있습니다.

예:

http_requests_total{method="GET"}  # 기존 ASCII 이름
도서_대출_건수_total              # UTF-8 메트릭 이름 (한글)

주의할 점

  • UTF-8 메트릭 이름을 쓰면 PromQL 쿼리에서 일부 연산자/문법과 충돌할 수 있으므로, 필요하면 이름을 따옴표로 묶거나 리버스 프록시·대시보드 호환을 확인해야 합니다.
  • OpenMetrics 텍스트 형식과의 호환성, 그리고 이전 Prometheus 버전과의 하위 호환에도 유의하세요. UTF-8 이름은 OpenMetrics 1.0 형식에서는 완전히 지원되지 않을 수 있습니다.
  • 가능하면 기존의 소문자·밑줄 명명 규칙을 유지하는 것이 좋고, UTF-8 이름은 정말 필요할 때만 쓰는 것을 권장합니다.

관련 기능

  • utf8-name 기능 플래그는 메트릭 이름과 라벨 값의 UTF-8 지원을 켭니다.
  • Alertmanager의 라벨 매처 또한 UTF-8 전환(utf8-strict-mode)을 진행 중입니다(관련 문서 참조).

더 알아보기 (Learn more)