OTLP 수집 개요

이 문서에서는 OpenTelemetry 프로토콜을 구현하는 Telemetry (OTLP) API telemetry.googleapis.com의 사용을 소개합니다. Telemetry API를 사용하면 OTLP 형식의 로그, 측정항목, trace 데이터를 Google Cloud Observability로 수집할 수 있습니다.

  • OTLP 로그 레코드는 로그 항목 으로 변환된 후 라우팅되고 저장됩니다. 변환 프로세스에 대한 자세한 내용은 이 문서의 OTLP 로그 수집 섹션을 참고하세요.
  • 측정항목 데이터는 Cloud Monitoring으로 수집됩니다. 측정항목 및 라벨 이름과 수집 제한에 대한 자세한 내용은 이 문서의 OTLP 측정항목 수집 섹션을 참고하세요.
  • trace 데이터는 일반적으로 OTLP와 일치하는 형식으로 저장됩니다. 자세한 내용은 OTLP trace 수집을 참고하세요.

SDK를 사용하는 애플리케이션에서 Telemetry API로 원격 분석 데이터를 전송하거나 OpenTelemetry Collector에서 내보낼 수 있습니다.

Google Kubernetes Engine을 사용하는 경우 GKE용 Managed OpenTelemetry를 Telemetry API를 사용하는 OpenTelemetry Collector를 수동으로 배포하고 구성하는 대신 사용할 수 있습니다.

프로토콜 지원

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 프로젝트로 전송하려면 다음도 수행해야 합니다.

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

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

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 리소스에 대해 변환은 target_info 측정항목을 추가합니다. 이 측정항목에는 service.name, service.instance.id, service.namespace를 제외한 모든 리소스 속성이 포함됩니다.

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 필드에 보존된 추가 메타데이터가 필요하지 않은 경우 otel 필드가 채워지지 않도록 하는 기존 매핑 옵션 gcp.use_legacy_mapping을 사용합니다.

측정항목 데이터 결제

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

trace 데이터 결제

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

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

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

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

  • 중요: 콜론 (:) 및 밑줄 (_) 이외의 특수 문자가 포함된 측정항목 이름과 라벨 키를 쿼리하려면 PromQL's 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 데이터: 적용되는 추가 할당량 또는 한도가 없습니다.

다음 단계