Bermigrasi ke eksportir OTLP

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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

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

Mengaktifkan Telemetry API

Pengekspor 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

Memberi otorisasi 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 project Google Cloud Anda.

Jika akun layanan Anda memiliki format yang berbeda, Anda dapat menggunakan perintah dalam dokumentasi Google Cloud Managed Service for Prometheus untuk mengizinkan 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

Temukan pengekspor yang akan diganti

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

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

Menambahkan konfigurasi untuk eksportir otlphttp

Pada langkah ini, Anda menambahkan pengekspor otlphttp dan pemroses metricstarttime ke konfigurasi. Pengekspor tambahan ini menyebabkan pengumpul menulis metrik dua kali.

• Jika Anda menggunakan metrik native OTLP, penulisan ganda tidak menimbulkan masalah karena struktur deskriptor metrik yang dibuat oleh kedua metode berbeda. Keduanya adalah metrik terpisah.
• Jika Anda menggunakan metrik Prometheus, Anda akan melihat tabrakan 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 ganda metrik, perbarui dasbor dan kebijakan pemberitahuan untuk menggunakan nama metrik baru yang dihasilkan oleh pengekspor otlphttp. Pengekspor otlphttp tidak mengganti nama metrik menjadi "gaya Prometheus", menggunakan penggantian garis bawah.

Catatan: Karena Telemetry API menetapkan jenis nilai semua metrik ke DOUBLE, kami memperkirakan akan ada kemungkinan bentrokan jenis nilai, khususnya jika Anda sebelumnya telah mengirimkan metrik INT64 target_info. Jika Anda mengalami konflik, solusi jangka panjang terbaik untuk masalah ini adalah menghapus deskriptor metrik untuk metrik INT64 target_info. Untuk menghapus deskriptor ini dari cakupan metrik Anda, gunakan skrip Golang ini.

Menghapus konfigurasi untuk pengekspor sebelumnya

Setelah memperbarui dasbor dan pemberitahuan untuk merujuk ke metrik yang diekspor otlphttp, hapus pengekspor 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]

Migrasikan dasbor dan kebijakan pemberitahuan, jika perlu

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

Namun, jika Anda menggunakan eksportir googlemanagedprometheus untuk mengumpulkan dan mengirim data yang awalnya dikeluarkan 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. Eksporter googlemanagedprometheus mengonversi semua kemunculan 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 membuat deskriptor metrik berdasarkan nama. Perbedaan cara penanganan karakter titik (.) dan garis miring (/) oleh jalur penyerapan berarti deskriptor metrik yang dihasilkan berbeda antara metrik yang diserap menggunakan eksportir googlemanagedprometheus dan yang diserap menggunakan eksportir otlphttp. Jika menggunakan kedua jalur penyerapan, Anda akan memiliki dua set 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 jika ada unit, 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 pengekspor googlemanagedprometheus. Perbedaan ini juga berlaku untuk sufiks _total dan _ratio.

Untuk mengetahui informasi selengkapnya tentang perbedaan antara metrik, lihat Perbedaan antara pengekspor 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 menulis aturan pemroses untuk membuat ulang transformasi ini agar terus menulis metrik UTF-8 seolah-olah dikumpulkan oleh pengekspor googlemanagedprometheus. Dengan melakukannya, kompatibilitas mundur akan tetap dipertahankan, tetapi kompatibilitas maju akan dikorbankan, dan Anda tidak akan dapat dengan mudah menggunakan aset open source yang mereferensikan nama metrik UTF-8.