OTLP 내보내기 도구로 마이그레이션

이 문서에서는 기존 내보내기 도구(이 경우 googlemanagedprometheus 내보내기 도구)를 사용하는 OpenTelemetry Collector 구성을 수정하여 otlphttp 내보내기 도구와 원격 분석(OTLP) API, telemetry.googleapis.com를 사용하는 방법을 설명합니다.

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

Telemetry API 사용 설정

otlphttp 내보내기는 원격 분석 API에 쓰므로 프로젝트에서 해당 API를 사용 설정해야 합니다. 다음 명령어를 실행하여 Telemetry API를 사용 설정합니다.

gcloud services enable telemetry.googleapis.com

Kubernetes 서비스 계정 승인

Kubernetes 서비스 계정에 원격 분석 API를 사용할 권한이 있어야 합니다. 다음 명령어는 Kubernetes 서비스 계정에 필요한 Identity and Access Management (IAM) 역할을 부여합니다. 이러한 명령어는 GKE용 워크로드 아이덴티티 제휴를 사용한다고 가정합니다.

export PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
  --role=roles/telemetry.metricsWriter \
  --member=principal://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog.goog/subject/ns/opentelemetry/sa/opentelemetry-collector \
  --condition=None

PROJECT_ID 변수를 Google Cloud 프로젝트의 ID로 바꿉니다.

서비스 계정의 형식이 다른 경우 Google Cloud Managed Service for Prometheus 문서의 명령어를 사용하여 다음 변경사항과 함께 서비스 계정을 승인할 수 있습니다.

  • 서비스 계정 이름 gmp-test-sa을 서비스 계정으로 바꿉니다.
  • 명령어를 실행하여 roles/telemetry.metricsWriter 역할을 부여합니다.

PROJECT_ID 환경 변수를 설정합니다.

수집기 배포에서 PROJECT_ID 환경 변수를 설정합니다. 결과는 다음과 같이 표시됩니다.

env:
- name: PROJECT_ID
  value: PROJECT_ID

바꿀 내보내기 도구를 찾습니다.

구성 파일에서 익스포터와 익스포터를 사용하는 서비스를 찾습니다.

exporters:
  googlemanagedprometheus:
service:
  pipelines:
    metrics:
      exporters: [googlemanagedprometheus]

otlphttp 내보내기 프로그램 구성 추가

이 단계에서는 otlphttp 내보내기 도구와 metricstarttime 프로세서를 구성에 추가합니다. 이 추가 내보내기 도구로 인해 수집기가 측정항목을 두 번 작성합니다.

  • OTLP 네이티브 측정항목을 사용하는 경우 두 방법으로 생성된 측정항목 설명의 구조가 다르기 때문에 이중 쓰기로 인해 문제가 발생하지 않습니다. 별도의 측정항목입니다.
  • Prometheus 측정항목을 사용하는 경우 googlemanagedpromethus 내보내기 도구를 삭제할 때까지 충돌이 발생합니다.

업데이트된 구성은 다음과 같습니다.

exporters:
  googlemanagedprometheus:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [googlemanagedprometheus, otlphttp]

측정항목을 이중으로 작성한 후 otlphttp 내보내기 도구에서 생성된 새 측정항목 이름을 사용하도록 대시보드와 알림 정책을 업데이트합니다. otlphttp 내보내기 도구는 밑줄 대체 항목을 사용하여 측정항목의 이름을 'Prometheus 스타일'로 바꾸지 않습니다.

이전 내보내기 프로그램의 구성 삭제

otlphttp로 내보낸 측정항목을 참조하도록 대시보드와 알림을 업데이트한 후 구성에서 이전 내보내기 프로그램(이 경우 googlemanagedprometheus)을 삭제합니다. 수정된 구성은 다음과 같습니다.

exporters:
  otlphttp:
    encoding: json
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
processors:
  # This processor ensures the start time is set for Prometheus metrics. This must be set in the pipeline before the k8sattributes processor, if used.
  metricstarttime:
    strategy: subtract_initial_point
  resource/gcp_project_id:
    attributes:
    - action: insert
      # Make sure you set the PROJECT_ID environment variable.
      value: ${PROJECT_ID}
      key: gcp.project_id
extensions:
  googleclientauth:
service:
  extensions: [googleclientauth]
  pipelines:
    metrics:
      processors: [resource/gcp_project_id, metricstarttime]
      exporters: [otlphttp]

필요한 경우 대시보드 및 알림 정책 마이그레이션

Prometheus 측정항목 데이터에만 googlemanagedprometheus 내보내기 도구를 사용한 경우 OTLP 내보내기 도구로 전환해도 기존 대시보드와 알림 정책이 계속 작동합니다.

하지만 googlemanagedprometheus 내보내기를 사용하여 원래 OTLP를 사용하여 내보낸 데이터를 수집하고 전송한 경우 또는 UTF-8 문자로 Prometheus 측정항목을 스크랩한 경우에는 UTF-8 측정항목 이름을 사용하도록 대시보드와 알림을 업데이트해야 합니다.

이는 OTLP를 사용하여 내보낸 측정항목과 googlemanagedprometheus 내보내기 도구를 사용하여 내보낸 측정항목 간의 다음과 같은 차이점 때문입니다.

  • 원격 분석 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 접미사에도 적용됩니다.

측정항목 간 차이점에 대한 자세한 내용은 googlemanagedprometheus 내보내기와 원격 분석 API의 차이점을 참고하세요.

변환 규칙은 UTF-8 문자가 포함된 측정항목에는 적용되지 않으므로 새 측정항목 이름을 사용하거나 이전 측정항목 이름과 새 측정항목 이름을 통합하도록 대시보드와 알림 정책을 다시 작성해야 합니다.

googlemanagedprometheus 내보내기 도구에서 수집한 것처럼 UTF-8 측정항목을 계속 작성하기 위해 이러한 변환을 다시 만드는 프로세서 규칙을 작성하지 않는 것이 좋습니다. 이렇게 하면 이전 버전과의 호환성이 유지되지만 이후 버전과의 호환성이 저하되며 UTF-8 측정항목 이름을 참조하는 오픈소스 애셋을 쉽게 사용할 수 없습니다.