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 sendiri dan konfigurasikan untuk diekspor ke Managed Service for Prometheus. Penyiapannya mirip dengan menjalankan Google Cloud Managed Service for Prometheus dengan pengumpulan yang di-deploy sendiri.

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

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

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

Sebelum memulai

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

Menyiapkan project dan alat

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

  • Project Google Cloud dengan Cloud Monitoring API diaktifkan.

    • Jika Anda tidak memiliki project Google Cloud , lakukan hal berikut:

      1. Di Google Cloud console, 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 API & layanan:

        Buka API & layanan

      2. Pilih project Anda.

      3. Klik Aktifkan API dan Layanan.

      4. Telusuri "Pemantauan".

      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 di Memulai cepat 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 perlu memasukkan project ID atau nama cluster berulang kali, lakukan konfigurasi berikut:

  • Konfigurasikan alat command line sebagai berikut:

    • Konfigurasikan gcloud CLI untuk merujuk ke ID projectGoogle Cloud Anda:

      gcloud config set project PROJECT_ID

    • Konfigurasikan kubectl CLI untuk menggunakan cluster Anda:

      kubectl config set-cluster CLUSTER_NAME

    Untuk informasi selengkapnya tentang alat ini, lihat referensi berikut:

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

Jika cluster Kubernetes Anda telah mengaktifkan Workload Identity Federation untuk GKE, Anda dapat melewati bagian ini.

Saat berjalan di GKE, 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 Anda tidak menggunakan Workload Identity Federation untuk GKE, dan sebelumnya telah menghapus salah satu peran tersebut dari akun layanan node default, Anda harus menambahkan kembali izin yang hilang tersebut sebelum melanjutkan.

Mengonfigurasi akun layanan untuk Workload Identity Federation for GKE

Jika cluster Kubernetes Anda tidak mengaktifkan Workload Identity Federation untuk GKE, Anda dapat melewati bagian ini.

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

Membuat dan mengikat akun layanan

Langkah ini muncul di beberapa tempat dalam dokumentasi Managed Service for Prometheus. Jika Anda telah melakukan langkah ini sebagai bagian dari tugas sebelumnya, Anda tidak perlu mengulanginya. Langsung ke Memberikan otorisasi ke 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. \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=gmp-test-sa@PROJECT_ID.

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

Memberikan otorisasi ke akun layanan

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

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

Jika telah 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. \
  --role=roles/monitoring.metricWriter

Men-debug konfigurasi Workload Identity Federation for GKE

Jika Anda mengalami masalah saat membuat Workload Identity Federation for GKE berfungsi, lihat dokumentasi untuk memverifikasi penyiapan Workload Identity Federation for GKE dan panduan pemecahan masalah Workload Identity Federation for GKE.

Karena kesalahan ketik dan penyalinan sebagian adalah sumber error paling umum saat mengonfigurasi Workload Identity Federation untuk GKE, sebaiknya gunakan variabel yang dapat diedit dan ikon salin-tempel yang dapat diklik yang disematkan dalam contoh kode dalam petunjuk ini.

Workload Identity Federation for GKE di lingkungan produksi

Contoh yang dijelaskan dalam dokumen ini mengikat akun layanan Google Cloud ke akun layanan Kubernetes default dan memberi akun layanan Google Cloudsemua 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 informasi selengkapnya tentang cara mengonfigurasi akun layanan untuk pengelolaan identitas beban kerja, lihat Menggunakan Workload Identity Federation untuk GKE.

Menyiapkan OpenTelemetry Collector

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

OpenTelemetry Collector analog 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 Anda dapat menggunakan builder kolektor untuk mem-build kolektor Anda sendiri yang hanya terdiri dari komponen yang Anda perlukan. Untuk mem-build kolektor yang akan digunakan dengan Managed Service for Prometheus, Anda memerlukan komponen berikut:

  • Eksportir Managed Service for Prometheus, yang menulis metrik Anda ke Managed Service for Prometheus.
  • Penerima untuk meng-scrap metrik Anda. Dokumen ini mengasumsikan bahwa Anda menggunakan penerima Prometheus OpenTelemetry, tetapi pengekspor Managed Service for Prometheus kompatibel dengan penerima metrik OpenTelemetry apa pun.
  • Pemroses untuk mengelompokkan dan menandai metrik Anda guna menyertakan ID resource penting, bergantung pada lingkungan Anda.

Komponen ini diaktifkan menggunakan file konfigurasi yang diteruskan ke Pengumpul dengan flag --config.

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

Mengonfigurasi dan men-deploy Kolektor

Baik Anda menjalankan koleksi di Google Cloud atau di lingkungan lain, Anda tetap dapat mengonfigurasi OpenTelemetry Collector untuk diekspor ke Managed Service for Prometheus. Perbedaan terbesarnya adalah cara Anda mengonfigurasi Pengumpul. Di lingkungan non-Google Cloud , mungkin ada pemformatan data metrik tambahan yang diperlukan agar kompatibel dengan Managed Service for Prometheus. Namun, di Google Cloud, sebagian besar format ini dapat otomatis terdeteksi 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 eksportir Managed Service for Prometheus untuk menyalin endpoint metrik di Pod Kubernetes dan mengekspor metrik tersebut ke Managed Service for Prometheus. Pemroses pipeline memformat dan mengelompokkan data.

Untuk mengetahui detail selengkapnya tentang fungsi setiap bagian konfigurasi ini, bersama dengan konfigurasi untuk berbagai platform, lihat bagian berikut yang mendetail tentang metrik scraping dan menambahkan pemroses.

Saat menggunakan konfigurasi Prometheus yang ada dengan penerima prometheus OpenTelemetry Collector, ganti karakter tanda dolar tunggal, , dengan karakter ganda, , untuk menghindari pemicuan penggantian variabel lingkungan. Untuk informasi selengkapnya, lihat Mengambil metrik Prometheus.

Anda dapat mengubah konfigurasi ini berdasarkan lingkungan, penyedia, dan metrik yang ingin di-scrape, tetapi contoh konfigurasi adalah titik awal yang direkomendasikan untuk dijalankan di GKE.

Menjalankan OpenTelemetry Collector di luar Google Cloud

Menjalankan OpenTelemetry Collector di luar Google Cloud, seperti di lokal atau di penyedia cloud lain, mirip dengan menjalankan Collector di GKE. Namun, metrik yang Anda ambil kemungkinan besar tidak akan otomatis menyertakan data yang paling sesuai untuk formatnya di Managed Service for Prometheus. Oleh karena itu, Anda harus lebih berhati-hati untuk mengonfigurasi kolektor guna memformat metrik agar kompatibel dengan Managed Service for Prometheus.

Anda dapat memasukkan konfigurasi berikut ke dalam file bernama config.yaml untuk 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 scraping penemuan layanan Kubernetes untuk Prometheus. Untuk informasi selengkapnya, lihat mengambil 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 eksportir googlemanagedprometheus. Untuk informasi selengkapnya tentang eksportir, lihat Mengonfigurasi eksportir googlemanagedprometheus.

Saat menggunakan konfigurasi Prometheus yang ada dengan penerima prometheus OpenTelemetry Collector, ganti karakter tanda dolar tunggal, , dengan karakter ganda, , untuk menghindari pemicuan penggantian variabel lingkungan. Untuk informasi selengkapnya, lihat Mengambil metrik Prometheus.

Untuk informasi tentang praktik terbaik dalam mengonfigurasi Pemroses di cloud lain, lihat Amazon EKS atau Azure AKS.

Men-deploy aplikasi contoh

Aplikasi contoh memunculkan metrik penghitung example_requests_total dan metrik histogram example_random_numbers (di antara yang lainnya) di port metrics-nya. Manifes untuk contoh ini menentukan tiga replika.

Untuk men-deploy aplikasi contoh, jalankan perintah berikut:

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

Membuat konfigurasi kolektor sebagai ConfigMap

Setelah membuat konfigurasi dan menempatkannya dalam file bernama config.yaml, gunakan file tersebut untuk membuat ConfigMap Kubernetes berdasarkan file config.yaml Anda. Saat 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.128.0
        args:
        - --config
        - /etc/otel/config.yaml
        - --feature-gates=exporter.googlemanagedprometheus.intToDouble
        volumeMounts:
        - mountPath: /etc/otel/
          name: otel-config
      volumes:
      - name: otel-config
        configMap:
          name: otel-config

Buat deployment Collector di cluster Kubernetes Anda dengan menjalankan perintah berikut:

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

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

Untuk informasi tentang cara membuat kueri data, 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. Di cluster Kubernetes non-GKE, kredensial harus diberikan secara eksplisit ke OpenTelemetry Collector menggunakan flag atau variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

  1. Tetapkan konteks ke project target Anda:

    gcloud config set project PROJECT_ID

  2. Buat akun layanan:

    gcloud iam service-accounts create gmp-test-sa

    Langkah ini akan membuat akun layanan yang mungkin sudah Anda buat di petunjuk Workload Identity Federation untuk GKE.

  3. Berikan izin yang diperlukan ke akun layanan:

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

  4. 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.

  5. Tambahkan file kunci sebagai secret ke cluster non-GKE Anda:

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

  6. Buka referensi Deployment OpenTelemetry untuk mengedit:

    kubectl -n NAMESPACE_NAME edit deployment otel-collector

  1. Tambahkan teks yang ditampilkan dalam tebal ke resource:

    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
...

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

Mengambil metrik Prometheus

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

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

Konfigurasi penerima Prometheus 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 yang dapat Anda ubah sesuai kebutuhan untuk meng-scrape aplikasi.

Saat menggunakan konfigurasi Prometheus yang ada dengan penerima prometheus OpenTelemetry Collector, ganti karakter tanda dolar tunggal, , dengan karakter ganda, , untuk menghindari pemicuan penggantian variabel lingkungan. Hal ini sangat penting untuk dilakukan untuk nilai replacement dalam bagian relabel_configs. 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 informasi selengkapnya, lihat dokumentasi OpenTelemetry.

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

Menambahkan pemroses

Pemroses OpenTelemetry mengubah data telemetri sebelum diekspor. Anda dapat menggunakan pemroses berikut untuk memastikan metrik ditulis dalam format yang kompatibel dengan Managed Service for Prometheus.

Mendeteksi atribut resource

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

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

Kegagalan untuk menetapkan label ini ke nilai unik dapat mengakibatkan error "timeseries duplikasi" saat mengekspor ke Managed Service for Prometheus. Dalam banyak kasus, nilai dapat terdeteksi secara otomatis untuk label ini, tetapi dalam beberapa kasus, Anda mungkin harus memetakan sendiri. Bagian lain dari bagian ini menjelaskan skenario ini.

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.

Jika memungkinkan, isi atribut lainnya secara otomatis menggunakan pemroses pendeteksian resource. Namun, bergantung pada lingkungan Anda, beberapa atribut mungkin tidak dapat dideteksi secara otomatis. Dalam hal ini, Anda dapat menggunakan pemroses lain untuk menyisipkan nilai ini secara manual atau mengurainya dari label metrik. Bagian berikut mengilustrasikan konfigurasi untuk mendeteksi resource di berbagai platform.

GKE

Saat menjalankan OpenTelemetry di GKE, Anda harus mengaktifkan pemroses deteksi resource untuk mengisi label resource. Pastikan metrik Anda belum berisi label resource yang dikhususkan. 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 akan menggantikan bagian processors jika sudah ada.

Amazon EKS

Detektor resource EKS tidak otomatis mengisi atribut cluster atau namespace. Anda dapat memberikan nilai ini secara manual menggunakan pemroses resource, seperti yang ditunjukkan pada 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 memberikan nilai ini secara manual menggunakan pemroses resource, seperti yang ditunjukkan pada 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 menggunakan pemroses groupbyattrs; lihat 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 dalam 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

Membuat konfigurasi kolektor sebagai ConfigMap menjelaskan cara menggunakan konfigurasi. Bagian tersebut mengasumsikan bahwa Anda telah menempatkan konfigurasi dalam file yang disebut config.yaml.

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

Atau, Anda dapat menetapkan atribut resource yang diperlukan secara manual dalam variabel lingkungan, OTEL_RESOURCE_ATTRIBUTES, dengan daftar pasangan nilai kunci yang dipisahkan koma, misalnya:

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

Kemudian, gunakan pemroses detector 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 bentrok dengan atribut resource yang diperlukan (seperti location, cluster, atau namespace), ganti namanya untuk menghindari bentrok. Konvensi Prometheus adalah menambahkan awalan exported_ ke nama label. Untuk menambahkan awalan ini, gunakan pemroses transformasi.

Konfigurasi processors berikut mengganti nama potensi konflik dan menyelesaikan kunci yang bertentangan 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 eksportir Anda memantau beberapa namespace. Misalnya, saat menjalankan eksportir kube-state-metrics.

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

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

Pada contoh sebelumnya, dengan metrik yang memiliki label namespace, cluster, 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 penggunaan resource kolektor.

Batch processing

Dengan permintaan batch, Anda dapat menentukan jumlah titik data yang akan dikirim dalam satu permintaan. Perhatikan bahwa Cloud Monitoring membatasi 200 deret waktu per permintaan. Aktifkan pemroses batch 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 Anda 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 eksportir googlemanagedprometheus

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

exporters:
  googlemanagedprometheus:

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

Setelan project_id

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

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

  • Menetapkan project di konfigurasi eksportir
  • Tambahkan atribut resource gcp.project.id ke metrik Anda.

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

Menetapkan project di konfigurasi eksportir

Cuplikan konfigurasi berikut mengirimkan metrik ke Managed Service for Prometheus di Google Cloud project 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 tahu bahwa setiap metrik yang masuk melalui Pengumpul ini harus dikirim ke MY_PROJECT.

Menetapkan 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 akan 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 dengan menggunakan pemroses di konfigurasi Pengumpul, 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]

Menetapkan opsi klien

Pengekspor googlemanagedprometheus menggunakan klien gRPC untuk 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 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. Default-nya adalah nomor build dan versi OpenTelemetry Collector, misalnya, opentelemetry-collector-contrib 0.128.0.
  • endpoint: Menetapkan endpoint tempat data metrik akan dikirim.
  • use_insecure: Jika benar, menggunakan gRPC sebagai transpor komunikasi. Hanya berpengaruh jika nilai endpoint bukan "".
  • grpc_pool_size: Menetapkan ukuran kumpulan koneksi di klien gRPC.
  • prefix: Mengonfigurasi awalan metrik yang dikirim ke Managed Service for Prometheus. Default-nya adalah prometheus.googleapis.com. Jangan ubah awalan ini; tindakan ini akan menyebabkan metrik tidak dapat dikueri dengan PromQL di UI Cloud Monitoring.

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

Semua setelan ini ditetapkan di bawah blok metric di bagian eksportir 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.128.0
      endpoint: ""
      use_insecure: false
      grpc_pool_size: 1
      prefix: prometheus.googleapis.com

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

Langkah berikutnya