Google Cloud Observability의 OTLP 지원

OpenTelemetry 프로토콜을 구현하는 원격 분석 (OTLP) API를 사용하여 OTLP 형식의 로그, 측정항목, trace 데이터를 Google Cloud Observability로 수집할 수 있습니다. 이 API를 사용하면 맞춤 Google Cloud 내보내기 도구를 사용하지 않고도 OpenTelemetry SDK 및 수집기에서 공급업체 중립적인 원격 분석을 수집할 수 있습니다.

원격 분석 API를 사용하여 프로젝트에 원격 분석을 전송하면 Google Cloud Observability에서 각 신호를 다음과 같이 처리합니다.

  • 로그 데이터: OTLP 로그 레코드를 로그 항목으로 변환하고 저장되도록 라우팅합니다.
  • 측정항목 데이터: 측정항목 데이터를 Cloud Monitoring의 Prometheus 시계열에 매핑합니다.
  • 추적 데이터: 일반적으로 OTLP와 일치하는 형식으로 분산된 추적을 저장합니다.

Google Kubernetes Engine에서 워크로드를 실행하는 경우 OpenTelemetry Collector를 수동으로 배포하고 관리하는 대신 GKE용 관리형 OpenTelemetry를 사용할 수 있습니다.

프로토콜 지원

OTLP 엔드포인트는 http/protobuf, http/json, grpc를 비롯한 모든 OTLP 전송 및 직렬화 프로토콜을 지원합니다. SDK를 사용하여 애플리케이션에서 직접 내보낼 때는 대부분의 SDK 내보내기 도구에서 동적 토큰 새로고침을 지원하지 않으므로 HTTP 내보내기 도구 대신 gRPC OTLP 내보내기 도구를 사용하는 것이 좋습니다.

인증

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

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

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

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

  • 사용자 또는 애플리케이션에서 사용하는 서비스 계정에 다음 Identity and Access Management (IAM) 역할을 부여합니다.

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

OTLP 수집

이 섹션에서는 로그, 측정항목, 추적 데이터가 OTLP에서 Google Cloud Observability 데이터 구조로 변환되는 방법을 설명합니다.

로그 데이터 수집

Telemetry API를 사용하여 OTLP 형식의 로그를 수집하면 로그 데이터가 Cloud Logging 로그 항목으로 변환됩니다. JSON 형식의 수신 OTLP 형식 로그 요청의 일반적인 구조는 다음과 같습니다.

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

각 logRecords 배열의 각 항목은 단일 Cloud Logging 로그 항목이 됩니다. resource 속성은 결과 LogEntry의 모니터링 리소스를 결정합니다. OTLP 형식 로그 수집에 필요한 속성에 대한 자세한 내용은 리소스 유형에 대한 OTLP 속성 매핑을 참고하세요.

OTLP 형식 로그의 수집을 지원하기 위해 Cloud Logging LogEntry 구조에는 otel이라는 추가 필드가 포함됩니다. OTLP와 Cloud Logging 데이터 모델의 구조가 다르기 때문에 otel 필드는 수신 OTLP 요청의 리소스, 범위, 엔티티 메타데이터의 사본을 보존합니다.

예를 들어 다음과 같은 OTLP resourceLogs 페이로드를 원격 분석 API에 전송하면 결과로 생성되는 각 로그 항목에 resource 필드(모니터링 리소스용)와 otel 필드가 포함됩니다(다른 탭에 표시됨).

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Cloud Logging 로그 항목은 자체 포함되어 있고 외부 리소스 스키마에 연결되지 않으므로 모든 OTLP 리소스, 범위, 엔티티 메타데이터가 각 로그 항목에 복사됩니다.

측정항목 데이터 수집

Prometheus 측정항목용 OTLP는 OpenTelemetry Collector 버전 0.140.0 이상을 사용하는 경우에만 작동합니다.

OpenTelemetry Collector 및 otlphttp 내보내기 도구를 사용하여 측정항목을 Cloud Monitoring에 수집하거나 OpenTelemetry SDK를 사용하여 직접 전송하면 OTLP 측정항목이 Cloud Monitoring 측정항목 구조에 매핑됩니다. 이러한 매핑에 대한 자세한 내용은 다음을 참고하세요.

Google Cloud Observability는 측정항목을 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 측정항목을 추가합니다.

Cloud Monitoring의 측정항목 이름과 라벨 키는 전체 UTF-8을 지원하지 않으므로 측정항목 데이터가 거부될 수 있습니다.

  • [a-zA-Z][a-zA-Z0-9_:./-]* 정규 표현식을 준수하지 않는 측정항목 이름은 거부됩니다. 측정항목 이름에 허용되는 특수 문자는 _:./- 집합에 있는 문자뿐입니다.
  • 정규 표현식 [a-zA-Z_][a-zA-Z0-9_.]*을 준수하지 않는 속성 (즉, 라벨 키)이 포함된 데이터 포인트는 거부됩니다. 라벨 키에 허용되는 유일한 특수 문자는 _. 집합에 있습니다. 라벨 값에는 모든 특수문자가 허용됩니다.

이러한 이유로 측정항목이 거부되지 않도록 하려면 replace_pattern 함수를 사용하여 측정항목 이름과 속성을 변환하세요.

Trace 데이터 수집

Telemetry API를 사용하는지 Cloud Trace API를 사용하는지와 관계없이 수신되는 trace 데이터는 OTLP와 일치하는 형식으로 저장됩니다. 하지만 Cloud Trace API보다 수집 할당량이 더 높은 Telemetry API를 사용하는 것이 좋습니다.

다음은 애플리케이션에서 Google Cloud 프로젝트로 전송될 수 있는 추적 데이터의 예입니다.

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

각 scopeSpans.spans 배열의 각 항목은 하나의 저장된 범위가 됩니다.

  • 각 스팬의 resource 필드에는 resourceSpans.resource.attributes 데이터의 사본이 포함됩니다.
  • 각 스팬의 instrumentation_scope 필드에는 scopeSpans.scope 데이터의 사본이 포함됩니다.
  • 각 스팬은 scopeSpans.spans 배열의 항목 하나에 해당합니다. traceId, spanId, kind과 같은 필드는 추적 스키마에서 이름이 비슷한 필드로 매핑됩니다.

자세한 내용은 다음 문서를 참조하세요.

결제

Telemetry API를 사용하여 수집된 로그, 측정항목, 추적 데이터의 청구는 원격 분석 신호에 따라 달라집니다. 자세한 내용은 결제 페이지를 참고하세요.

로그 데이터 결제

로그 볼륨이 변경되어 Telemetry API를 사용하여 로그를 수집할 때 Cloud Logging 스토리지 및 결제 값이 변경될 수 있습니다.

다음 두 가지가 모두 참인 경우 Google Cloud 프로젝트의 스토리지 및 결제에 가장 큰 변화가 발생합니다.

  • resource 필드에 카디널리티가 높은 속성 또는 많은 수의 속성이 포함되어 있습니다. 이러한 리소스 속성은 결과 LogEntry의 모니터링 리소스를 결정합니다.
  • scopeLogs 필드에는 logRecords 배열에 많은 항목이 포함되어 있습니다. scopeLogs.scope 필드는 모든 개별 로그 항목의 otel 필드에 복사됩니다.

이 리소스 및 범위 메타데이터는 모든 개별 로그 항목에 복사되므로 저장된 로그 볼륨이 증가할 수 있습니다.

스토리지 볼륨을 최소화하려면 다음을 권장합니다.

  • transform 프로세서와 같은 OpenTelemetry Collector 프로세서를 사용하여 데이터를 내보내기 전에 불필요한 리소스 또는 범위 속성을 삭제합니다.
  • otel 필드에 추가 메타데이터를 보존할 필요가 없는 경우 otel 필드가 채워지지 않도록 하는 기존 매핑 옵션인 gcp.use_legacy_mapping를 사용하세요.

측정항목 데이터 결제

OTLP 측정항목의 청구는 Google Cloud Managed Service for Prometheus의 측정항목에 사용되는 것과 동일한 'Prometheus 샘플 수집됨' SKU로 처리됩니다.

추적 데이터 청구

프로젝트에 trace 데이터를 전송하는 데 사용하는 API는 해당 데이터의 요금 계산 방식에 영향을 주지 않습니다.

로그, 측정항목, trace 데이터 쿼리

탐색기 페이지(로그 탐색기, 측정항목 탐색기, Trace 탐색기)를 사용하여 로그, 측정항목, trace 데이터를 쿼리할 수 있습니다. 관측 가능성 분석 페이지를 사용하여 SQL로 로그 및 추적 데이터를 분석할 수도 있습니다.

측정항목 탐색기를 사용하여 측정항목 데이터를 쿼리할 때 다음 팁이 도움이 될 수 있습니다.

  • 중요: 콜론 (:) 및 밑줄 (_) 이외의 특수 문자가 포함된 측정항목 이름 및 라벨 키를 쿼리하려면 PromQL UTF-8 사양에 따라 중괄호 ({})와 따옴표 (")로 래핑해야 합니다. 예를 들어 다음은 유효한 쿼리입니다.

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • 지수 히스토그램을 쿼리할 때 le 라벨을 유지하면 예상치 못한 결과가 반환될 수 있습니다. 더 일반적인 histogram_quantile(.99, sum by (le) (metric)) 질문은 작동할 것으로 예상됩니다.

  • 매우 드문 델타와 같은 특정 상황에서는 델타 측정항목이 올바르게 쿼리되지 않을 수 있습니다.

한도 및 할당량

Telemetry API 한도는 모든 신호 유형에 적용됩니다.

다음 할당량과 한도도 적용됩니다.

  • 로그 데이터: Cloud Logging API 할당량 및 한도가 적용됩니다.

  • 측정항목 데이터: Cloud Monitoring API 할당량 및 한도가 적용됩니다. 예를 들어 측정항목에는 200개가 넘는 라벨이 있을 수 없습니다.

    Telemetry API에서 수집한 측정항목의 기본 할당량은 분당 60,000개 요청입니다. 요청당 최대 배치 크기가 200포인트인 경우 이 할당량은 초당 200,000개 샘플의 효과적인 기본 할당량입니다. 할당량 상향 조정을 요청할 수 있습니다.

  • 추적 데이터: 적용되는 추가 할당량이나 한도가 없습니다.

다음 단계