Mulai menggunakan OpenTelemetry Collector

Dokumen ini menjelaskan cara menyiapkan OpenTelemetry Collector untuk menyalin metrik Prometheus standar dan melaporkan metrik tersebut ke Google Cloud Managed Service for Prometheus. OpenTelemetry Collector adalah agen yang dapat Anda deploy dan konfigurasi untuk diekspor ke Google Cloud Managed Service for Prometheus. Penyiapannya mirip dengan menjalankan Managed Service for Prometheus dengan koleksi yang di-deploy sendiri.

Anda dapat lebih memilih OpenTelemetry Collector daripada koleksi yang di-deploy sendiri karena alasan berikut:

Dengan OpenTelemetry Collector, Anda dapat merutekan data telemetri ke beberapa backend dengan mengonfigurasi berbagai pengekspor di pipeline Anda.
Kolektor juga mendukung sinyal dari metrik, log, dan trace, sehingga dengan menggunakannya, Anda dapat menangani ketiga jenis sinyal dalam satu agen.
Format data agnostik vendor OpenTelemetry (OpenTelemetry Protocol, atau OTLP) mendukung ekosistem library yang kuat dan komponen Collector yang dapat dicocokkan. Hal ini memungkinkan berbagai opsi kemampuan penyesuaian untuk menerima, memproses, dan mengekspor data Anda.

Kompromi dari manfaat ini adalah bahwa menjalankan OpenTelemetry Collector memerlukan pendekatan deployment dan pemeliharaan yang dikelola sendiri. Pendekatan yang Anda pilih akan bergantung pada kebutuhan spesifik Anda, tetapi dalam dokumen ini, kami menawarkan panduan yang direkomendasikan untuk mengonfigurasi OpenTelemetry Collector menggunakan Google Cloud Managed Service for Prometheus sebagai backend.

Sebelum memulai

Bagian ini menjelaskan konfigurasi yang diperlukan untuk tugas-tugas yang dijelaskan dalam dokumen ini.

Menyiapkan project dan alat

Untuk menggunakan Google Cloud Managed Service for Prometheus, Anda memerlukan referensi berikut:

Project Google Cloud dengan Cloud Monitoring API diaktifkan.
- Jika Anda tidak memiliki project Google Cloud, lakukan hal berikut:
  1. Di konsol Google Cloud, buka New Project:
    
    Membuat Project Baru
  2. Di kolom Project Name, masukkan nama untuk project Anda, lalu klik Create.
  3. Buka Penagihan:
    
    Buka Penagihan
  4. Pilih project yang baru saja Anda buat jika belum dipilih di bagian atas halaman.
  5. Anda akan diminta untuk memilih profil pembayaran yang sudah ada atau membuat yang baru.
  Monitoring API diaktifkan secara default untuk project baru.
- Jika Anda sudah memiliki project Google Cloud, pastikan Monitoring API diaktifkan:
  1. Buka APIs & services:
    
    Buka APIs & services
  2. Pilih project Anda.
  3. Klik Aktifkan API dan Layanan.
  4. Telusuri "Monitoring".
  5. Di hasil penelusuran, klik "Cloud Monitoring API".
  6. Jika "API enabled" tidak ditampilkan, klik tombol Enable.
Cluster Kubernetes. Jika Anda tidak memiliki cluster Kubernetes, ikuti petunjuk dalam Panduan Memulai untuk GKE.

Anda juga memerlukan alat command line berikut:

gcloud
kubectl

Alat gcloud dan kubectl adalah bagian dari Google Cloud CLI. Untuk mengetahui informasi tentang cara menginstalnya, lihat Mengelola komponen Google Cloud CLI. Untuk melihat komponen gcloud CLI yang telah Anda instal, jalankan perintah berikut:

gcloud components list

Mengonfigurasi lingkungan Anda

Agar tidak berulang kali memasukkan project ID atau nama cluster Anda, lakukan konfigurasi berikut:

Konfigurasikan alat command line sebagai berikut:
- Konfigurasikan gcloud CLI untuk merujuk ke ID project Google Cloud Anda:
```
gcloud config set project PROJECT_ID
```
- Konfigurasikan kubectl CLI untuk menggunakan cluster Anda:
```
kubectl config set-cluster CLUSTER_NAME
```
Untuk mengetahui informasi selengkapnya tentang alat ini, lihat referensi berikut:
- Ringkasan gcloud CLI
- Perintah kubectl

Menyiapkan namespace

Buat namespace Kubernetes NAMESPACE_NAME untuk resource yang Anda buat sebagai bagian dari aplikasi contoh:

kubectl create ns NAMESPACE_NAME

Memverifikasi kredensial akun layanan

Anda dapat melewati bagian ini jika cluster Kubernetes Anda telah mengaktifkan Workload Identity.

Saat berjalan di GKE, Google Cloud Managed Service for Prometheus akan otomatis mengambil kredensial dari lingkungan berdasarkan akun layanan default Compute Engine. Akun layanan default memiliki izin yang diperlukan, monitoring.metricWriter dan monitoring.viewer, secara default. Jika tidak menggunakan Workload Identity, dan sebelumnya telah menghapus salah satu peran tersebut dari akun layanan node default, Anda harus menambahkan kembali izin yang tidak ada tersebut sebelum melanjutkan.

Jika Anda tidak menjalankan aplikasi di GKE, lihat Memberikan kredensial secara eksplisit.

Mengonfigurasi akun layanan untuk Workload Identity

Anda dapat melewati bagian ini jika cluster Kubernetes Anda tidak mengaktifkan Workload Identity.

Google Cloud Managed Service for Prometheus merekam data metrik menggunakan Cloud Monitoring API. Jika cluster menggunakan Workload Identity, Anda harus memberikan izin ke akun layanan Kubernetes ke Monitoring API. Bagian ini menjelaskan hal berikut:

Membuat akun layanan Google Cloud khusus, gmp-test-sa.
Mengikat akun layanan Google Cloud ke akun layanan Kubernetes default dalam namespace pengujian, NAMESPACE_NAME.
Memberikan izin yang diperlukan ke akun layanan Google Cloud.

Membuat dan mengikat akun layanan

Langkah ini muncul di beberapa tempat dalam dokumentasi Managed Service for Prometheus. Jika sudah melakukan langkah ini sebagai bagian dari tugas sebelumnya, Anda tidak perlu mengulanginya. Lanjutkan ke bagian Mengizinkan akun layanan.

Urutan perintah berikut membuat akun layanan gmp-test-sa dan mengikatnya ke akun layanan Kubernetes default di namespace NAMESPACE_NAME:

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create gmp-test-sa \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Jika Anda menggunakan namespace atau akun layanan GKE yang berbeda, sesuaikan perintah dengan tepat.

Mengizinkan akun layanan

Grup izin terkait dikumpulkan ke dalam peran, dan Anda memberikan peran kepada akun utama, dalam contoh ini, akun layanan Google Cloud. Untuk mengetahui informasi selengkapnya tentang peran Monitoring, lihat Kontrol akses.

Perintah berikut memberikan akun layanan Google Cloud, gmp-test-sa, peran Monitoring API yang diperlukan untuk menulis data metrik.

Jika sudah memberikan peran tertentu kepada akun layanan Google Cloud sebagai bagian dari tugas sebelumnya, Anda tidak perlu melakukannya lagi.

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

Men-debug konfigurasi Workload Identity Anda

Jika Anda mengalami masalah dalam membuat Workload Identity berfungsi, lihat dokumentasi untuk memverifikasi penyiapan Workload Identity Anda dan panduan pemecahan masalah Workload Identity.

Karena salah ketik dan salin-tempel sebagian adalah sumber error yang paling umum saat mengonfigurasi Workload Identity, kami sangat merekomendasikan penggunaan variabel yang dapat diedit dan ikon salin-tempel yang dapat diklik dan disematkan dalam contoh kode dalam petunjuk ini.

Workload Identity di lingkungan produksi

Contoh yang dijelaskan dalam dokumen ini mengikat akun layanan Google Cloud ke akun layanan Kubernetes default dan memberi akun layanan Google Cloud semua izin yang diperlukan untuk menggunakan Monitoring API.

Dalam lingkungan produksi, Anda mungkin ingin menggunakan pendekatan yang lebih terperinci, dengan akun layanan untuk setiap komponen, masing-masing dengan izin minimal. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi akun layanan untuk pengelolaan workload-identitas, lihat Menggunakan Workload Identity.

Menyiapkan OpenTelemetry Collector

Bagian ini akan memandu Anda dalam menyiapkan dan menggunakan kolektor OpenTelemetry untuk menyalin metrik dari aplikasi contoh dan mengirim data ke Google Cloud Managed Service for Prometheus. Untuk mengetahui informasi konfigurasi mendetail, lihat bagian berikut:

Menghapus metrik Prometheus
Menambahkan pemroses
Mengonfigurasi pengekspor googlemanagedprometheus

OpenTelemetry Collector setara dengan biner agen Managed Service for Prometheus. Komunitas OpenTelemetry secara rutin memublikasikan rilis termasuk kode sumber, biner, dan image container.

Anda dapat men-deploy artefak ini di VM atau cluster Kubernetes menggunakan default praktik terbaik, atau menggunakan builder kolektor untuk membangun kolektor sendiri yang hanya terdiri dari komponen yang Anda butuhkan. Untuk mem-build kolektor yang akan digunakan dengan Managed Service for Prometheus, Anda memerlukan komponen berikut:

Pengekspor Layanan Terkelola untuk Prometheus, yang menulis metrik Anda ke Google Cloud Managed Service for Prometheus.
Penerima untuk menyalin metrik Anda. Dokumen ini mengasumsikan bahwa Anda menggunakan penerima OpenTelemetry Prometheus, tetapi pengekspor Managed Service for Prometheus kompatibel dengan semua penerima metrik OpenTelemetry.
Pemroses mengelompokkan dan menandai metrik Anda untuk menyertakan ID resource penting, bergantung pada lingkungan Anda.

Komponen ini diaktifkan menggunakan file konfigurasi yang diteruskan ke Kolektor dengan tanda --config.

Bagian berikut membahas cara mengonfigurasi setiap komponen ini secara lebih mendetail. Dokumen ini menjelaskan cara menjalankan kolektor di GKE dan tempat lain.

Mengonfigurasi dan men-deploy Kolektor

Baik menjalankan koleksi di Google Cloud maupun di lingkungan lain, Anda masih dapat mengonfigurasi OpenTelemetry Collector untuk diekspor ke Google Cloud Managed Service for Prometheus. Perbedaan terbesarnya terletak pada cara Anda mengonfigurasi Kolektor. Dalam lingkungan non-Google Cloud, mungkin ada pemformatan tambahan data metrik yang diperlukan agar kompatibel dengan Managed Service for Prometheus. Namun, di Google Cloud, sebagian besar pemformatan ini dapat dideteksi secara otomatis oleh Kolektor.

Menjalankan OpenTelemetry Collector di GKE

Anda dapat menyalin konfigurasi berikut ke dalam file bernama config.yaml untuk menyiapkan OpenTelemetry Collector di GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

# Note that the googlemanagedprometheus exporter block is intentionally blank
exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resourcedetection, transform]
      exporters: [googlemanagedprometheus]

Konfigurasi sebelumnya menggunakan penerima Prometheus dan pengekspor Layanan Terkelola untuk Prometheus untuk menyalin endpoint metrik di Pod Kubernetes dan mengekspor metrik tersebut ke Google Cloud Managed Service for Prometheus. Memformat prosesor pipeline dan mengelompokkan data.

Untuk detail selengkapnya tentang fungsi setiap bagian konfigurasi ini, beserta konfigurasi untuk berbagai platform, lihat bagian detail di bawah ini tentang menggabungkan metrik dan menambahkan prosesor.

Saat menjalankan cluster dengan konfigurasi Prometheus yang ada, ganti setiap karakter $ dengan $$ agar tidak memicu penggantian variabel lingkungan. Untuk informasi selengkapnya, lihat Metrik Prometheus Scrape.

Anda dapat mengubah konfigurasi ini berdasarkan lingkungan, penyedia, dan metrik yang ingin Anda salin, tetapi contoh konfigurasi ini adalah titik awal yang direkomendasikan untuk menjalankan aplikasi di GKE.

Menjalankan OpenTelemetry Collector di luar Google Cloud

Menjalankan OpenTelemetry Collector di luar Google Cloud, seperti pada infrastruktur lokal atau di penyedia cloud lainnya, mirip dengan menjalankan Collector di GKE. Namun, metrik yang Anda salin cenderung tidak otomatis menyertakan data dalam format yang paling baik untuk Google Cloud Managed Service for Prometheus. Oleh karena itu, Anda harus lebih berhati-hati dalam mengonfigurasi kolektor untuk memformat metrik agar kompatibel dengan Managed Service for Prometheus.

Anda dapat melakukan konfigurasi berikut ke dalam file bernama config.yaml guna menyiapkan OpenTelemetry Collector untuk deployment di cluster Kubernetes non-GKE:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'SCRAPE_JOB_NAME'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name]
          action: keep
          regex: prom-example
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "CLUSTER_NAME"
      action: upsert
    - key: "namespace"
      value: "NAMESPACE_NAME"
      action: upsert
    - key: "location"
      value: "REGION"
      action: upsert

  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

exporters:
  googlemanagedprometheus:
    project: "PROJECT_ID"

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch, memory_limiter, resource, transform]
      exporters: [googlemanagedprometheus]

Konfigurasi ini melakukan hal berikut:

Menyiapkan konfigurasi scrape penemuan layanan Kubernetes untuk Prometheus. Untuk informasi selengkapnya, lihat mengikis metrik Prometheus.
Menetapkan atribut resource cluster, namespace, dan location secara manual. Untuk mengetahui informasi selengkapnya tentang atribut resource, termasuk deteksi resource untuk Amazon EKS dan Azure AKS, lihat Mendeteksi atribut resource.
Menetapkan opsi project di pengekspor googlemanagedprometheus. Untuk mengetahui informasi selengkapnya tentang pengekspor, lihat Mengonfigurasi pengekspor googlemanagedprometheus.

Untuk mengetahui informasi tentang praktik terbaik dalam mengonfigurasi kolektor di cloud lainnya, lihat Amazon EKS atau Azure AKS.

Men-deploy aplikasi contoh

Aplikasi contoh memunculkan metrik penghitung example_requests_total dan metrik histogram example_random_numbers (antara lain) pada port metrics-nya. Manifes untuk contoh ini mendefinisikan tiga replika.

Untuk men-deploy aplikasi contoh, jalankan perintah berikut:

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.8.2/examples/example-app.yaml

Membuat konfigurasi kolektor sebagai ConfigMap

Setelah Anda membuat konfigurasi dan menempatkannya di file bernama config.yaml, gunakan file tersebut untuk membuat ConfigMap Kubernetes berdasarkan file config.yaml Anda. Saat kolektor di-deploy, kolektor akan memasang ConfigMap dan memuat file.

Untuk membuat ConfigMap bernama otel-config dengan konfigurasi Anda, gunakan perintah berikut:

kubectl -n NAMESPACE_NAME create configmap otel-config --from-file config.yaml

Men-deploy kolektor

Buat file bernama collector-deployment.yaml dengan konten berikut:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: NAMESPACE_NAME:prometheus-test
rules:
- apiGroups: [""]
  resources:
  - pods
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: NAMESPACE_NAME:prometheus-test
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: NAMESPACE_NAME:prometheus-test
subjects:
- kind: ServiceAccount
  namespace: NAMESPACE_NAME
  name: default
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: otel-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: otel-collector
  template:
    metadata:
      labels:
        app: otel-collector
    spec:
      containers:
      - name: otel-collector
        image: otel/opentelemetry-collector-contrib:0.92.0
        args:
        - --config
        - /etc/otel/config.yaml
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

Buat deployment Collector di cluster Kubernetes dengan menjalankan perintah berikut:

kubectl -n NAMESPACE_NAME create -f collector-deployment.yaml

Setelah pod dimulai, pod akan menyalin aplikasi contoh dan melaporkan metrik ke Managed Service for Prometheus.

Untuk mengetahui informasi tentang cara membuat kueri data Anda, lihat Membuat kueri menggunakan Cloud Monitoring atau Membuat kueri menggunakan Grafana.

Memberikan kredensial secara eksplisit

Saat berjalan di GKE, OpenTelemetry Collector akan otomatis mengambil kredensial dari lingkungan berdasarkan akun layanan node. Dalam cluster Kubernetes non-GKE, kredensial harus diberikan secara eksplisit ke OpenTelemetry Collector menggunakan flag atau variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

Tetapkan konteks ke project target Anda:
```
gcloud config set project PROJECT_ID
```
Buat akun layanan:
```
gcloud iam service-accounts create gmp-test-sa
```
Langkah ini akan membuat akun layanan yang mungkin telah Anda buat di petunjuk Workload Identity.

Berikan izin yang diperlukan ke akun layanan tersebut:

gcloud projects add-iam-policy-binding PROJECT_ID\
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/monitoring.metricWriter

Buat dan download kunci untuk akun layanan:

gcloud iam service-accounts keys create gmp-test-sa-key.json \
  --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com

Tambahkan file kunci sebagai rahasia ke cluster non-GKE Anda:

kubectl -n NAMESPACE_NAME create secret generic gmp-test-sa \
  --from-file=key.json=gmp-test-sa-key.json

Buka resource OpenTelemetry Deployment untuk mengedit:

kubectl -n NAMESPACE_NAME edit deployment otel-collector

Tambahkan teks yang ditampilkan dalam huruf tebal ke referensi:

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: NAMESPACE_NAME
  name: otel-collector
spec:
  template
    spec:
      containers:
      - name: otel-collector
        env:
        - name: "GOOGLE_APPLICATION_CREDENTIALS"
          value: "/gmp/key.json"
...
        volumeMounts:
        - name: gmp-sa
          mountPath: /gmp
          readOnly: true
...
      volumes:
      - name: gmp-sa
        secret:
          secretName: gmp-test-sa
...

Simpan file dan tutup editor. Setelah perubahan diterapkan, pod dibuat ulang dan mulai mengautentikasi ke backend metrik dengan akun layanan yang diberikan.

Hapus metrik Prometheus

Bagian ini dan bagian berikutnya memberikan informasi penyesuaian tambahan untuk menggunakan OpenTelemetry Collector. Informasi ini mungkin berguna dalam situasi tertentu, tetapi tidak diperlukan untuk menjalankan contoh yang dijelaskan dalam Menyiapkan Kolektor OpenTelemetry.

Jika aplikasi Anda sudah mengekspos endpoint Prometheus, OpenTelemetry Collector dapat menyalin endpoint tersebut menggunakan format konfigurasi scrape yang sama yang akan Anda gunakan dengan konfigurasi Prometheus standar. Untuk melakukannya, aktifkan penerima Prometheus di konfigurasi kolektor Anda.

Konfigurasi penerima Prometheus sederhana untuk pod Kubernetes mungkin terlihat seperti berikut:

receivers:
  prometheus:
    config:
      scrape_configs:
      - job_name: 'kubernetes-pods'
        kubernetes_sd_configs:
        - role: pod
        relabel_configs:
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
          action: keep
          regex: true
        - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
          action: replace
          target_label: __metrics_path__
          regex: (.+)
        - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
          action: replace
          regex: (.+):(?:\d+);(\d+)
          replacement: $1:$2
          target_label: __address__
        - action: labelmap
          regex: __meta_kubernetes_pod_label_(.+)

service:
  pipelines:
    metrics:
      receivers: [prometheus]

Ini adalah konfigurasi scrape berbasis penemuan layanan sederhana yang dapat diubah sesuai kebutuhan untuk menyalin aplikasi Anda.

Saat menjalankan cluster dengan konfigurasi Prometheus yang ada, ganti setiap karakter $ dengan $$ agar tidak memicu penggantian variabel lingkungan. Hal ini sangat penting untuk dilakukan untuk nilai replacement dalam bagian relabel_configs Anda. Misalnya, jika Anda memiliki bagian relabel_config berikut:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $1:$2
  target_label: __address__

Kemudian tulis ulang menjadi:

- source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
  action: replace
  regex: (.+):(?:\d+);(\d+)
  replacement: $$1:$$2
  target_label: __address__

Untuk mengetahui informasi selengkapnya, lihat dokumentasi OpenTelemetry.

Selanjutnya, sebaiknya Anda menggunakan pemroses untuk memformat metrik. Dalam banyak kasus, pemroses harus digunakan untuk memformat metrik dengan benar.

Menambahkan prosesor

Prosesor OpenTelemetry mengubah data telemetri sebelum diekspor. Anda dapat menggunakan pemroses di bawah ini untuk memastikan bahwa metrik Anda ditulis dalam format yang kompatibel dengan Google Cloud Managed Service for Prometheus.

Mendeteksi atribut resource

Pengekspor Managed Service for Prometheus untuk OpenTelemetry menggunakan resource yang dipantau prometheus_target untuk mengidentifikasi titik data deret waktu secara unik. Pengekspor akan mengurai kolom resource yang dimonitor dan diperlukan dari atribut resource pada titik data metrik. Kolom dan atribut tempat nilai disalin adalah:

project_id: terdeteksi otomatis oleh Kredensial Default Aplikasi, gcp.project.id, atau project dalam konfigurasi pengekspor (lihat mengonfigurasi pengekspor)
lokasi: location, cloud.availability_zone, cloud.region
cluster: cluster, k8s.cluster_name
namespace: namespace, k8s.namespace_name
tugas: service.name + service.namespace
instance: service.instance.id

Tidak menetapkan label ini ke nilai unik dapat menyebabkan error "seri waktu duplikat" saat mengekspor ke Google Cloud Managed Service for Prometheus.

Penerima Prometheus secara otomatis menetapkan atribut service.name berdasarkan job_name dalam konfigurasi scrape, dan atribut service.instance.id berdasarkan instance target scrape. Penerima juga menetapkan k8s.namespace.name saat menggunakan role: pod dalam konfigurasi scrape.

Sebaiknya isi atribut lainnya secara otomatis menggunakan pemroses deteksi resource. Namun, bergantung pada lingkungan Anda, beberapa atribut mungkin tidak terdeteksi secara otomatis. Dalam hal ini, Anda dapat menggunakan pemroses lain untuk menyisipkan nilai ini secara manual atau mengurainya dari label metrik. Bagian berikut menggambarkan konfigurasi untuk melakukan pemrosesan ini di berbagai platform

GKE

Saat menjalankan OpenTelemetry di GKE, Anda hanya perlu mengaktifkan pemroses deteksi resource untuk mengisi label resource. Pastikan metrik Anda belum berisi label resource yang dicadangkan. Jika hal ini tidak dapat dihindari, lihat Menghindari konflik atribut resource dengan mengganti nama atribut.

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

Bagian ini dapat disalin langsung ke file konfigurasi Anda, yang menggantikan bagian processors jika sudah ada.

Amazon EKS

Detektor resource EKS tidak otomatis mengisi atribut cluster atau namespace. Anda dapat menyediakan nilai ini secara manual menggunakan pemroses resource, seperti yang ditunjukkan dalam contoh berikut:

processors:
  resourcedetection:
    detectors: [eks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

Anda juga dapat mengonversi nilai ini dari label metrik menggunakan pemroses groupbyattrs (lihat memindahkan label metrik ke label resource di bawah).

Azure AKS

Detektor resource AKS tidak otomatis mengisi atribut cluster atau namespace. Anda dapat menyediakan nilai ini secara manual menggunakan pemroses resource, seperti yang ditunjukkan dalam contoh berikut:

processors:
  resourcedetection:
    detectors: [aks]
    timeout: 10s

  resource:
    attributes:
    - key: "cluster"
      value: "my-eks-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert

Anda juga dapat mengonversi nilai ini dari label metrik dengan menggunakan pemroses groupbyattrs. Baca artikel Memindahkan label metrik ke label resource.

Lingkungan lokal dan non-cloud

Dengan lingkungan lokal atau non-cloud, Anda mungkin tidak dapat mendeteksi atribut resource yang diperlukan secara otomatis. Dalam hal ini, Anda dapat memunculkan label ini dalam metrik dan memindahkannya ke atribut resource (lihat Memindahkan label metrik ke label resource), atau menetapkan semua atribut resource secara manual seperti yang ditunjukkan pada contoh berikut:

processors:
  resource:
    attributes:
    - key: "cluster"
      value: "my-on-prem-cluster"
      action: upsert
    - key: "namespace"
      value: "my-app"
      action: upsert
    - key: "location"
      value: "us-east-1"
      action: upsert

Bagian Membuat konfigurasi kolektor sebagai ConfigMap menjelaskan cara menggunakan konfigurasi. Bagian ini mengasumsikan bahwa Anda telah menempatkan konfigurasi dalam file bernama config.yaml.

Atribut resource project_id masih dapat ditetapkan secara otomatis saat menjalankan Kolektor dengan Kredensial Default Aplikasi. Jika Kolektor Anda tidak memiliki akses ke Kredensial Default Aplikasi, lihat Menyetel project_id.

Atau, Anda dapat secara manual menetapkan atribut resource yang diperlukan pada variabel lingkungan, OTEL_RESOURCE_ATTRIBUTES, dengan daftar key-value pair yang dipisahkan koma, misalnya:

export OTEL_RESOURCE_ATTRIBUTES="cluster=my-cluster,namespace=my-app,location=us-east-1"

Selanjutnya, gunakan pemroses detektor resource env untuk menetapkan atribut resource:

processors:
  resourcedetection:
    detectors: [env]

Menghindari konflik atribut resource dengan mengganti nama atribut

Jika metrik Anda sudah berisi label yang bertabrakan dengan atribut resource yang diperlukan (seperti location, cluster, atau namespace), ganti nama label untuk menghindari konflik. Konvensi Prometheus adalah menambahkan awalan exported_ ke nama label. Untuk menambahkan awalan ini, gunakan pemroses transformasi.

Konfigurasi processors berikut akan mengganti nama setiap potensi konflik dan menyelesaikan setiap kunci yang mengalami konflik dari metrik:

processors:
  transform:
    # "location", "cluster", "namespace", "job", "instance", and "project_id" are reserved, and
    # metrics containing these labels will be rejected.  Prefix them with exported_ to prevent this.
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

Memindahkan label metrik ke label resource

Dalam beberapa kasus, metrik Anda mungkin sengaja melaporkan label seperti namespace karena pengekspor Anda memantau beberapa namespace. Misalnya, saat menjalankan pengekspor kube-state-metrics.

Dalam skenario ini, label ini dapat dipindahkan ke atribut resource menggunakan pemroses groupbyattrs:

processors:
  groupbyattrs:
    keys:
    - namespace
    - cluster
    - location

Pada contoh di atas, dengan metrik dengan label namespace, cluster, dan/atau location, label tersebut akan dikonversi menjadi atribut resource yang cocok.

Membatasi permintaan API dan penggunaan memori

Dua prosesor lainnya, pemroses batch dan pemroses pembatas memori memungkinkan Anda membatasi konsumsi resource kolektor Anda.

Batch processing

Pengelompokan permintaan memungkinkan Anda menentukan jumlah titik data yang akan dikirim dalam satu permintaan. Perhatikan bahwa Cloud Monitoring memiliki batas 200 deret waktu per permintaan. Aktifkan batch pemroses menggunakan setelan berikut:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

Pembatasan memori

Sebaiknya aktifkan prosesor pembatas memori untuk mencegah kolektor error pada saat throughput tinggi. Aktifkan pemrosesan menggunakan setelan berikut:

processors:
  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

Mengonfigurasi pengekspor `googlemanagedprometheus`

Secara default, penggunaan pengekspor googlemanagedprometheus di GKE tidak memerlukan konfigurasi tambahan. Untuk banyak kasus penggunaan, Anda hanya perlu mengaktifkannya dengan blok kosong di bagian exporters:

exporters:
  googlemanagedprometheus:

Namun, pengekspor menyediakan beberapa setelan konfigurasi opsional. Bagian berikut ini menjelaskan setelan konfigurasi lainnya.

Setelan `project_id`

Untuk mengaitkan deret waktu Anda dengan project Google Cloud, resource yang dipantau prometheus_target harus memiliki project_id yang ditetapkan.

Saat menjalankan OpenTelemetry di Google Cloud, pengekspor Google Cloud Managed Service for Prometheus secara default akan menetapkan nilai ini berdasarkan Kredensial Default Aplikasi yang ditemukannya. Jika tidak ada kredensial yang tersedia, atau Anda ingin mengganti project default, ada dua opsi:

Tetapkan project di konfigurasi pengekspor
Tambahkan atribut resource gcp.project.id ke metrik Anda.

Sebaiknya gunakan nilai default (tidak ditetapkan) untuk project_id, bukan menetapkannya secara eksplisit, jika memungkinkan.

Tetapkan `project` di konfigurasi pengekspor

Cuplikan konfigurasi berikut mengirimkan metrik ke Managed Service for Prometheus di project Google Cloud MY_PROJECT:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    project: MY_PROJECT

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

Satu-satunya perubahan dari contoh sebelumnya adalah baris baru project: MY_PROJECT. Setelan ini berguna jika Anda mengetahui bahwa setiap metrik yang masuk melalui Kolektor ini harus dikirim ke MY_PROJECT.

Setel atribut resource `gcp.project.id`

Anda dapat menetapkan pengaitan project per metrik dengan menambahkan atribut resource gcp.project.id ke metrik. Tetapkan nilai atribut ke nama project yang harus dikaitkan dengan metrik.

Misalnya, jika metrik Anda sudah memiliki label project, label ini dapat dipindahkan ke atribut resource dan diganti namanya menjadi gcp.project.id menggunakan pemroses dalam konfigurasi Kolektor, seperti yang ditunjukkan dalam contoh berikut:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  groupbyattrs:
    keys:
    - project

  resource:
    attributes:
    - key: "gcp.project.id"
      from_attribute: "project"
      action: upsert

exporters:
  googlemanagedprometheus:

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection, groupbyattrs, resource]
      exporters: [googlemanagedprometheus]

Menyetel opsi klien

Pengekspor googlemanagedprometheus menggunakan klien gRPC untuk Google Cloud Managed Service for Prometheus. Oleh karena itu, setelan opsional tersedia untuk mengonfigurasi klien gRPC:

compression: Mengaktifkan kompresi gzip untuk permintaan gRPC, yang berguna untuk meminimalkan biaya transfer data saat mengirim data dari cloud lain ke Google Cloud Managed Service for Prometheus (nilai yang valid: gzip).
user_agent: Mengganti string agen pengguna yang dikirim pada permintaan ke Cloud Monitoring; hanya berlaku untuk metrik. Setelan defaultnya adalah nomor build dan versi OpenTelemetry Collector, misalnya, opentelemetry-collector-contrib 0.92.0.
endpoint: Menetapkan endpoint tempat data metrik akan dikirim.
use_insecure: Jika true (benar), menggunakan gRPC sebagai transport komunikasi. Memiliki efek hanya jika nilai endpoint bukan "".
grpc_pool_size: Menetapkan ukuran kumpulan koneksi di klien gRPC.
prefix: Mengonfigurasi awalan metrik yang dikirim ke Google Cloud Managed Service for Prometheus. Default-nya adalah prometheus.googleapis.com. Jangan mengubah awalan ini; jika dilakukan, metrik tidak akan dapat dikueri dengan PromQL di UI Cloud Monitoring.

Pada umumnya, Anda tidak perlu mengubah nilai ini dari defaultnya. Namun, Anda dapat mengubahnya untuk mengakomodasi keadaan khusus.

Semua setelan ini ditetapkan dalam blok metric di bagian pengekspor googlemanagedprometheus, seperti yang ditunjukkan dalam contoh berikut:

receivers:
  prometheus:
    config:
    ...

processors:
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

exporters:
  googlemanagedprometheus:
    metric:
      compression: gzip
      user_agent: opentelemetry-collector-contrib 0.92.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [resourcedetection]
      exporters: [googlemanagedprometheus]

Langkah selanjutnya

Menggunakan PromQL di Cloud Monitoring untuk membuat kueri metrik Prometheus.
Gunakan Grafana untuk membuat kueri metrik Prometheus.
Siapkan OpenTelemetry Collector sebagai agen bantuan di Cloud Run.
Halaman Metrics Management Cloud Monitoring menyediakan informasi yang dapat membantu Anda mengontrol jumlah biaya yang dikeluarkan untuk metrik yang dapat dikenakan biaya tanpa memengaruhi kemampuan observasi. Halaman Pengelolaan Metrik melaporkan informasi berikut:
- Volume penyerapan untuk penagihan berbasis byte dan sampel, di seluruh domain metrik dan untuk masing-masing metrik.
- Data tentang label dan kardinalitas metrik.
- Penggunaan metrik dalam kebijakan pemberitahuan dan dasbor kustom.
- Rasio error penulisan metrik.
Untuk informasi selengkapnya tentang halaman Metrics Management, lihat Melihat dan mengelola penggunaan metrik.