Distribution(분포)

원문 보기 위키 갱신 2026.10.05

Distribution은 flush 간격 동안 여러 호스트에서 전송된 값을 집계해 전체 인프라에 걸친 통계적 분포를 측정하는 메트릭 타입이에요. 서로 다른 메트릭 타입과 달리, 글로벌 분포는 서버 측에서 Datadog의 DDSketch 자료구조를 이용해 집계되기 때문에 전역적으로 정확한 백분위 집계 같은 고급 쿼리 기능을 제공해요. 이 문서에서는 Distribution의 고급 쿼리 기능, 태그 커스터마이징, 그리고 메트릭 이름 충돌과 관련된 주의사항을 함께 살펴봐요.

출처: 문서

본문

개요

Distribution은 flush 간격 동안 여러 호스트에서 전송된 값을 집계해 전체 인프라에 걸친 통계적 분포를 측정하는 메트릭 타입이에요.

글로벌 분포는 서비스 같은 논리적 객체를 기반 호스트와 독립적으로 계측해요. Agent 측에서 집계되는 히스토그램과 달리, 글로벌 분포는 flush 간격 동안 수집된 모든 원시 데이터를 전송하고, 집계는 Datadog의 DDSketch 자료구조를 사용해 서버 측에서 발생해요.

OpenTelemetry를 사용한다면 OTLP Histogram 메트릭은 기본적으로 Datadog Distribution에 매핑돼요. 이 매핑과 사용 가능한 구성 옵션에 대한 자세한 내용은 OTLP Metric Types를 참고해 주세요.

Distribution은 다른 메트릭 타입(count, rate, gauge, histogram)에서 제공되지 않는 향상된 쿼리 기능과 구성 옵션을 제공해요.

백분위 집계 계산: Distribution은 DDSketch 자료구조로 저장되어 원시적이고 집계되지 않은 데이터를 나타내므로, 모든 호스트의 원시 데이터에 걸쳐 전역적으로 정확한 백분위 집계(p50, p75, p90, p95, p99 또는 소수점 두 자리까지 원하는 어떤 백분위든)를 계산할 수 있어요. 백분위 집계를 활성화하면 다음과 같은 고급 쿼리 기능을 사용할 수 있게 돼요.
- 어떤 시간대에 걸친 단일 백분위 값:

"지난 한 주 동안 내 애플리케이션의 99.9번째 백분위 로드 시간은 어땠나?"

어떤 시간대에 걸친 표준 편차:

"지난 한 달 동안 내 애플리케이션의 CPU 소비 표준 편차(stddev)는 얼마인가?"

메트릭 모니터의 백분위 임계값:

"지난 5분 동안 내 애플리케이션 요청 지연 시간의 p95가 200ms보다 크면 알려줘."

임계값 쿼리(Threshold Queries):

"내 서비스에 대한 요청의 95%가 5초 안에 완료되는 30일 SLO를 정의하고 싶어."

태깅 커스터마이징: 이 기능은 호스트 수준 세분성이 필요 없는 커스텀 메트릭(예: 결제 서비스의 초당 트랜잭션 수)에 대해 태깅 체계를 제어할 수 있게 해줘요.

참고: Distribution 메트릭 데이터는 다른 타입과 다르게 저장되므로, distribution에 사용된 메트릭 이름은 다른 메트릭 타입에 사용하면 안 돼요. 자세한 내용은 메트릭 이름 충돌과 가림(overshadowing)을 참고하세요.

고급 쿼리 기능 활성화

gauge나 histogram 같은 다른 메트릭 타입과 마찬가지로, Distribution은 count, min, max, sum, avg 집계를 사용할 수 있어요. Distribution은 처음에는 다른 메트릭과 같은 방식으로, 코드에서 설정한 커스텀 태그로 태깅돼요. 그런 다음 메트릭을 보고한 호스트를 기반으로 호스트 태그로 해석돼요.

하지만 Metrics Summary 페이지에서 Distribution의 모든 조회 가능한 태그에 대해 전역적으로 정확한 백분위 집계 계산 같은 고급 쿼리 기능을 활성화할 수 있어요. 그러면 p50, p75, p90, p95, p99 또는 원하는 어떤 사용자 정의 백분위(99.99 같은 소수점 두 자리까지)에 대한 집계가 제공돼요. 고급 쿼리를 활성화하면 임계값 쿼리와 표준 편차도 이용할 수 있어요.

{% video url="https://docs.dd-static.net/images/metrics/distributions/metric_detail_enable_percentiles.mp4" /%}

Distribution 메트릭에 백분위 집계를 적용하기로 선택하면 이 집계들은 그래프 작성 UI에서 자동으로 사용할 수 있어요.

{% video url="https://docs.dd-static.net/images/metrics/distributions/graph_percentiles.mp4" /%}

백분위 집계는 다양한 다른 위젯과 알림에서도 사용할 수 있어요.

어떤 시간대에 걸친 단일 백분위 값

"지난 한 주 동안 내 애플리케이션 요청 기간의 99.9번째 백분위는 어땠나?"

{% image source="https://docs.dd-static.net/images/metrics/distributions/percentile_qvw.79931614b96d1264e7fb26d3607d201d.jpg?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/metrics/distributions/percentile_qvw.79931614b96d1264e7fb26d3607d201d.jpg?auto=format&fit=max&w=850&dpr=2 2x" alt="A query value widget displaying a single value (7.33s) for the 99.99 percentile aggregation of a single metric" /%}

메트릭 모니터의 백분위 임계값 "지난 5분 동안 내 애플리케이션 요청 지연 시간의 p95가 200ms보다 크면 알려줘."

{% image source="https://docs.dd-static.net/images/metrics/distributions/percentile_monitor.5c8f0dbb69dbc1639106abbfa9117e6d.jpg?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/metrics/distributions/percentile_monitor.5c8f0dbb69dbc1639106abbfa9117e6d.jpg?auto=format&fit=max&w=850&dpr=2 2x" alt="Percentile threshold being set with a dropdown for alert conditions in a monitor " /%}

여러 메트릭에 대한 일괄 구성

각 메트릭을 개별적으로 구성하는 대신, 여러 메트릭에 대해 한 번에 백분위 집계를 활성화하거나 비활성화할 수 있어요.

Metrics Summary 페이지로 이동해 Configure Metrics 드롭다운을 클릭하세요.
Enable percentiles를 선택하세요.
해당 네임스페이스와 일치하는 모든 메트릭을 선택할 메트릭 네임스페이스 접두사를 지정하세요.
(선택 사항) 네임스페이스의 모든 메트릭에 대해 백분위를 비활성화하려면 Percentile aggregations 토글을 클릭하세요.

{% image source="https://docs.dd-static.net/images/metrics/summary/percentile_aggregations_toggle.a6fab14d04720b7881acf24c9333fb10.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/metrics/summary/percentile_aggregations_toggle.a6fab14d04720b7881acf24c9333fb10.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Toggle to manage percentile aggregations" /%}

임계값 쿼리(Threshold Queries)

Distribution 메트릭에 DDSketch로 계산된 전역적으로 정확한 백분위를 활성화하면 임계값 쿼리를 사용할 수 있어요. 임계값 쿼리에서는 원시 Distribution 메트릭 값이 숫자 임계값을 초과하거나 미달하는 경우 그 개수를 셀 수 있어요. 이 기능을 사용해 대시보드에서 비정상적인 숫자 임계값과 비교해 오류 또는 위반 횟수를 집계할 수 있어요. 또한 "지난 30일 동안 요청의 95%가 10초 안에 완료됨" 같은 SLO를 정의하는 데도 임계값 쿼리를 사용할 수 있어요.

백분위가 있는 Distribution의 임계값 쿼리를 사용하면 메트릭 제출 전에 임계값을 미리 정의할 필요가 없고, Datadog에서 임계값을 자유롭게 조정할 수 있어요.

임계값 쿼리를 사용하려면:

Metrics Summary 페이지에서 Distribution 메트릭에 백분위를 활성화하세요.
count values… 집계자를 사용해 선택한 Distribution 메트릭을 그래프로 작성하세요.
임계값과 비교 연산자를 지정하세요.

{% video url="https://docs.dd-static.net/images/metrics/distributions/threshold_queries.mp4" /%}

유사하게 임계값 쿼리를 사용해 메트릭 기반 SLO를 만들 수도 있어요.

Metrics Summary 페이지에서 Distribution 메트릭에 백분위를 활성화하세요.
새 Metric-Based SLO를 만들고, 선택한 Distribution 메트릭에 count values… 집계자를 사용한 쿼리로 "good" 이벤트 수를 분자로 정의하세요.
임계값과 비교 연산자를 지정하세요. {% image source="https://docs.dd-static.net/images/metrics/distributions/threshold_SLO.e905b152d0e18dfbdcfae9bba3517f58.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/metrics/distributions/threshold_SLO.e905b152d0e18dfbdcfae9bba3517f58.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Threshold Queries for SLOs" /%}

태깅 커스터마이징

Distribution은 호스트 수준 세분성이 의미가 없는 커스텀 메트릭에 대해 태깅을 제어할 수 있는 기능을 제공해요. 태그 구성은 유지하고 싶은 태그의 *허용 목록(allowlist)*이에요.

태깅을 커스터마이즈하려면:

Metrics Summary 테이블에서 커스텀 Distribution 메트릭 이름을 클릭해 메트릭 상세 사이드 패널을 엽니다.
Manage Tags 버튼을 클릭해 태그 구성 모달을 엽니다.
Custom… 탭을 클릭해 쿼리에 사용할 수 있게 유지할 태그를 커스터마이즈하세요.

참고: 허용 목록 기반 태그 커스터마이징에서는 태그 제외가 지원되지 않아요. !로 시작하는 태그 추가는 허용되지 않습니다.

{% image source="https://docs.dd-static.net/images/metrics/distributions/dist_manage.f2eeee61c6d883f90441dc3bf21a91f7.jpg?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/metrics/distributions/dist_manage.f2eeee61c6d883f90441dc3bf21a91f7.jpg?auto=format&fit=max&w=850&dpr=2 2x" alt="Configuring tags on a distribution with the Manage Tags button" /%}

메트릭 이름 충돌과 가림(overshadowing)

Distribution 메트릭은 비분포 타입(count, rate, gauge, histogram)과 다르게 데이터를 저장해요. 같은 메트릭 이름이 Distribution 데이터와 비분포 데이터를 모두 받으면, Datadog의 쿼리 시스템은 Distribution 데이터를 우선시해요. 이 동작을 가림(overshadowing) 이라고 해요.

두 타임시리즈가 모두 저장되므로 데이터가 손실되진 않아요. 하지만 쿼리는 Distribution 데이터만 반환하므로 비분포 타임시리즈는 보이지 않게 돼요. 가림은 첫 번째 Distribution datapoint가 도착하는 순간부터 적용돼요.

가림의 증상

가림은 일반적으로 다음 중 한 가지 방식으로 나타나요.

구성 변경을 하지 않았는데도 메트릭의 태그나 데이터가 갑자기 바뀌는 것처럼 보여요.
metrics API를 통해 태그 구성을 업데이트할 때 다음 오류가 표시돼요.
```
New tag-configuration conflicts with existing configuration for <METRIC_NAME>
```
메트릭이 예상과 다른 타입으로 보고돼요(예: count를 기대했는데 distribution으로 보임).

메트릭의 현재 타입을 확인하려면 Metrics Summary 페이지를 참고해 주세요.

가림 피하기

메트릭 이름은 어느 방향으로든 타입 간에 고유해야 해요. 자주 간과되는 두 가지 경우가 있어요.

로그 기반 메트릭: 로그 기반 메트릭은 항상 Distribution으로 제출되므로, 선택한 메트릭 이름이 이미 count, gauge, rate 또는 histogram 메트릭으로 존재하지 않는지 확인하세요.
은퇴된 이름: 더 이상 데이터를 받지 않는 이름도 원래 타입이 계속 차지하고 있어요. 다른 타입으로 재사용하지 마세요.

가림 해결하기

메트릭이 이미 가려졌다면 distribution 데이터 또는 비분포 데이터 중 하나를 유지하기로 선택해야 해요. 같은 메트릭 이름 아래에서 둘 다 유지할 수는 없어요.

Datadog Support에 다음을 알려주세요.

영향을 받는 메트릭 이름
보존하고 싶은 데이터 타입

충돌이 해결된 후에는 향후 제출에서 메트릭 이름을 변경해 각 메트릭 이름이 하나의 타입에만 사용되도록 하세요.

감사 이벤트(Audit events)

태그 구성이나 백분위 집계 변경 시 이벤트 탐색기에 이벤트가 생성돼요. 이 이벤트는 변경 내용을 설명하고 변경을 수행한 사용자를 표시해요.

Distribution 메트릭에서 태그 구성을 생성, 업데이트 또는 제거했다면 다음 이벤트 검색으로 예시를 볼 수 있어요.

https://app.datadoghq.com/event/stream?tags_execution=and&per_page=30&query=tags%3Aaudit%20status%3Aall%20priority%3Aall%20tag%20configuration

Distribution 메트릭에서 백분위 집계를 추가하거나 제거했다면 다음 이벤트 검색으로 예시를 볼 수 있어요.

https://app.datadoghq.com/event/stream?tags_execution=and&per_page=30&query=tags%3Aaudit%20status%3Aall%20priority%3Aall%20percentile%20aggregations

더 알아보기 (Learn more)

추가로 도움이 되는 문서, 링크, 글: