OpenTelemetry 메트릭을 Prometheus로 보내는 방법
Prometheus의 OTLP/HTTP 수신기와 Collector를 구성하고, 저장된 메트릭 이름과 리소스 레이블을 확인하며 Delta 처리 방식을 선택합니다.
결제 서비스의 OpenTelemetry 메트릭을 새 백엔드로 보내기 시작했다. Collector는 배치를 받는데 Prometheus 대시보드는 여전히 비어 있다. 먼저 실제 HTTP 요청을 확인한다. Prometheus가 OTLP 메트릭을 받는 경로는 /api/v1/otlp/v1/metrics다. 요청이 그 경로에 도착했다면 계측 코드를 바꾸기 전에 Prometheus에 저장된 메트릭 이름과 레이블 집합을 확인한다.
메트릭 요청을 정확한 URL로 보내기
Prometheus 3.x에서는 OTLP 수신기를 명시적으로 켠다. 로컬에서 동작을 확인할 때는 아래 Prometheus 설정을 prometheus.yml로 저장하고 루프백에서만 수신하도록 설정한다.
prometheus --web.enable-otlp-receiver --web.listen-address=127.0.0.1:9090 --config.file=prometheus.yml
환경 변수로 구성할 수 있는 SDK에서 직접 보낼 때는 OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf와 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://127.0.0.1:9090/api/v1/otlp/v1/metrics를 지정한다. 메트릭 전용 변수에는 전체 URL이 들어간다. 공통 변수인 OTEL_EXPORTER_OTLP_ENDPOINT를 쓰는 경우에는 기본 URL을 지정하면 HTTP 내보내기가 신호별 경로를 덧붙인다. 트레이스와 로그는 각각 목적지를 설정한다.
Collector 0.159.0에서는 아래 로컬 파이프라인으로 OTLP/HTTP 메트릭을 받아 Prometheus에 전달할 수 있다. 이전 Collector 빌드에서는 내보내기 이름이 otlphttp일 수 있다.
receivers:
otlp:
protocols:
http:
endpoint: 127.0.0.1:4318
exporters:
otlp_http:
endpoint: http://127.0.0.1:9090/api/v1/otlp
service:
pipelines:
metrics:
receivers: [otlp]
exporters: [otlp_http]
Collector는 endpoint에 /v1/metrics를 붙인다. metrics_endpoint를 쓰면 전체 URL을 넣는다. 수신기에 gRPC를 구성하면 애플리케이션에서 OTLP/gRPC를 받을 수 있고, Prometheus로 내보내는 쪽은 계속 HTTP를 사용한다. Prometheus 2.47은 --enable-feature=otlp-write-receiver로 실험적 수신 기능을 도입했다. 실제 운영 버전에서 지원하는 시작 옵션을 확인한다. Prometheus OTLP 가이드 · OTLP 내보내기 사양 · Collector HTTP 내보내기
Prometheus에 저장된 시계열 확인하기
결제 서비스가 checkout.requests라는 누적 단조 증가 합계를 내보낸다고 하자. Prometheus 3.16의 기본 변환에서는 checkout_requests_total로 조회한다. 변환 과정에서 메트릭과 레이블 이름이 정규화되고 해당하는 유형과 단위 접미사가 붙는다. UTF-8을 지원하는 버전에서도 OTLP 변환 방식은 설정에 따른다. 방식을 변경하면 대시보드와 규칙의 셀렉터가 바뀔 수 있고, 유형이나 단위로 구분되던 메트릭이 충돌할 수도 있다.
job은 service.name을 바탕으로 만들며, service.namespace가 있으면 앞에 붙인다. instance는 service.instance.id에서 가져온다. 네임스페이스가 shop, 서비스 이름이 checkout, 인스턴스 ID가 checkout-1이면 checkout_requests_total{job="shop/checkout",instance="checkout-1"}로 조회할 수 있다. Prometheus 3.16은 리소스에 job 또는 instance가 될 식별 속성과 그 외 속성이 하나 이상 있을 때 target_info를 만든다. job과 instance로 조인하려면 일치하는 정보 시계열이 하나로 결정되어야 한다. 속성이 바뀌면 이전 시계열과 새 시계열이 한동안 함께 보일 수 있다.
리소스에 이미 환경 속성이 있고 모든 알림에서 필터링에 쓰려면 해당 속성을 메트릭 레이블로 승격한다. 파드 이름을 각 시계열에 붙일 필요가 없다면 target_info에 둔다. 다음 설정에서 승격된 레이블은 기본 변환 기준으로 deployment_environment_name이다.
otlp:
translation_strategy: UnderscoreEscapingWithSuffixes
promote_resource_attributes:
- deployment.environment.name
새로운 레이블 값 조합이 생기면 시계열이 나뉜다. 동시에 존재하는 시계열 수가 크게 늘지 않더라도 워크로드 재시작 등으로 값이 자주 바뀌면 시계열 생성과 소멸이 잦아진다. 실제 부하에서 활성 시계열 수, 신규 시계열 증가 속도, 메모리 여유를 확인한다. Prometheus의 리소스 속성 변환 · Prometheus 3.16 변환 코드(영어) · 관측 데이터의 높은 카디널리티
대시보드를 옮기기 전에 집계 시간성 정하기
누적 카운터는 시작 시점부터의 합계를 담고, Delta 데이터 포인트는 한 구간의 변화량을 담는다. 기존 대시보드가 누적 카운터에 rate()를 적용한다면 가능하면 SDK에서 누적값을 보낸다. Collector에서 변환할 때는 같은 스트림이 일관되게 같은 변환기로 가도록 경로를 정한다. 변환기는 상태를 유지하므로 재시작하거나 경로를 바꾸면 누적값이 달라질 수 있다.
Prometheus 3.2에서 추가된 실험 기능 otlp-deltatocumulative는 메모리에 변환 상태를 유지한다. 재시작하면 그 상태가 사라진다. 3.4에서 추가된 실험 기능 otlp-native-delta-ingestion은 Delta 값을 그대로 저장한다. 두 기능을 동시에 켤 수 없다. Delta를 그대로 저장할 때는 배포 버전의 Delta 처리 방식에 맞춰 쿼리를 검토한다. Prometheus 기능 플래그 · 버전 변경 기록
늦게 도착한 배치와 중복 쓰기 구분하기
Collector 복제본이 여럿이면 배치가 순서와 다르게 도착할 수 있다. 같은 스트림의 일부를 서로 다른 복제본이 전달한다면 도착 지연을 확인한 다음 storage.tsdb.out_of_order_time_window의 범위를 검토한다. 같은 샘플을 여러 송신자가 보내거나 서로 다른 스트림이 동일한 인스턴스 ID를 쓴다면 먼저 경로나 식별자를 바로잡는다. 허용 범위를 넓히면 그 범위 안에서 늦게 도착한 샘플을 수용할 수 있다.
루프백 외부에서 수신하기 전에 TLS를 구성하고 쓰기 권한을 제한한다. 내보내기 실패, 재시도, 큐 상태와 함께 Prometheus가 버린 샘플과 알림이 참조하는 시계열을 확인한다. Remote Write로 장기 저장소에도 보낸다면 해당 큐를 별도로 모니터링한다. 애플리케이션의 OTLP 전송 상태는 스크레이프에서 생성하는 up과 별도로 확인한다. OpenTelemetry Collector 모니터링
저장소를 바꾸기 전에 숫자 대조하기
이미 Guance 워크스페이스를 쓰고 있다면 DataKit OpenTelemetry 입력(영어)을 구성해 OTLP 메트릭을 받을 수 있다. 기존 /metrics 엔드포인트는 DataKit Prom 수집기(영어)로 스크레이프할 수 있다. 애플리케이션 카운터와 별도로 트레이스 전송 경로와 트레이스에서 산출하는 APM 메트릭을 확인한다.
전환 기간에 두 저장소로 동시에 보낸다면 같은 서비스, 시간 범위, 계측에서 나온 값을 비교한다. 이미 알고 있는 요청 수 변화와 지연 시간 히스토그램을 대조한 뒤 알림을 옮긴다. Guance PromQL 쿼리 모드(영어)에서 비교할 때도 저장된 이름, 레이블, 버킷 경계를 확인한 뒤 쿼리를 재사용한다.
