v1.metrics 개요

이 문서에서는 Telemetry (OTLP) API를 사용하여 Google Cloud 프로젝트로 전송되는 측정항목 데이터가 Cloud Monitoring 구조에 매핑되는 방법을 설명합니다. 이 API는 OpenTelemetry OTLP 프로토콜을 구현합니다. otlphttp 내보내기 도구 및 OpenTelemetry 수집기로 애플리케이션을 계측하거나 OpenTelemetry SDK를 사용하는 경우 이 API로 데이터를 전송할 수 있습니다.

OpenTelemetry는 Google Cloud에서 지원하는 오픈소스 프로젝트로, Google Cloud엔지니어가 원격 분석의 수집 및 시각화를 지원합니다.

Cloud Monitoring의 OTLP 측정항목

이 기능에는 서비스별 약관이 적용됩니다. 정식 버전(GA) 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

OpenTelemetry Collector 및 otlphttp 내보내기 도구를 사용하여 측정항목을 Cloud Monitoring에 수집하거나 OpenTelemetry SDK를 사용하여 직접 전송하면 OTLP 측정항목이 Cloud Monitoring 측정항목 구조에 매핑됩니다. 이 섹션에서는 다음을 설명합니다.

• OTLP 리소스와 Cloud Monitoring 모니터링 리소스 간의 매핑
• OTLP 측정항목과 Cloud Monitoring 측정항목 간의 매핑

모니터링 리소스 매핑

모든 측정항목 포인트는 Prometheus 매핑을 사용하여 Google Cloud Managed Service for Prometheus와 동일하게 작성됩니다.

Prometheus 매핑

Prometheus 측정항목에는 모니터링 리소스 유형 prometheus_target을 사용해야 합니다.

prometheus_target 리소스 유형의 다음 라벨은 Monarch 내에서 데이터를 스키마화하고 효율적으로 저장하는 데 사용됩니다. 이러한 속성의 값을 더 정확하게 지정할수록 쿼리 가능성과 확장성이 향상됩니다.

명시적 값이 없는 경우 사용할 대체 로직이 구현되어 있지만 이러한 라벨의 값을 설정할 때는 최대한 명시적으로 설정하는 것이 좋습니다.

다음 표에는 우선순위 순으로 라벨 값의 소스가 나와 있습니다.

prometheus-target 라벨	사용된 값 (우선순위 순서)
location(필수)	location 속성 cloud.availability_zone 속성 cloud.region 속성
cluster	cluster 속성 k8s.cluster.name 속성 __gce__: cloud.platform 속성이 gcp_compute_engine인 경우 __run__: cloud.platform 속성이 gcp_cloud_run인 경우 빈 문자열
namespace	namespace 속성 k8s.namespace.name 속성 service.namespace 속성 빈 문자열
job	job 속성 "service.namespace" + '/' + service.namespace 속성 service.name 속성 service.name 속성(unknown_service:foo이 아닌 경우) faas.name 속성 k8s.deployment.name 속성 k8s.statefulset.name 속성 k8s.job.name 속성 k8s.cronjob.name 속성 service.name 속성(unknown_service:foo인 경우) 빈 문자열
instance 비어 있으면 점 거부	instance 속성 service.instance.id 속성 faas.instance 속성 k8s.pod.name:k8s.container.name 속성 컨테이너 이름이 없는 경우 k8s.pod.name 속성 host.id 속성

측정항목 매핑

측정항목이 Prometheus 시계열 형식으로 변환됩니다. 측정항목 이름에는 도메인이 없거나 도메인이 prometheus.googleapis.com이어야 합니다. 변환 후 측정항목 이름에는 prometheus.googleapis.com 접두사와 OTLP 포인트 종류에 따른 추가 접미사가 포함됩니다. 결과 Cloud Monitoring 측정항목의 구조는 다음과 같습니다.

prometheus.googleapis.com/{metric_name}/{suffix}

또한 각 고유한 OpenTelemetry 리소스에 대해 변환은 service.name, service.instance.id, service.namespace를 제외한 모든 리소스 속성이 포함된 target_info 측정항목을 추가합니다.

수집기가 값 유형을 INT64로 지정하더라도 모든 OTLP INT64 측정항목은 Cloud Monitoring에서 DOUBLE 값 유형으로 변환됩니다. 시계열이 Monarch에 있으면 값 유형을 변경할 수 없으므로 이 변경사항이 적용됩니다. INT64 값을 지원할 때 가장 흔한 결과는 측정항목을 삭제해야만 해결할 수 있는 충돌이 발생한다는 것입니다.

참고: 이전에 INT64 target_info 측정항목을 전송한 경우 값 유형 충돌이 발생할 수 있습니다. 충돌이 발생하면 장기적으로 가장 좋은 해결책은 INT64 target_info 측정항목의 측정항목 설명자를 삭제하는 것입니다. 측정항목 범위에서 이 설명자를 삭제하려면 이 Golang 스크립트를 사용하세요.

Prometheus 측정항목 매핑

측정항목 유형은 다음과 같이 매핑됩니다.

• OTLP 게이지는 Cloud Monitoring 게이지에 매핑됩니다.
• OTLP 합계는 다음과 같이 매핑됩니다.
  • is_monotonic이 false로 설정된 경우 Cloud Monitoring 게이지
  • aggregation_temporality이 AGGREGATION_TEMPORALITY_CUMULATIVE로 설정된 경우 Cloud Monitoring 누적
  • aggregation_temporality이 AGGREGATION_TEMPORALITY_DELTA로 설정된 경우 Cloud Monitoring 델타
• OTLP 히스토그램은 aggregation_temporality 값에 따라 측정항목 종류가 누적 또는 델타인 Cloud Monitoring 분포에 매핑됩니다.
• OTLP 요약 측정항목은 각 구성요소(count, sum, 각 quantile)의 개별 시계열로 확장됩니다.
  • 개수 및 합계 측정항목의 이름에는 각각 _count 또는 _sum이 접미사로 붙고, DOUBLE 유형의 Cloud Monitoring cumulative 측정항목으로 기록됩니다.
  • 각 분위수는 quantile 라벨이 있는 DOUBLE 유형의 자체 게이지 시계열이 됩니다.

다음 표에는 측정항목 매핑이 요약되어 있습니다.

OTLP 포인트 종류	측정항목 종류 모니터링	값 유형 모니터링	접미사	참고
게이지	게이지	DOUBLE	/gauge
GAUGE (metric.metadata["prometheus.type"]="unknown")	게이지	DOUBLE	/unknown	Prometheus Unknowns는 OpenTelemetry Collector에 의해 카운터와 게이지로 분할됩니다.
SUM (단조, 누적)	누적	DOUBLE	/counter
SUM (단조, 누적, metric.metadata["prometheus.type"]="unknown")	누적	DOUBLE	/unknown:counter	Prometheus Unknowns는 OpenTelemetry Collector에 의해 카운터와 게이지로 분할됩니다.
SUM (단조, DELTA)	델타	DOUBLE	/delta
SUM (비단조, 누적)	게이지	DOUBLE	/gauge
히스토그램 (누적)	누적	명시적 버킷이 있는 분포	/histogram
지수 히스토그램 (누적)	누적	지수 버킷을 사용하는 분포	/histogram
히스토그램 (델타)	델타	명시적 버킷이 있는 분포	/histogram:delta
지수 히스토그램 (델타)	델타	지수 버킷을 사용하는 분포	/histogram:delta
SUMMARY (sum, count, quantile)	누적 누적 게이지	DOUBLE DOUBLE DOUBLE	_sum/summary:counter _count/summary /summary	요약 데이터 포인트는 여러 시계열로 작성됩니다. 하나는 개수, 합계, 계산된 각 분위수에 해당합니다. 분위수 측정항목도 quantile 라벨과 함께 생성됩니다.

googlemanagedprometheus 내보내기 도구와 Telemetry API의 차이점

Telemetry API (telemetry.googleapis.com)는 googlemanagedprometheus 내보내기 프로그램과 다르게 측정항목을 처리합니다.

• 원격 분석 API는 측정항목 이름에 마침표 (.)와 슬래시 (/) 문자를 허용합니다. googlemanagedprometheus 내보내기는 이러한 문자의 모든 인스턴스를 밑줄 (_) 문자로 변환합니다. 예를 들어 prometheus.googleapis.com/foo.bar/gauge라는 OTLP 측정항목은 OTLP 내보내기 도구에 의해 그대로 내보내지지만 googlemanagedprometheus 내보내기 도구에 의해 prometheus.googleapis.com/foo_bar/gauge으로 내보내집니다.

  측정항목이 수집되면 Cloud Monitoring은 이름을 기반으로 측정항목 설명을 만듭니다. 수집 경로에서 마침표 (.)와 슬래시 (/) 문자를 처리하는 방식의 차이로 인해 googlemanagedprometheus 내보내기를 사용하여 수집한 측정항목과 otlphttp 내보내기를 사용하여 수집한 측정항목 간에 결과 측정항목 설명자가 다릅니다. 두 수집 경로를 모두 사용하는 경우 측정항목이 두 세트가 됩니다. 쿼리할 때 완전한 결과를 얻으려면 Prometheus 버전과 OTLP 버전의 측정항목 결과를 수동으로 통합해야 합니다.

• 원하는 단위가 있는 경우 원격 분석 API는 측정항목 이름에 단위를 추가하지 않으며 카운터에 _total 접미사를 추가하지 않습니다. 따라서 Telemetry API를 사용할 때 prometheus.googleapis.com/foo/counter로 내보낸 측정항목은 googlemanagedprometheus 내보내기 도구에 의해 prometheus.googleapis.com/foo_seconds_total/counter로 내보내집니다. 이 차이점은 _total 및 _ratio 접미사에도 적용됩니다.

• API는 지수 히스토그램에서 파생된 분포 값의 sum_of_squared_deviation 값을 합성합니다. googlemanagedprometheus 내보내기는 지수 히스토그램에 대해 이 필드를 설정하지 않습니다.

• API는 모든 정수 포인트 값을 Prometheus 측정항목의 double 값으로 변환합니다.

• scope_version 또는 scope_name 라벨에 빈 값이 있는 경우 API는 해당 라벨을 설정하지 않습니다.

수집된 데이터를 확인할 수 있는 위치

Telemetry API를 통해 수집된 측정항목 데이터는 측정항목 탐색기 페이지를 사용하여 볼 수 있습니다. 측정항목 데이터 보기 및 차트 작성에 대한 자세한 내용은 측정항목 탐색기로 차트 만들기를 참고하세요.