OTLP 히스토그램 검수OpenTelemetry 버킷 합 countexplicit_bounds bucket_counts 검수OTLP Prometheus 누적 버킷 차이

OTLP 히스토그램 검수, 버킷 합이 전체 건수와 다를 때

OTLP 히스토그램은 구간별 건수·전체 건수·경계 배열을 함께 대조합니다. 공식 정의와 가상 8조건으로 버킷 생략, 경계 포함, Prometheus classic 형식의 인수 판정을 정리합니다.

이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스

발행 ·알파카랩스

OTLP 히스토그램은 구간별 건수와 전체 건수를 대조합니다. 2026-11-20 확인 기준, 버킷 생략은 따로 판단합니다.

AI 도구나 자동화 작업의 지연을 히스토그램으로 받았는데 전체는 6건, 버킷 건수를 더하면 13건이라면 원천 형식부터 확인해야 합니다. 구간별 건수를 기대한 자리에 누적 버킷을 넣었을 수 있습니다. 이 건수와 아래 지연값은 모두 합성 예시이며 실제 운영 성과나 장애 사례가 아닙니다.

여기서 버킷 합은 버킷 건수의 합입니다. 히스토그램의 sum 필드는 측정값의 합이며 건수 합과 다릅니다. 이 글은 explicit bucket 히스토그램 포인트의 일부 의미 제약을 검수합니다. 전체 OTLP 적합성이나 수집기의 자동 거절 동작을 보장하지 않습니다.

어떤 숫자와 배열을 함께 대조해야 하나요?#

버킷 상세가 있으면 구간별 건수의 합과 전체 count, 경계 배열과 건수 배열의 길이를 함께 확인합니다. 고정 태그의 HistogramDataPoint 정의는 경계가 증가하고 건수 배열이 경계보다 하나 길도록 정합니다. 건수 배열이 비어 있으면 경계도 비어야 하는 예외가 있습니다.

OpenTelemetry 데이터 모델은 버킷 상세를 선택 사항으로 설명합니다. 따라서 상세가 없다는 이유만으로 전체 건수가 잘못됐다고 판단하지 않습니다. 분포를 0으로 채우기보다 상세 미확인으로 표시할 조건을 정합니다.

아래는 같은 가상 단위 ms로 합의한 포인트의 일부 필드입니다. JSON의 64비트 건수는 십진 문자열로 적었습니다. 시각·속성·지표 이름·단위가 있는 전체 전송 요청은 아니며 실제 수집 결과도 아닙니다.

{
  "count": "6",
  "explicitBounds": [100, 500],
  "bucketCounts": ["2", "3", "1"]
}

어떤 표본으로 버킷 합 오류를 판정하나요?#

같은 단위와 경계에서 건수·배열 모양·경계 포함을 비교합니다. 아래 정상·보류는 로컬 설계 판정이며 Collector의 실제 오류 코드가 아닙니다. 관측값이 있는 행은 그 값을 구간에 배정하고, 나머지는 입력된 건수의 일부 제약만 대조했습니다.

합성 조건경계·건수 표본설계 판정
구간별 건수 일치경계 100·500, 건수 2·3·1, 전체 6정상: 합 6
버킷 건수가 부족경계 100·500, 건수 2·3·0, 전체 6보류: 합 5와 전체 6 불일치
건수 배열이 짧음경계 2개, 건수 2개보류: 필요한 건수 구간 3개
경계 순서가 뒤집힘경계 500·100, 건수 2·3·1보류: 경계 증가 조건 위반
경계에 걸친 관측값관측 100·500·501, 경계 100·500정상: 구간 건수 1·1·1
버킷 상세 생략경계·건수 배열 없음, 전체 6상세 미확인: 0분포로 채우지 않음
경계 없이 한 구간경계 없음, 건수 6, 전체 6정상: 전체 범위 한 구간
Prometheus classic 원천누적 버킷 2·5·6, 전체 6형식 확인: OTLP식 합산 보류
출처: OpenTelemetry·Prometheus 공식 정의를 참고한 알파카랩스 로컬 설계 검증 8조건, 2026-11-20. 합성 입력의 일부 의미 제약이며 SDK·Protobuf 인코더·Collector·운영 성능 검증이 아닙니다.

데이터 모델의 구간 정의에 따라 유한한 상한은 포함하고 하한은 제외합니다. 합성 경계가 100·500일 때 관측값 100은 첫 구간, 500은 둘째, 501은 마지막 구간입니다. 경계값을 다른 구간에 넣으면 합계가 맞아도 분포가 달라질 수 있습니다.

인수표에는 원천 형식, 지표·단위, 경계, 구간 건수, 전체 건수와 상세 생략 여부를 적습니다. 숫자의 모양만 보고 Prometheus라고 추정하지 마세요. 마지막 행은 원천이 classic 형식이라고 확인된 표본이며, 형식을 확인할 수 없는 입력은 별도로 보류합니다.

합계가 맞으면 지연 분포도 신뢰할 수 있나요?#

합계 일치는 일부 조건입니다. 단위·시계열 식별·시간 구간·측정 대상이 섞이면 같은 건수라도 다른 분포가 됩니다. 전체 건수나 평균만 확인하고 백분위까지 검증했다고 기록하지 않습니다. 상세가 없을 때 무엇을 표시할지도 화면 계약에 포함합니다.

Prometheus classic 공식 안내의 le 버킷은 해당 상한 이하를 누적합니다. 가상 누적 건수 2·5·6을 구간별 건수처럼 모두 더하면 13이 됩니다. 확인된 형식의 변환 규칙을 따로 검수해야 하며, 이 설명을 Prometheus native histogram 전체에 적용하지 않습니다.

누적 카운터 검수의 시간 누적·재시작과 버킷 누적은 다른 문제입니다. 히스토그램의 시간 집계 방식도 별도로 확인합니다. OTLP 트레이스 부분 성공 검수처럼 데이터의 모양과 전송 결과 역시 나눠야 합니다. 이번 표를 통과해도 수집 완료를 뜻하지 않습니다.

알파카랩스 AX 서비스는 인증·관측·비용·품질 평가를 플랫폼 서비스로 설명합니다. 이 자기표기는 OTLP 히스토그램의 운영 실적이나 특정 SDK 기능·모든 수집기 호환·정량 성과의 보장이 아닙니다. 필요한 지표와 검수 범위는 실제 원천 표본으로 협의합니다.

어떤 판본과 공식 문서를 기준으로 했나요?#

2026-11-20에 opentelemetry-proto v1.11.1의 고정 태그와 공식 릴리스를 확인했습니다. 릴리스 공개일은 2026-09-29입니다. 데이터 모델 사이트에는 OTel 1.62.0이 표시됐으며 이를 설치한 SDK 버전으로 해석하지 않습니다. Prometheus 안내의 개별 게시일은 미확인입니다.

metrics.proto와 데이터 모델은 필드·구간의 근거입니다. 로컬 계산은 합성 8조건의 배열·정수·구간 배정만 대조했습니다. 시각·temporality·exemplar·전체 메시지·실제 수집기·백분위 계산은 별도 범위입니다. 원천·스키마·단위·변환기가 바뀌면 다시 대조합니다.

자주 묻는 질문#

sum이 버킷 건수의 합인가요?

sum은 측정값의 합입니다. 버킷 건수의 합은 전체 count와 대조하며 두 계산을 구분해야 합니다.

버킷 배열이 없으면 오류인가요?

상세 생략 예외를 확인해야 합니다. 이번 표에서는 분포 미확인으로 두며 빈 배열을 0건 분포로 채우지 않습니다.

경계값과 같은 관측은 어느 구간에 들어가나요?

이번 explicit bucket 정의에서는 유한한 상한을 포함합니다. 가상 경계 100·500에서 값 100과 500은 각각 첫째·둘째 구간에 배정했습니다.

Prometheus의 버킷을 그대로 더해도 되나요?

classic le 버킷의 누적 건수를 OTLP 구간별 건수로 합산하지 않습니다. 원천 형식을 확인한 뒤 변환 규칙을 따로 검수합니다.

정상 판정이면 관측 연동 인수가 끝나나요?

표는 일부 데이터 제약의 합성 판정입니다. 단위·시각·식별·시간 집계·전송 결과와 실제 화면까지 별도 대조해야 합니다.

히스토그램 인수표 초안을 정리합니다#

비식별 원천 형식·단위·경계·건수와 기대하는 표시 결과를 준비하세요.

히스토그램 인수표 초안을 정리합니다

첫 범위 협의에서 비식별 관측 표본·단위·경계를 대조해 히스토그램 인수표 초안을 정리합니다. 소요 시간은 원천 형식·변환 범위·표본을 확인한 뒤 안내합니다.

히스토그램 인수표 초안 협의