접미사와 콜론은 규약이 아니라 계약이다

한 줄 요약

프로메테우스의 메트릭 이름 규칙은 취향이 아니라 도구가 의존하는 계약입니다. _total 은 카운터라는 선언이고, _bucket·_sum·_count 는 히스토그램의 세 구성 요소이며, 콜론은 레코딩 룰에만 허용됩니다. 이름만 보고 무엇인지 알 수 있어야 대시보드와 알림이 서로를 믿을 수 있습니다.

왜 이게 필요했나

타입을 잘못 고르면 나중에 하고 싶은 계산이 원리적으로 불가능해집니다. 가장 흔한 사고는 지연 시간을 게이지로 기록하는 것입니다.

last_latency = Gauge("http_request_duration_seconds", "요청 처리 시간")last_latency.set(elapsed)   # 앞선 값들은 전부 사라진다

스크레이프 간격이 15초이고 초당 요청이 500건이면 7,500건 중 단 1건의 값만 저장됩니다. 나머지는 존재한 적도 없는 것이 됩니다. 이 시계열로는 p99 를 구할 수 없고, 나중에 데이터를 다시 처리해도 복원되지 않습니다.

어떻게 동작하나

익스포지션 포맷은 사람이 읽을 수 있는 텍스트입니다. 한 줄에 메트릭 이름, 중괄호 안의 레이블, 값이 들어가고 # HELP 와 # TYPE 주석이 붙습니다. 표준 경로는 /metrics 이고, 다른 경로를 쓰면 스크레이프 설정에서 metrics_path 를 지정해야 합니다. OpenMetrics 는 이 포맷을 표준화한 것으로 exemplar 와 created timestamp 를 추가했습니다.

타입 네 가지

| 타입 | 노출되는 시계열 | 답하는 질문 |
| --- | --- | --- |
| Counter | x_total | 초당 얼마나 늘어나는가 (rate 필요) |
| Gauge | x | 지금 값이 얼마인가 |
| Histogram | x_bucket{le}, x_sum, x_count | 분포가 어떤가 (서버에서 분위수 추정) |
| Summary | x{quantile}, x_sum, x_count | 이 프로세스 안에서의 분위수 |

Summary 가 서비스 수준에서 쓸모없는 이유는 앞 모듈에서 다룬 성질 하나 때문입니다. 분위수는 합칠 수 없습니다. Summary 는 클라이언트가 이미 계산해 버린 분위수를 내보내므로, 파드 40개의 p99 를 하나로 합칠 방법이 없습니다. Histogram 은 정확도를 버킷 해상도만큼 포기하는 대신 집계 가능성을 얻습니다. 분산 시스템에서는 거의 항상 후자가 맞는 거래입니다.

어디서 나오는 메트릭인가도 시험 단골입니다.

• node_cpu_seconds_total — Node Exporter (호스트 하드웨어·OS)
• container_cpu_usage_seconds_total — cAdvisor (kubelet 내장, 컨테이너 자원)
• kube_deployment_spec_replicas — kube-state-metrics (API 오브젝트의 상태)
• process_cpu_seconds_total — 클라이언트 라이브러리가 자동으로 붙이는 프로세스 메트릭
• probe_success — Blackbox Exporter (HTTP·TCP·DNS 프로브)

레코딩 룰은 계산을 쿼리 시점에서 평가 시점으로 옮깁니다. 만들 기준은 넷입니다. 같은 표현식이 세 곳 이상에서 반복될 때, 쿼리가 2초를 넘을 때, 알림이 무거운 표현식을 매 평가마다 돌릴 때, 고카디널리티 원본을 집계해 오래 보관하고 싶을 때.

이름은 수준:메트릭:연산 규약을 따릅니다. route:http_requests:rate5m 을 보면 라우트 수준으로 집계된 요청 수의 5분 rate 라는 것이 이름만으로 읽힙니다. 콜론은 원본 메트릭 이름에는 절대 쓰지 않기 때문에 이름만 보고 "이건 파생된 시계열"임을 알 수 있습니다.

계층 구조가 핵심입니다. 계층 1이 원본을 한 번 스캔해 놓으면 계층 2는 그 결과만 참조하므로 원본 스캔이 한 번으로 끝납니다. 다만 그룹 안에서는 위에서 아래로 평가되므로 계층 1이 계층 2보다 위에 있어야 합니다.

현장에서 만나는 모습

레코딩 룰 2,000개를 한꺼번에 넣었다가 약 100만 시계열이 생기고 WAL 이 폭증한 적이 있습니다. 배포 전 계산은 간단합니다. 라우트가 120개인데 윈도 5종에 대해 각각 규칙을 만들면 600개, 규칙이 50개면 3만 개입니다. 룰 파일은 코드처럼 리뷰하지만 비용은 새 메트릭과 같습니다.

검증은 CI 에서 돕니다. promtool check rules 로 문법을, promtool test rules 로 기대값을 확인합니다. 특히 단위 테스트에 기대값을 직접 계산해 적어 두면, 나중에 누군가 규칙을 "최적화"하다가 의미를 바꿨을 때 CI 가 잡아냅니다. promtool 이 잡아 주지 못하는 것도 있습니다 — 규칙끼리의 순환 참조는 사람이 리뷰에서 봐야 합니다.

다음 실습에서 할 것

/root/pca-rules/ 아래에 레코딩 룰 파일과 알림 룰 파일을 쓰고, level:metric:operations 네이밍으로 2단 계층을 만듭니다. 그다음 promtool 단위 테스트 파일에 입력 시계열과 기대값을 직접 계산해 넣고, 마지막으로 같은 내용을 Prometheus Operator 가 읽는 PrometheusRule CR 로 옮깁니다.