v1.metrics 개요

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

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

권장사항

프로젝트로 trace 데이터를 전송하도록 애플리케이션을 계측할 때는 OTLP 형식 데이터를 수집기에 작성하는 내보내기 도구를 사용하는 것이 좋습니다. 그러면 수집기에서 trace 데이터를 Telemetry API로 전송합니다.Google Cloud 수집기에서 루트 URL만 지정합니다.

exporters:
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com

OpenTelemetry는 데이터 유형을 감지하고 /v1/traces, /v1/metrics, /v1/logs를 적절하게 자동으로 추가합니다. 자세한 내용은 OTLP/HTTP 요청을 참조하세요.

trace 또는 측정항목 데이터를 Telemetry API로 내보내는 예시는 다음 문서를 참조하세요.

수집기를 사용할 수 없는 경우 프로세스 내 OTLP 내보내기 도구가 포함된 OpenTelemetry 라이브러리를 사용하여 원격 분석을 Telemetry API로 전송할 수 있습니다. trace 데이터를 직접 내보내는 방법을 알아보려면 Cloud Trace 내보내기 도구에서 OTLP 엔드포인트로를 참조하세요.

인증

프로젝트로 데이터를 전송하는 데 필요한 사용자 인증 정보로 내보내기 도구를 구성해야 합니다. Google Cloud 예를 들어 수집기를 사용하는 경우 일반적으로 googleclientauth 확장 프로그램을 사용하여 Google 사용자 인증 정보로 인증합니다.

trace 데이터 직접 내보내기를 사용할 때 인증의 예시는 인증 구성을 참조하세요. 이 예시에서는 애플리케이션 기본 사용자 인증 정보 (ADC)로 내보내기 도구를 구성하고 애플리케이션에 언어별 Google 인증 라이브러리를 추가하는 방법을 보여줍니다. Google Cloud

Telemetry API를 사용하여 Google Cloud 프로젝트로 원격 분석 데이터를 전송하려면 다음 작업도 실행해야 합니다.

Cloud Monitoring의 OTLP 측정항목

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

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

모니터링 리소스 매핑

모든 측정항목 포인트는 Google Cloud Managed Service for Prometheus에 대해 있는 그대로 작성됩니다. 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__ 속성이 gcp_cloud_run인 경우 cloud.platform
  • __vae__ 속성이 gcp.agent_engine인 경우 cloud.platform
  • 빈 문자열
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이 있어야 합니다. 변환 후 측정항목 이름에는 OTLP 포인트 종류에 따라 prometheus.googleapis.com 프리픽스와 추가 서픽스가 포함됩니다. 결과 Cloud Monitoring 측정항목의 구조는 다음과 같습니다.

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

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

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

Prometheus 측정항목 매핑

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

  • OTLP 게이지는 Cloud Monitoring 게이지에 매핑됩니다.
  • OTLP 합계는 다음과 같이 매핑됩니다.
    • Cloud Monitoring 게이지 로 is_monotonic가 false로 설정된 경우
    • Cloud Monitoring 누적 aggregation_temporality이(가) AGGREGATION_TEMPORALITY_CUMULATIVE로 설정된 경우
    • Cloud Monitoring 델타 aggregation_temporality가 AGGREGATION_TEMPORALITY_DELTA로 설정된 경우
  • OTLP 히스토그램은 분포와 측정항목 종류가 누적 또는 델타인 Cloud Monitoring에 매핑되며, 이는 aggregation_temporality 값에 따라 달라집니다.
  • OTLP 요약 측정항목은 각 구성요소(count, sum, 각 quantile)의 개별 시계열로 확장됩니다.

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

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

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

Telemetry API (telemetry.googleapis.com)는 측정항목을 다르게 처리합니다. googlemanagedprometheus 내보내기 도구와:

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

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

  • Telemetry 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 값으로 변환합니다.

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

Cloud Monitoring 및 데이터 레지던시

측정항목 데이터가 저장되는 방법을 알아보려면 Cloud Monitoring의 데이터 리전성을 참조하세요.

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

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