OTLP 메트릭 유형
OTLP 메트릭 유형 (OTLP Metrics Types)
Datadog 에이전트와 OpenTelemetry Collector는 OpenTelemetry 형식(OTLP)의 메트릭을 수집할 수 있어요. 이 형식은 OpenTelemetry로 계측된 애플리케이션이 만들어 낼 수 있습니다. OTLP 메트릭은 Sums, Gauges, Histograms, Summaries 네 가지 유형으로 나뉘고, 이것들이 Datadog의 COUNT, GAUGE, DISTRIBUTION, HISTOGRAM(Explicit, Exponential) 유형으로 매핑돼요.
하나의 OTLP 메트릭이 그 의미를 나타내는 접미사를 가진 여러 Datadog 메트릭에 매핑될 수 있습니다. 이 글에서는 각 유형이 정확히 어떻게 매핑되는지 예시와 함께 설명할게요.
출처: 문서
본문
개요 (Overview)
Datadog 에이전트와 OpenTelemetry Collector는 OpenTelemetry 형식(OTLP)의 메트릭을 수집할 수 있어요. OTLP는 OpenTelemetry로 계측된 애플리케이션이 만들어 낼 수 있습니다.
Datadog 에이전트와 OpenTelemetry Collector는 다음 OTLP 메트릭 유형을 지원해요.
- Sums
- Gauges
- Histograms
- Summaries
이 OTLP 메트릭 유형들은 Datadog 메트릭 유형으로 매핑됩니다.
- COUNT
- GAUGE
- DISTRIBUTION
- HISTOGRAM (Explicit, Exponential)
하나의 OTLP 메트릭은 그 의미를 나타내는 접미사를 가진 여러 Datadog 메트릭에 매핑될 수 있어요.
참고: OpenTelemetry는 메트릭 API 인스트루먼트(Gauge, Counter, UpDownCounter, Histogram 등)를 제공하며, 그 측정값은 OTLP 메트릭(Sum, Gauge, Histogram)으로 내보낼 수 있어요. OTLP 메트릭의 다른 출처도 가능합니다. 애플리케이션과 라이브러리는 만들어진 OTLP 메트릭에 커스터마이제이션을 제공할 수 있어요. OpenTelemetry SDK 또는 OTLP 생성 애플리케이션의 문서를 읽어 만들어지는 OTLP 메트릭과 커스터마이즈 방법을 이해하세요.
참고: OpenTelemetry 프로토콜은 시간상 메트릭을 표현하는 두 가지 방식을 지원해요: Cumulative와 Delta temporality. 이는 아래 설명하는 메트릭에 영향을 줍니다. OpenTelemetry 구현의 temporality 선호도를 DELTA로 설정하세요. CUMULATIVE로 설정하면 애플리케이션(또는 컬렉터) 시작 중에 일부 데이터 포인트가 버려질 수 있기 때문이에요. 자세한 내용은 OpenTelemetry로 Delta Temporality 메트릭 만들기를 읽어 보세요.
메트릭 유형 (Metric types)
매핑 (Mapping)
Sum
OTLP Sum은 시간 창 동안 보고된 측정값의 합을 나타내요. 예를 들어 Sum은 데이터베이스에 만들어진 연결의 총 수나 엔드포인트에 대한 요청 총 수를 추적하는 데 사용할 수 있어요. Sum에는 매핑에 영향을 주는 두 가지 특징이 있습니다.
- 집계 temporality(Aggregation temporality) — cumulative 또는 delta일 수 있어요. Delta 메트릭은 시간 창이 겹치지 않지만, cumulative 메트릭은 고정된 시작 시점부터의 시간 창을 나타냅니다.
- 단조성(Monotonicity) — 단조(monotonic) sum은 절대 감소하지 않으며 기본 카운트에 더하기만 지원해요.
기본 매핑은 다음과 같습니다.
- cumulative 단조 sum의 경우, 연속된 포인트 사이의 델타가 계산되어 count로 Datadog에 보고돼요. 첫 번째 포인트는 저장되지만 생략됩니다. OTLP 페이로드의 값을 복구하려면
cumsum산술 함수를 사용하세요. - Cumulative 비단조 sum은 Datadog gauge로 내보내져요.
- Delta sum은 Datadog count로 내보내집니다.
Gauge
OTLP Gauge는 주어진 시점의 샘플링된 값을 나타내요. 주어진 시간 창의 마지막 값만 OTLP 메트릭에 포함됩니다.
OTLP Gauge는 집계 의미론(semantic)을 제공하지 않으므로 Datadog Gauge로 매핑돼요. 정수와 부동소수점 Gauge 데이터 포인트 모두 Datadog 형식의 부동소수점 숫자로 매핑됩니다.
Histogram
OTLP는 값 분포를 나타내는 두 가지 히스토그램 유형을 정의합니다.
- Explicit Bucket Histogram: 고정된, 사용자 정의 또는 SDK 기본 버킷 경계를 사용해요. 각 버킷은 경계 안에 들어오는 측정값이 몇 개인지 셉니다. sum, count, 선택적 min/max도 저장합니다.
- Exponential Histogram: 스케일 파라미터(
base = 2^(2^(-scale)))를 기반으로 동적으로 계산된 버킷 경계를 사용해요. 작은 상대 오차로 높은 동적 범위를 허용합니다. Datadog은[-4, 8]범위의 스케일을 지원해요.
두 유형 모두 매핑에 영향을 주는 한 가지 특징이 있습니다.
- 집계 temporality — cumulative 또는 delta일 수 있어요. Delta 메트릭은 시간 창이 겹치지 않지만, cumulative 메트릭은 고정된 시작 시점부터의 시간 창을 나타냅니다.
두 히스토그램 temporality 유형의 기본 매핑은 다음과 같습니다.
- Delta (기본 및 권장): Explicit Bucket과 Exponential Histogram은 네이티브로 수집되어 원래 버킷 구조가 보존된 채 저장돼요. count가 0인 히스토그램은 버려집니다.
- Cumulative: 연속된 포인트 사이의 델타가 계산되어 distribution으로 Datadog에 보고돼요. count가 0인 델타는 보고되지 않습니다.
참고: 구성 지침은 OpenTelemetry로 Delta Temporality 메트릭 만들기를 참고하세요.
백분위수 집계는 네이티브 버킷 구조에서 직접 계산됩니다. min과 max는 제공되면 저장되고, 원래 데이터에 없으면 버킷 경계에서 파생됩니다.
Summary
OTLP Summary는 시간 창 동안 모집단(population)에 대한 분위수(quantile) 정보를 전달하는 레거시 유형이에요. OTLP Summary 유형은 OpenTelemetry SDK가 만들지 않지만, 하위 호환성을 위해 다른 컴포넌트가 만들 수 있습니다.
<METRIC_NAME>.sum— 애플리케이션이 메트릭을 만들기 시작한 이후 값의 합. Datadog 인앱 유형: COUNT<METRIC_NAME>.count— 모집단의 값 수. Datadog 인앱 유형: COUNT<METRIC_NAME>.quantile,quantile태그 — 주어진 분위수의 값. Datadog 인앱 유형: GAUGE
속성 매핑 (Attribute mapping)
OTLP는 두 가지 종류의 속성을 지원해요: 데이터포인트 수준 속성(datapoint-level attributes)과 리소스 속성(resource attributes). 이 속성들은 OpenTelemetry 의미론적 규약(semantic conventions)을 따르고 잘 알려진 의미를 가질 수 있어요.
Datadog 에이전트와 Datadog OTLP 수집(intake)은 데이터포인트 수준 속성을 태그로 매핑합니다. OpenTelemetry 의미론적 규약을 따르는 리소스 속성은, 존재한다면 동등한 Datadog 규약으로 매핑돼요.
Collector의 OTLP HTTP exporter를 사용할 때 모든 리소스 속성을 태그로 추가하려면 dd-otel-metric-config 헤더에서 resource_attributes_as_tags를 구성하세요.
예시 (Example)
Sum
단일 애플리케이션에서 OpenTelemetry Counter 인스트루먼트를 사용한다고 해 볼게요. 이 인스트루먼트는 기본적으로 cumulative monotonic Sum 유형의 메트릭을 내보냅니다. 다음 표는 Datadog 동작을 요약해요.
| 수집 기간 | Counter 값 | OTLP Sum 값 | Datadog에 보고되는 값 | Datadog 인앱 유형 | 참고 |
|---|---|---|---|---|---|
| #1 | [1,1,1,2,2,2,3,3] | 15 | 없음 | COUNT | 첫 수집 기간 값은 보고되지 않아요. |
| #2 | [3,4,1,2] | 25 | 10 | COUNT | 값 사이의 차이가 보고됩니다. |
| #3 | [] | 25 | 0 | COUNT | 이 기간에 새 값이 보고되지 않았어요. |
단일 애플리케이션에서 OpenTelemetry UpDownCounter 인스트루먼트를 사용한다고 해 볼게요. 이 인스트루먼트는 기본적으로 cumulative Sum 유형의 메트릭을 내보냅니다. 다음 표는 Datadog 동작을 요약해요.
| 수집 기간 | UpDownCounter 값 | OTLP Sum 값 | Datadog에 보고되는 값 | Datadog 인앱 유형 |
|---|---|---|---|---|
| #1 | [1,1,1,2,2,2,3,3] | 15 | 15 | GAUGE |
| #2 | [3,-4,1,2] | 17 | 17 | GAUGE |
| #3 | [-1] | 16 | 16 | GAUGE |
Gauge
단일 애플리케이션에서 OpenTelemetry Gauge 인스트루먼트 temperature를 사용한다고 해 볼게요. 다음 표는 Datadog 동작을 요약해요.
| 수집 기간 | Gauge 인스트루먼트 | OTLP Gauge 값 | Datadog에 보고되는 값 | Datadog 인앱 유형 |
|---|---|---|---|---|
| #1 | 71.5 | 71.5 | 71.5 | GAUGE |
| #2 | 72 | 72 | 72 | GAUGE |
| #3 | 70 | 70 | 70 | GAUGE |
Histogram
두 웹 서버 webserver:web_1과 webserver:web_2에서 OpenTelemetry Histogram 인스트루먼트 request.response_time.histogram을 사용한다고 해 볼게요. 주어진 수집 기간에 webserver:web_1은 값 [1,1,1,2,2,2,3,3]으로 메트릭을 보고하고, webserver:web_2는 값 [1,1,2]로 같은 메트릭을 보고한다고 가정해 봅시다. 이 수집 기간 동안 다음 다섯 가지 집계가 두 웹 서버에서 수집된 모든 값의 전역 통계 분포를 나타냅니다.
| 메트릭 이름 | 값 | Datadog 인앱 유형 |
|---|---|---|
avg:request.response_time.distribution |
1.73 |
GAUGE |
count:request.response_time.distribution |
11 |
COUNT |
max:request.response_time.distribution |
3 |
GAUGE |
min:request.response_time.distribution |
1 |
GAUGE |
sum:request.response_time.distribution |
19 |
COUNT |
추가 집계를 구성하는 방법은 distribution에 대해 더 알아보기를 읽어 보세요.
또는 counters 모드를 사용 중이고, send_aggregation_metrics 플래그가 활성화되어 있으며, 히스토그램 버킷 경계가 [-inf, 2, inf]로 설정되어 있다면, 다음 메트릭이 보고됩니다.
| 메트릭 이름 | 값 | 태그 | Datadog 인앱 유형 |
|---|---|---|---|
request.response_time.distribution.count |
8 |
n/a | COUNT |
request.response_time.distribution.sum |
15 |
n/a | COUNT |
request.response_time.distribution.max |
3 |
n/a | GAUGE |
request.response_time.distribution.min |
1 |
n/a | GAUGE |
request.response_time.distribution.bucket |
6 |
lower_bound:-inf, upper_bound:2 |
GAUGE |
request.response_time.distribution.bucket |
2 |
lower_bound:2, upper_bound:inf |
GAUGE |
Summary
한 웹 서버에서 레거시 OTLP Summary 메트릭 request.response_time.summary를 제출한다고 해 볼게요. 주어진 수집 기간에 웹 서버가 값 [1,1,1,2,2,2,3,3]으로 메트릭을 보고한다고 가정해 봅시다. min, max, median 분위수가 활성화되어 있다면 다음 메트릭이 보고됩니다.
| 메트릭 이름 | 값 | 태그 | Datadog 인앱 유형 |
|---|---|---|---|
request.response_time.distribution.count |
8 |
n/a | COUNT |
request.response_time.distribution.sum |
15 |
n/a | COUNT |
request.response_time.distribution.quantile |
1 |
quantile:0 |
GAUGE |
request.response_time.distribution.quantile |
2 |
quantile:0.5 |
GAUGE |
request.response_time.distribution.quantile |
3 |
quantile:1.0 |
GAUGE |