v1.metrics 개요

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

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

권장사항

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

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

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

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

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

인증

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

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

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

  • 할당량 프로젝트를 구성합니다. 자세한 내용은 할당량 프로젝트 설정을 참조하세요.

  • 애플리케이션에서 사용하는 사용자 또는 서비스 계정에 다음 ID 및 액세스 관리 (IAM) 역할을 부여합니다.

    • 서비스 사용량 소비자 역할 (roles/serviceusage.serviceUsageConsumer) 할당량 프로젝트
    • Cloud Telemetry 작성자 역할 (roles/telemetry.writer) 이 역할을 사용하면 애플리케이션에서 로그, 측정항목, trace 데이터를 작성할 수 있습니다.

Cloud Monitoring의 OTLP 측정항목

OpenTelemetry Collector 및 otlphttp 내보내기 도구를 사용하여 측정항목이 Cloud Monitoring으로 수집되거나 OpenTelemetry SDK를 사용하여 직접 전송되면 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를 제외한 모든 리소스 속성이 포함됩니다.

Collector에서 값 유형을 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)의 개별 시계열로 확장됩니다.
    • 개수 및 합계 측정항목의 이름에는 각각 _count 또는 _sum 이 서픽스로 추가되고 DOUBLE 유형의 Cloud Monitoring 누적 측정항목으로 작성됩니다.
    • 각 분위수는 자체 게이지 시계열이 되며, 유형은 DOUBLE이고 quantile 라벨이 있습니다.

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

OTLP 포인트 종류 Monitoring 측정항목 종류 Monitoring 값 유형 서픽스 참고
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) 지원되지 않음 델타 임시 UpDownCounter는 지원되지 않습니다.
히스토그램 (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를 통해 수집된 측정항목 데이터는 측정항목 탐색기 페이지를 사용하여 볼 수 있습니다. 측정항목 데이터를 보고 차트로 표시하는 방법에 대한 자세한 내용은 측정항목 탐색기로 차트 만들기를 참조하세요.

할당량

Telemetry API와 연결된 할당량에 대한 자세한 내용은 Telemetry API 한도를 참조하세요.