메트릭과 라벨 이름 짓기

메트릭과 라벨 이름 짓기 (Metric and label naming)

메트릭 이름을 어떻게 짓느냐는 모니터링의 품질을 좌우해요. 이 문서는 프로메테우스에서 메트릭과 라벨 이름을 지을 때 권장하는 규칙(best practices)과 스타일 가이드를 정리한 거예요. 이 규칙들은 사용하는 데 필수는 아니지만, 잘 따르면 메트릭을 읽고, 공유하고, 자동화 도구와 연동하기 훨씬 편해져요.

다만 개별 조직이 명명 규칙 같은 일부 관행을 자신의 방식으로 접근하고 싶을 수 있어요. 이 문서는 강제가 아니라 지침이라는 점을 기억해 두세요. 특히 단위 접미사와 타입 접미사를 이름에 포함해야 하는 이유를 설명한 부분은 프로메테우스가 왜 그렇게 하는지 이해하는 데 큰 도움이 돼요.

출처: 문서

본문

이 문서에 제시된 메트릭과 라벨 규칙은 프로메테우스를 사용하는 데 필수는 아니지만, 스타일 가이드이자 모범 사례 모음으로 역할할 수 있어요. 개별 조직은 이 관행 중 일부, 예를 들어 명명 규칙을 다르게 접근하고 싶을 수 있어요.

메트릭 이름 (Metric names)

메트릭 이름은...

  • ...데이터 모델의 유효 문자를 준수해야 해요(MUST).

  • ...메트릭이 속한 도메인과 관련된 (단일 단어) 애플리케이션 접두사를 가져야 해요(SHOULD). 이 접두사를 클라이언트 라이브러리에서는 namespace라고 부르기도 해요. 애플리케이션 특유의 메트릭의 경우 접두사는 보통 애플리케이션 이름 자체예요. 하지만 때로는 클라이언트 라이브러리가 내보내는 표준화된 메트릭처럼 더 일반적인 메트릭도 있어요. 예:

    • prometheus_notifications_total (Prometheus 서버 특유의 메트릭)

    • process_cpu_seconds_total (많은 클라이언트 라이브러리가 내보내는 메트릭)

    • http_request_duration_seconds (모든 HTTP 요청용)

  • ...단일 단위를 가리켜야 해요(예: 초와 밀리초를 섞지 마세요) (MUST). 그리고 단일 양을 가리켜야 해요(예: 요청 크기와 요청 지속시간을 섞지 마세요).

  • ...기본 단위를 사용해야 해요(SHOULD)(예: 초, 바이트, 미터 — 밀리초, 메가바이트, 킬로미터가 아니라요). 기본 단위 목록은 아래를 보세요.

  • ...단위를 복수형으로 설명하는 접미사를 가져야 해요(SHOULD). 누적 카운트는 해당하는 경우 단위에 더해 total 접미사를 가진다는 점에 주의하세요. 또한 이것은 좁은 의미의 단위(아래 표의 단위 같은)에 적용되며, 일반적으로 셀 수 있는 것에는 적용되지 않아요. 예를 들어 connections이나 notifications는 이 규칙의 단위로 간주되지 않고 메트릭 이름 끝에 있을 필요가 없어요. (다음 문단의 예도 참고하세요.)

    • http_request_duration_seconds

    • node_memory_usage_bytes

    • http_requests_total (단위 없는 누적 카운트용)

    • process_cpu_seconds_total (단위가 있는 누적 카운트용)

    • foobar_build_info (실행 중인 바이너리에 대한 메타데이터를 제공하는 유사 메트릭용)

    • data_pipeline_last_record_processed_timestamp_seconds (데이터 처리 파이프라인에서 가장 최근에 처리된 레코드의 시각을 추적하는 타임스탬프용)

  • ...다른 모든 규칙을 따른다면, 메트릭 이름 목록을 사전순으로 정렬할 때 편리한 그룹핑으로 이어지도록 이름 구성 요소의 순서를 정할 수 있어요(MAY). 다음 예는 공통 이름 구성 요소를 앞에 두어서 관련 메트릭들이 함께 정렬되게 해요.

    • prometheus_tsdb_head_truncations_closed_total

    • prometheus_tsdb_head_truncations_established_total

    • prometheus_tsdb_head_truncations_failed_total

    • prometheus_tsdb_head_truncations_total

    다음 예도 유효하지만, 다른 트레이드오프를 따르는 거예요. 개별적으로 읽기는 더 쉽지만, prometheus_tsdb_head_series 같은 무관한 메트릭이 그 사이에 정렬될 수 있어요.

    • prometheus_tsdb_head_closed_truncations_total

    • prometheus_tsdb_head_established_truncations_total

    • prometheus_tsdb_head_failed_truncations_total

    • prometheus_tsdb_head_truncations_total

  • ...모든 라벨 차원에서 같은 논리적 측정 대상(thing-being-measured)을 나타내야 해요(SHOULD).

    • 요청 지속시간

    • 데이터 전송 바이트 수

    • 백분율로서의 순간 리소스 사용

엄지손가락 규칙으로, 주어진 메트릭의 모든 차원에 대한 sum() 또는 avg() 중 하나가 의미 있어야 해요(꼭 유용할 필요는 없지만요). 그것이 의미가 없다면 데이터를 여러 메트릭으로 나누세요. 예를 들어 여러 큐의 용량을 하나의 메트릭에 두는 것은 좋지만, 큐의 용량과 큐의 현재 요소 수를 섞는 것은 좋지 않아요.

메트릭 이름에 단위와 타입 접미사를 포함하는 이유 (Why include unit and type suffixes in metric names?)

일부 메트릭 명명 규칙(예: OpenTelemetry)은 메트릭 이름에 메트릭 단위와 타입 정보를 포함하는 것을 권장하지 않거나 허용하지도 않아요. 흔한 주장은 그런 정보는 이미 다른 곳(예: 스키마, 메타데이터, 다른 라벨 등)에 정의돼 있다는 거예요.

프로메테우스는 그 정보를 다른 곳에 저장하더라도, 다음의 실용적인 이유 때문에 메트릭 이름에 단위와 타입을 포함하는 것을 강력히 권장해요.

  • 메트릭 소비 신뢰성과 UX: 현대적 UI로 상호작용하며 PromQL에서 그런 메트릭을 사용할 때, 메트릭의 타입과 단위에 대한 풍부한 정보를 표시하는 것이 가능해요(자동 완성, 오버레이, 팝업). 불행히도 강력한 UI에서의 대화형 ad-hoc 쿼리가 사용자가 메트릭과 상호작용하는 유일한 방식은 아니에요. 메트릭 소비 생태계는 방대해요. 소비의 대부분은 알림(alerting), 기록(recording), 오토스케일링, 대시보드, 분석, 처리 등 다양한 관측 도구에 대한 평범한 YAML 구성 형태로 이뤄져요. 특히 모니터링/SRE 인시던트 관행 동안 평범한 YAML에서 PromQL 표현식을 보고 작업하는 메트릭 타입과 단위를 이해하는 것이 중요해요.

  • 메트릭 충돌: 채택이 늘어나고 메트릭이 시간에 따라 변함에 따라, 메트릭 이름에 단위와 타입 정보가 없으면 특정 시리즈가 충돌하는 경우가 있어요(예: 초와 밀리초에 대한 process_cpu).

라벨 (Labels)

측정 대상의 특성을 구분하는 데 라벨을 사용하세요.

  • api_http_requests_total - 요청 타입 구분: operation="create|update|delete"

  • api_request_duration_seconds - 요청 단계 구분: stage="extract|transform|load"

라벨 이름을 메트릭 이름에 넣지 마세요. 이는 중복을 도입하고, 해당 라벨이 집계되어 사라지면 혼란을 일으킬 거예요.

주의: 키-값 라벨 쌍의 모든 고유 조합은 새로운 타임시리즈를 나타낸다는 것을 기억하세요. 이것은 저장되는 데이터의 양을 극적으로 늘릴 수 있어요. 사용자 ID, 이메일 주소, 또는 다른 무한한 값 집합처럼 높은 카디널리티(많은 서로 다른 라벨 값)의 차원을 저장하는 데 라벨을 사용하지 마세요.

기본 단위 (Base Units)

프로메테우스는 하드코딩된 단위가 없어요. 더 나은 호환성을 위해 기본 단위를 사용해야 해요. 다음은 기본 단위와 함께 몇 가지 메트릭 패밀리를 나열해요. 목록은 완전하지 않아요.

패밀리 기본 단위 비고
시간 seconds
온도 celsius 실용적인 이유로 kelvin보다 celsius가 선호돼요. kelvin은 색온도나 온도가 절대적이어야 하는 특수한 경우에 기본 단위로 허용돼요.
길이 meters
바이트 bytes
비트 bytes 서로 다른 메트릭을 결합할 때 혼란을 피하려면 비트가 더 흔해 보이는 곳에서도 항상 bytes를 사용하세요.
백분율 ratio 값은 0–1(0–100이 아니라)이에요. ratio는 disk_usage_ratio 같은 이름의 접미사로만 사용돼요. 일반적인 메트릭 이름은 A_per_B 패턴을 따라요.
전압 volts
전류 amperes
에너지 joules
전력 joules 카운터를 내보내는 것을 선호하세요. 그러면 rate(joules[5m])이 와트 단위의 전력을 줘요.
질량 grams kilo 접두사의 문제를 피하려고 grams가 kilograms보다 선호돼요.

더 알아보기 (Learn more)