Google Cloud Observability의 OTLP 지원

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

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

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

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

프로토콜 지원

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

인증

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

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

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

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

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

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

OTLP 수집

이 섹션에서는 로그, 측정항목, trace 데이터가 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 페이로드를 Telemetry 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 도메인이 있어야 합니다. 변환 후 측정항목 이름에는 OTLP 포인트 종류에 따라 prometheus.googleapis.com 프리픽스와 추가 서픽스가 포함됩니다. 결과 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와 일치하는 형식으로 저장됩니다. 하지만 Telemetry API는 Cloud Trace API보다 높은 수집 할당량을 제공하므로 Telemetry API를 사용하는 것이 좋습니다.

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

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

각 scopeSpans.spans 배열의 각 항목은 단일 저장된 스팬이 됩니다.

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

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

결제

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

로그 데이터 결제

Telemetry API를 사용하여 로그를 수집할 때 로그 볼륨 변경으로 인해 Cloud Logging 스토리지 및 청구 값이 변경될 수 있습니다.

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

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

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

스토리지 볼륨을 최소화하려면 다음을 수행하는 것이 좋습니다.

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

측정항목 데이터 결제

OTLP 측정항목의 청구는 Google Cloud Managed Service for Prometheus의 측정항목에 사용되는 것과 동일한 '수집된 Prometheus 샘플' SKU에 따라 계산됩니다.

trace 데이터 결제

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

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

로그 탐색기, 측정항목 탐색기, Trace 탐색기 등의 탐색기 페이지를 사용하여 로그, 측정항목, trace 데이터를 쿼리할 수 있습니다. Observability Analytics 페이지를 사용하여 SQL로 로그 및 trace 데이터를 분석할 수도 있습니다.

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

  • 중요: 콜론 (:) 및 밑줄 (_) 이외의 특수 문자가 포함된 측정항목 이름과 라벨 키를 쿼리하려면 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개 샘플의 유효한 기본 할당량입니다. 할당량 상향 조정을 요청할 수 있습니다.

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

다음 단계