Bermigrasi ke eksportir OTLP

Dokumen ini menjelaskan cara mengubah konfigurasi OpenTelemetry Collector yang menggunakan eksportir yang ada — dalam hal ini, eksportir googlemanagedprometheus — untuk menggunakan eksportir otlphttp dan Telemetry (OTLP) API, telemetry.googleapis.com.

OTLP untuk metrik Prometheus hanya berfungsi saat menggunakan OpenTelemetry Collector versi 0.140.0 atau yang lebih baru.

Mengaktifkan Telemetry API

Eksportir otlphttp menulis ke Telemetry API, sehingga API tersebut harus diaktifkan di project Anda. Aktifkan Telemetry API dengan menjalankan perintah berikut:

gcloud services enable telemetry.googleapis.com

Mengotorisasi akun layanan Kubernetes

Akun layanan Kubernetes harus memiliki izin untuk menggunakan Telemetry API. Perintah berikut memberikan peran Identity and Access Management (IAM) yang diperlukan ke akun layanan Kubernetes. Perintah ini mengasumsikan bahwa Anda menggunakan Workload Identity Federation for 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

Ganti variabel PROJECT_ID dengan ID Google Cloud project Anda.

Jika akun layanan Anda memiliki format yang berbeda, Anda dapat menggunakan perintah dalam dokumentasi Google Cloud Managed Service for Prometheus untuk mengotorisasi akun layanan, dengan perubahan berikut:

  • Ganti nama akun layanan gmp-test-sa dengan akun layanan Anda.
  • Jalankan perintah untuk memberikan peran roles/telemetry.metricsWriter.

Menetapkan variabel lingkungan PROJECT_ID

Tetapkan variabel lingkungan PROJECT_ID dalam deployment pengumpul Anda. Hasilnya akan terlihat seperti berikut:

env:
- name: PROJECT_ID
  value: PROJECT_ID

Menemukan eksportir yang akan diganti

Dalam file konfigurasi, temukan eksportir dan layanan yang menggunakan eksportir:

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

Menambahkan konfigurasi untuk eksportir otlphttp

Pada langkah ini, Anda menambahkan eksportir otlphttp dan prosesor metricstarttime ke konfigurasi. Eksportir tambahan ini menyebabkan pengumpul menulis metrik dua kali.

  • Jika Anda menggunakan metrik native OTLP, penulisan dua kali tidak akan menimbulkan masalah karena struktur deskriptor metrik yang dibuat oleh kedua metode tersebut berbeda. Metrik tersebut terpisah.
  • Jika Anda menggunakan metrik Prometheus, Anda akan melihat konflik hingga Anda menghapus eksportir googlemanagedpromethus.

Konfigurasi yang diperbarui akan terlihat seperti berikut:

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]

Setelah menulis metrik dua kali, perbarui dasbor dan kebijakan pemberitahuan Anda untuk menggunakan nama metrik baru seperti yang dihasilkan oleh eksportir otlphttp. Eksportir otlphttp tidak mengganti nama metrik menjadi "gaya Prometheus", menggunakan penggantian garis bawah.

Menghapus konfigurasi untuk eksportir sebelumnya

Setelah memperbarui dasbor dan pemberitahuan Anda untuk merujuk ke metrik yang diekspor otlphttp, hapus eksportir lama, dalam hal ini googlemanagedprometheus, dari konfigurasi. Konfigurasi yang direvisi akan terlihat seperti berikut:

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]

Memigrasikan dasbor dan kebijakan pemberitahuan, jika perlu

Jika Anda hanya menggunakan eksportir googlemanagedprometheus untuk data metrik Prometheus, saat Anda beralih ke eksportir OTLP, dasbor dan kebijakan pemberitahuan yang ada akan terus berfungsi.

Namun, jika Anda menggunakan eksportir googlemanagedprometheus untuk mengumpulkan dan mengirim data yang awalnya dipancarkan menggunakan OTLP, atau jika Anda meng-scrape metrik Prometheus dengan karakter UTF-8, Anda harus memperbarui dasbor dan pemberitahuan untuk menggunakan nama metrik UTF-8.

Hal ini disebabkan oleh perbedaan berikut antara metrik yang diekspor menggunakan OTLP dan metrik yang diekspor menggunakan eksportir googlemanagedprometheus:

  • Telemetry API mengizinkan karakter titik (.) dan garis miring (/) dalam nama metrik. Eksportir googlemanagedprometheus mengonversi semua instance karakter ini menjadi karakter garis bawah (_). Misalnya, metrik OTLP yang disebut prometheus.googleapis.com/foo.bar/gauge diekspor secara verbatim oleh eksportir OTLP, tetapi diekspor sebagai prometheus.googleapis.com/foo_bar/gauge oleh eksportir googlemanagedprometheus.

    Saat metrik di-ingest, Cloud Monitoring akan membuat deskriptor metrik berdasarkan nama. Perbedaan dalam cara karakter titik (.) dan garis miring (/) ditangani oleh jalur penyerapan berarti deskriptor metrik yang dihasilkan berbeda antara metrik yang di-ingest menggunakan eksportir googlemanagedprometheus dan metrik yang di-ingest menggunakan eksportir otlphttp. Jika Anda menggunakan kedua jalur penyerapan, Anda akan memiliki dua kumpulan metrik; untuk mendapatkan hasil lengkap saat membuat kueri, Anda harus menggabungkan hasil secara manual dari metrik versi Prometheus dan OTLP.

  • Telemetry API tidak menambahkan unit ke nama metrik saat unit ada, dan tidak menambahkan akhiran _total ke penghitung. Jadi, metrik yang diekspor sebagai prometheus.googleapis.com/foo/counter saat menggunakan Telemetry API diekspor sebagai prometheus.googleapis.com/foo_seconds_total/counter oleh eksportir googlemanagedprometheus. Perbedaan ini juga berlaku untuk akhiran _total dan _ratio.

Untuk mengetahui informasi selengkapnya tentang perbedaan antara metrik, lihat Perbedaan antara eksportir googlemanagedprometheus dan Telemetry API.

Karena aturan transformasi tidak berlaku untuk metrik dengan karakter UTF-8, Anda harus menulis ulang dasbor dan kebijakan pemberitahuan untuk menggunakan nama metrik baru atau menggabungkan nama metrik lama dan baru.

Sebaiknya jangan tulis aturan prosesor untuk membuat ulang transformasi ini agar terus menulis metrik UTF-8 seolah-olah dikumpulkan oleh eksportir googlemanagedprometheus. Tindakan ini mempertahankan kompatibilitas mundur, tetapi mengorbankan kompatibilitas maju, dan Anda tidak akan dapat menggunakan aset open source yang mereferensikan nama metrik UTF-8 dengan mudah.