Prometheus native histogram, 이제 써볼 때가 됐다

오늘 알게 된 건데, Prometheus 3.8에서 native histogram이 드디어 stable로 올라왔다. 나처럼 몇 년째 "언젠간 써봐야지" 하고 미뤄두신 분들 꽤 있을 것 같아서 짧게 정리해둔다.

왜 지금이냐

기존 classic histogram 써본 분들은 아마 버킷 설계에서 한 번쯤 멘붕 겪어봤을 거다. 레이턴시 분포가 어떻게 생겼는지도 모르고 le 버킷을 깎아야 하고, 세밀하게 하자니 카디널리티 폭발, 대충 하자니 P99가 거짓말을 한다. 이걸 수년째 "일단 이 정도면 됐지" 하면서 쓰고 있었다.

Native histogram은 버킷 경계를 exponential하게 자동 생성한다. 즉 설정 한 줄로 버킷 설계가 끝난다. 거기에 Remote Write 2.0에서 native form 그대로 전송이 되니 전송 비용도 같이 내려간다. 솔직히 지난 2월에 Prometheus 블로그 올라온 "Modernizing Prometheus" 글 읽고 이번엔 진짜 써야겠다 싶었다.

우리 팀에서 붙여본 후기

우리 팀은 Go 서비스 몇 개에 prometheus/client_golang으로 붙여봤다. 단, 한 가지 중요한 함정이 있다. native histogram은 protobuf exposition에서만 동작한다. 기본 text exposition으로는 안 온다.

histogram := prometheus.NewHistogramVec(
    prometheus.HistogramOpts{
        Name:                            "http_request_duration_seconds",
        Help:                            "HTTP request duration",
        NativeHistogramBucketFactor:     1.1,   // 버킷 성장률
        NativeHistogramMaxBucketNumber:  160,   // 상한
        NativeHistogramMinResetDuration: time.Hour,
    },
    []string{"method", "route"},
)

NativeHistogramBucketFactor가 핵심이다. 1.1로 두면 버킷 하나당 약 10% 씩 범위가 늘어난다. 1ms ~ 수십 초 분포까지 160개 남짓한 버킷이면 충분히 커버된다. 아래 classic 버전이랑 비교해보면 감이 온다.

// 기존 classic 방식 — 버킷 직접 설계
Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}

11개 vs 160개로 보이지만, classic 쪽은 label cardinality × 버킷 수만큼 시리즈가 늘어난다는 점을 기억해야 한다. native histogram은 1개 시리즈로 해결된다. 실측으로 TSDB head 메모리가 15%쯤 줄었다.

Prometheus 쪽 설정

스크랩 시 명시적으로 켜야 한다. 이게 어디서 막히는 분들 좀 봤는데, 기본값 off다.

scrape_configs:
  - job_name: my-app
    scrape_native_histograms: true
    scrape_protocol: PrometheusProto
    static_configs:
      - targets: ['my-app:9090']

scrape_protocol을 PrometheusProto로 명시하는 게 안전하다. 안 쓰면 text format으로 fallback 되면서 native histogram이 빠진다.

아직 걸리는 부분

몇 가지 조심할 점:

• 라이브러리 지원이 고르지 않다. Go/Java는 되지만, Python/Ruby/Node는 아직 일부 기능만 된다. 폴리글랏 조직이면 한 번에 전환은 어렵다.
• Grafana 대시보드를 그냥 복붙하면 쿼리가 안 먹는다. histogram_quantile()은 여전히 쓰지만, le 라벨이 없어서 기존 대시보드의 일부 변형 쿼리는 수정이 필요하다.
• Alertmanager 규칙도 검증 필요. SLO burn rate 계산식에 버킷 기반 합계 쓰고 있다면 한 번 다시 돌려봐야 한다.

아직 우리 팀도 일부 서비스만 전환한 상태고, classic과 native를 병행해서 한 달 정도 운영해볼 예정이다. 레이턴시 sensitive한 서비스부터 옮기는 게 안전해 보인다.

혹시 먼저 프로덕션에 전면 전환하신 분 계시면 후기 궁금합니다. 특히 Thanos/Mimir 연동 쪽에서 hiccup 있었는지.