Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memigrasikan pengumpul untuk menggunakan pengekspor OTLP

The Telemetry (OTLP) API is an implementation of the OpenTelemetry Protocol. Dukungan untuk OTLP memungkinkan Anda menambahkan pengekspor otlphttp dan otlp_grpc/otlp_logs generik ke konfigurasi pengumpul Anda, sehingga menghindari pengekspor khusus vendor. Aplikasi dapat mengirim data log, metrik, dan rekaman aktivitas ke Telemetry API.

Panduan ini berlaku untuk Anda jika konfigurasi pengumpul Anda menggunakan googlecloud pengekspor atau googlemanagedprometheus pengekspor:

Data log: Bermigrasi dari pengekspor googlecloud ke pengekspor otlp_grpc/otlp_logs.
Data metrik: Bermigrasi dari pengekspor googlemanagedprometheus ke pengekspor otlphttp.
Data rekaman aktivitas: Bermigrasi dari pengekspor googlecloud ke pengekspor otlphttp.

Untuk bermigrasi ke pengekspor OTLP, lakukan langkah-langkah berikut:

Mengaktifkan Telemetry API
Mengotorisasi akun layanan pengumpul
Menetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT
Menambahkan ekstensi googleclientauth
Menambahkan pengekspor otlphttp dan otlp_grpc/otlp_logs
Menambahkan pemroses
Memperbarui pipeline layanan
Memvalidasi konfigurasi Anda
Memigrasikan dasbor dan kebijakan pemberitahuan
Menghapus pengekspor khusus vendor

Mengaktifkan Telemetry API

Pengekspor OTLP menulis ke Telemetry API, sehingga API tersebut harus diaktifkan di project Anda. Untuk mengaktifkan Telemetry API, jalankan perintah berikut:

gcloud services enable telemetry.googleapis.com

Mengotorisasi akun layanan pengumpul

Pengumpul melakukan autentikasi terhadap Google Cloud API menggunakan identitas lingkungan tempat pengumpul berjalan. Akun layanan yang menjalankan pengumpul Anda harus memiliki izin untuk menggunakan Telemetry API guna menulis data log, metrik, dan rekaman aktivitas. Selain itu, karena Telemetry API adalah API konsumen, Anda harus secara eksplisit menentukan Google Cloud project yang kuotanya digunakan oleh panggilan API dan memberikan izin kepada akun layanan yang diperlukan untuk menggunakan kuota project tersebut.

Peran yang diperlukan

Untuk memastikan bahwa akun layanan yang menjalankan pengumpul Anda memiliki izin yang diperlukan untuk mengirim data log, metrik, dan rekaman aktivitas, minta administrator untuk memberikan peran IAM berikut ke akun layanan yang menjalankan pengumpul Anda di project Anda:

Cloud Telemetry Writer (roles/telemetry.writer)
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Peran bawaan ini berisi izin yang diperlukan untuk mengirim data log, metrik, dan rekaman aktivitas. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengirim data log, metrik, dan rekaman aktivitas:

logging.logEntries.create
monitoring.timeSeries.create
telemetry.traces.write
serviceusage.services.use

Akun layanan Kubernetes

Jika Anda men-deploy pengumpul di Google Kubernetes Engine (GKE) menggunakan Workload Identity Federation for GKE, berikan peran yang diperlukan ke akun layanan Kubernetes Anda.

Anda dapat menggunakan perintah berikut untuk memberikan peran yang diperlukan jika kuota API Anda diambil dari Google Cloud project yang sama dengan tujuan panggilan Telemetry API. Sebelum menjalankan perintah, ganti PROJECT_ID dengan ID project Anda. Namun, jika Anda menggunakan project kuota terpisah, ganti PROJECT_ID dalam perintah kedua dengan ID project kuota Anda:

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

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

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

Akun layanan untuk Workload Identity Federation for GKE

Jika Anda mengonfigurasi akun layanan untuk Workload Identity Federation for GKE, Anda dapat menggunakan perintah dalam dokumentasi Google Cloud Managed Service for Prometheus untuk mengotorisasi akun layanan, dengan perubahan berikut:

Ganti gmp-test-sa dengan nama akun layanan Anda.
Jalankan perintah untuk memberikan peran yang diperlukan untuk menulis data log, metrik, dan rekaman aktivitas.

Akun layanan lainnya

Jika Anda menjalankan pengumpul di VM Compute Engine atau di luar GKE, berikan peran yang diperlukan ke Google Cloud akun layanan yang digunakan deployment Anda.

Menetapkan variabel lingkungan `GOOGLE_CLOUD_PROJECT`

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

env:
- name: GOOGLE_CLOUD_PROJECT
  value: PROJECT_ID

Menambahkan ekstensi `googleclientauth`

Tambahkan ekstensi googleclientauth ke konfigurasi pengumpul Anda. Telemetry API adalah API konsumen dan mengharuskan Anda menentukan project Google Cloud dan project kuota Anda. Hasilnya akan terlihat mirip dengan berikut ini:

extensions:
  googleclientauth:
    project: ${GOOGLE_CLOUD_PROJECT}
    quota_project: ${GOOGLE_CLOUD_PROJECT}

Menambahkan pengekspor `otlphttp` dan `otlp_grpc/otlp_logs`

Gunakan pengekspor otlphttp untuk mengirim data metrik dan rekaman aktivitas berformat OTLP ke project Anda, dan gunakan pengekspor otlp_grpc/otlp_logs untuk mengirim data log. Pastikan untuk mengonfigurasi kedua pengekspor dengan ekstensi googleclientauth.

Hasilnya akan terlihat mirip dengan berikut ini:

exporters:
  # ... existing content ...
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    auth:
      authenticator: googleclientauth
  otlp_grpc/otlp_logs:
    auth:
      authenticator: googleclientauth
    balancer_name: pick_first
    endpoint: telemetry.googleapis.com:443

Untuk pengekspor otlp_grpc/otlp_logs, kolom endpoint harus ditentukan menggunakan format host:port.

Menambahkan pemroses

Bagian ini mencantumkan pemroses yang perlu Anda tambahkan ke pengumpul Anda. Ada pemroses lain yang mungkin ingin Anda gunakan. Misalnya, konfigurasi pengumpul Google-Built OpenTelemetry Collector biasanya menyertakan pemroses memory_limiter dan pemroses yang mengubah data metrik. Untuk contohnya, lihat Google-Built OpenTelemetry Collector di GKE.

Menambahkan pemroses `resource/gcp_project_id`

Tambahkan pemroses resource yang mengambil informasi tentang Google Cloud project Anda.

  resource/gcp_project_id:
    attributes:
      - action: insert
        value: ${GOOGLE_CLOUD_PROJECT}
        key: gcp.project_id

Menambahkan pemroses `resourcedetection`

Jika Anda menjalankan di Google Cloud, pertimbangkan untuk menambahkan pemroses resourcedetection. Pemroses ini dapat otomatis menemukan informasi tentang arsitektur Anda.

Konfigurasi berikut mencari variabel lingkungan OpenTelemetry standar lalu membuat kueri server metadata Google Cloud untuk mengumpulkan informasi tentang infrastruktur Anda:

  resourcedetection:
    detectors: ["env", "gcp"]

Menambahkan pemroses `batch`

Untuk mengirim telemetri Anda ke project Anda dengan lebih efisien, sebaiknya gunakan pemroses Google Cloud batch.

Misalnya, pengumpul Google-Built OpenTelemetry Collector menggunakan konfigurasi berikut untuk pemroses batch:

batch:
  send_batch_max_size: 200
  send_batch_size: 200
  timeout: 5s

Menambahkan pemroses `metricstarttime`

Tambahkan pemroses metricstarttime ke konfigurasi. Pemroses ini memastikan bahwa metrik kumulatif menyertakan waktu mulai dan waktu observasi. Secara default, metrik Prometheus hanya menyertakan waktu saat ini. Oleh karena itu, jika Anda menghapus pemroses ini dan aplikasi Anda menghasilkan metrik Prometheus, data metrik Anda mungkin akan ditolak atau Anda mungkin melihat lonjakan data.

Anda harus menambahkan pemroses ini jika pengumpul Anda menerima metrik Prometheus.

processors:
  # This processor ensures the start time is set for Prometheus metrics.
  # Set in the pipeline before the k8sattributes processor, if used.
  # No-op for OTLP metrics.
  metricstarttime:
    strategy: subtract_initial_point

Menambahkan pemroses transformasi

Untuk mempertahankan sumber dan versi instrumentasi dalam data log Anda, tambahkan pemroses transform berikut:

  transform/otlp_grpc/preserve_instrumentation_source_version:
    error_mode: ignore
    log_statements:
      - context: log
        statements:
          - set(attributes["instrumentation_source"], instrumentation_scope.name) where instrumentation_scope.name != ""
          - set(attributes["instrumentation_version"], instrumentation_scope.version) where instrumentation_scope.version != ""
          - set(attributes["service.name"], resource.attributes["service.name"]) where resource.attributes["service.name"] != nil
          - set(attributes["service.namespace"], resource.attributes["service.namespace"]) where resource.attributes["service.namespace"] != nil
          - set(attributes["service.instance.id"], resource.attributes["service.instance.id"]) where resource.attributes["service.instance.id"] != nil

Memperbarui pipeline layanan

Selanjutnya, perbarui pipeline pengumpul Anda untuk menggunakan pengekspor otlp_grpc/otlp_logs dan otlphttp. Untuk data log dan rekaman aktivitas, petunjuk ini mengganti pengekspor Anda saat ini dengan pengekspor OTLP yang sesuai. Untuk data metrik Anda, petunjuk ini akan menghasilkan penulisan ganda. Pendekatan ini memungkinkan Anda memverifikasi bahwa pengekspor OTLP sedang mengirim data metrik ke Google Cloud project Anda. Pendekatan ini juga memungkinkan Anda memperbarui diagram dan kebijakan pemberitahuan sebelum Anda menonaktifkan aliran data dari pengekspor asli.

Lakukan perubahan berikut pada konfigurasi pipeline pengumpul Anda:

Tambahkan ekstensi googleclientauth ke entri service.
Untuk pipeline log Anda, ganti googlecloud/logging dengan otlp_grpc/otlp_logs, lalu tambahkan pemroses berikut ke daftar pemroses pipeline:
- resource/gcp_project_id
- transform/otlp_grpc/preserve_instrumentation_source_version
- resourcedetection (jika Anda menambahkan pemroses ini)
- batch
Konfigurasi ini melakukan penulisan data log tunggal. Jika Anda ingin menulis data log ganda, tambahkan pengekspor otlp_grpc/otlp_logs ke daftar pengekspor.
Untuk pipeline metrik Anda, tambahkan pengekspor otlphttp ke daftar pengekspor pipeline bersama dengan pengekspor googlemanagedprometheus, lalu tambahkan pemroses berikut:
- resource/gcp_project_id
- metricstarttime
- resourcedetection (jika Anda menambahkan pemroses ini)
- batch
Konfigurasi ini melakukan penulisan data metrik ganda. Setelah Anda memvalidasi aliran data metrik dan memperbarui diagram serta kebijakan pemberitahuan, hapus pengekspor Prometheus.
Untuk pipeline rekaman aktivitas Anda, ganti pengekspor Anda saat ini dengan pengekspor otlphttp, lalu tambahkan pemroses berikut:
- resource/gcp_project_id
- resourcedetection (jika Anda menambahkan pemroses ini)
- batch
Konfigurasi ini melakukan penulisan data rekaman aktivitas tunggal.

Hasil perubahan ini mirip dengan berikut ini:

service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - transform/otlp_grpc/preserve_instrumentation_source_version
        - batch
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - metricstarttime
        - batch
      exporters: ["googlemanagedprometheus", "otlphttp"]
    traces:
      receivers: ["otlp"]
      processors:
        - resourcedetection
        - resource/gcp_project_id
        - batch
      exporters: ["otlphttp"]

Cuplikan sebelumnya menggunakan penerima OTLP untuk data log, metrik, dan rekaman aktivitas Anda. Konfigurasi pengumpul Anda mungkin berbeda. Misalnya, jika Anda memiliki aplikasi yang menulis data log terstruktur, penerima filelog akan sesuai.

Memvalidasi konfigurasi Anda

Mulai ulang deployment Anda, lalu verifikasi bahwa pengekspor otlphttp dan otlp_grpc/otlp_logs Anda mengirim data ke Google Cloud project Anda. Untuk memverifikasi konfigurasi Anda, lakukan hal berikut:

Buat kueri entri log Anda untuk mengetahui error terkait penulisan data telemetri.
Lihat rasio error untuk Cloud Logging API, Cloud Monitoring API, dan Telemetry API.
Lihat deret waktu menggunakan Metrics Explorer.

Memigrasikan dasbor dan kebijakan pemberitahuan

Perbarui diagram dan dasbor Anda sebagai berikut:

Jika Anda memantau penggunaan Cloud Logging API atau Cloud Monitoring API dengan diagram atau kebijakan pemberitahuan, buat diagram atau kebijakan pemberitahuan tambahan untuk memantau penggunaan Telemetry API.
Jika penerima metrik menyertakan penerima otlp atau jika pengumpul Anda menyalin metrik Prometheus dengan karakter UTF-8, perbarui diagram dan dasbor Anda. Pengekspor otlphttp menghasilkan metrik yang berbeda dengan pengekspor googlemanagedprometheus. Untuk mengetahui informasi selengkapnya, lihat Perbedaan format metrik yang diekspor.

Anda tidak perlu memperbarui diagram dan dasbor jika pengumpul Anda hanya menerima data metrik Prometheus.
Jika pipeline metrik Anda menyertakan prometheuspenerima, akan terjadi konflik aliran data antara metrik yang dihasilkan oleh otlphttp dan googlemanagedprometheus pengekspor. Untuk mengatasi konflik ini, hapus pengekspor googlemanagedprometheus.

Perbedaan format metrik yang diekspor

Pembaruan pada diagram berbasis metrik dan kebijakan pemberitahuan diperlukan karena perbedaan berikut antara metrik yang diekspor oleh pengekspor OTLP dan googlemanagedprometheus:

Telemetry API mengizinkan karakter titik (.) dan garis miring (/) dalam nama metrik. Pengekspor 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 pengekspor OTLP, tetapi diekspor sebagai prometheus.googleapis.com/foo_bar/gauge oleh pengekspor googlemanagedprometheus.

Saat metrik dimasukkan, 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 dimasukkan menggunakan pengekspor googlemanagedprometheus dan metrik yang dimasukkan menggunakan otlphttp pengekspor. 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 pengekspor googlemanagedprometheus. Perbedaan ini juga berlaku untuk akhiran _total dan _ratio.

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

Aturan transformasi tidak berlaku untuk metrik dengan karakter UTF-8. Oleh karena itu, Anda harus menulis ulang dasbor dan kebijakan pemberitahuan untuk menggunakan nama metrik baru atau menggunakan kueri yang 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. Tindakan ini mempertahankan kompatibilitas mundur, tetapi mengorbankan kompatibilitas maju, dan Anda tidak akan dapat menggunakan aset open source yang mereferensikan nama metrik UTF-8.

Menghapus pengekspor khusus vendor

Setelah Anda memvalidasi aliran data baru dan memperbarui dasbor serta kebijakan pemberitahuan, hapus pengekspor googlecloud/logging dan googlemanagedprometheus dari konfigurasi pengumpul Anda. Anda mungkin juga perlu menghapus pemroses yang hanya digunakan oleh pengekspor yang dihapus dari konfigurasi.

Anda harus memperbarui daftar pengekspor dan pipeline layanan.

exporters:
  otlphttp: [...]
  otlp_grpc/otlp_logs: [...]

...
service:
  extensions: ["googleclientauth"]
  pipelines:
    logs:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlp_grpc/otlp_logs"]
    metrics:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]
    traces:
      receivers: ["otlp"]
      processors: [...]
      exporters: ["otlphttp"]

Pemecahan masalah

Bagian ini menjelaskan cara mengatasi kegagalan yang mungkin terjadi saat Anda memigrasikan konfigurasi pengumpul Anda.

Data metrik tidak ada atau lonjakan data metrik

Jika data metrik Anda tidak ada atau berisi lonjakan, pastikan Anda menambahkan pemroses metricstarttime ke konfigurasi pengumpul. Untuk mengetahui informasi selengkapnya, lihat Menambahkan pemroses metricstarttime.

Anda juga dapat meninjau log pengumpul, log sistem, dan log audit akses data untuk Monitoring. Misalnya, jika penulisan ke deret waktu gagal, log audit akses data yang menyertakan alasan kegagalan akan dibuat.

Pesan error tentang penulisan deret waktu

Sistem akan menghasilkan pesan error jika upaya untuk menulis data ke deret waktu gagal. Anda dapat menggunakan pesan ini untuk membantu Anda memahami alasan penulisan gagal dan cara mengatasi masalah ini.

Pesan error yang menunjukkan ketidakcocokan nilai:
```
"One or more TimeSeries could not be written: Value type DOUBLE does not match metric descriptor value type INT64."
```
Error ini terjadi jika Anda sebelumnya mengirim metrik target_info INT64 karena Telemetry API menetapkan jenis nilai semua metrik ke DOUBLE. Solusi jangka panjang terbaik adalah menghapus deskriptor metrik untuk metrik target_info INT64. Untuk menghapus deskriptor ini dari cakupan metrik Anda, gunakan skrip Golang ini.
Pesan error yang menunjukkan beberapa sumber menulis data deret waktu:
```
"One or more TimeSeries could not be written: Points must be written in order. One or more of the points specified had an older end time than the most recent point."
```
Untuk mengatasi masalah ini, hapus pengekspor googlemanagedprometheus dari konfigurasi pengumpul Anda. Untuk mengetahui informasi selengkapnya, lihat Menghapus pengekspor khusus vendor.

Langkah berikutnya

Ringkasan contoh instrumentasi berbasis pengumpul mengacu pada contoh aplikasi yang dapat Anda download dan instal. Setiap contoh aplikasi menyertakan pengumpul lengkap yang mengekspor data metrik dan rekaman aktivitas menggunakan Telemetry API.
Men-deploy Google-Built OpenTelemetry Collector di Google Kubernetes Engine menyertakan konfigurasi pengumpul lengkap.