Membuat kueri menggunakan Grafana

Setelah men-deploy Google Cloud Managed Service for Prometheus, Anda dapat membuat kueri data yang dikirim ke layanan terkelola dan menampilkan hasilnya dalam diagram dan dasbor.

Dokumen ini menjelaskan cakupan metrik, yang menentukan data yang dapat Anda kueri, dan cara menggunakan Grafana untuk mengambil dan menggunakan data yang telah Anda kumpulkan.

Semua antarmuka kueri untuk Google Cloud Managed Service for Prometheus dikonfigurasi untuk mengambil data dari Monarch menggunakan Cloud Monitoring API. Dengan membuat kueri Monarch, bukan membuat kueri data dari server Prometheus lokal, Anda akan mendapatkan pemantauan global dalam skala besar.

Sebelum memulai

Jika Anda belum men-deploy layanan terkelola, siapkan koleksi terkelola atau koleksi yang di-deploy sendiri. Anda dapat melewati langkah ini jika hanya tertarik untuk membuat kueri metrik Cloud Monitoring menggunakan PromQL.

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:

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 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 membaca data metrik.

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

Untuk mengizinkan akun layanan Anda membaca dari cakupan metrik multi-project, ikuti petunjuk berikut, lalu lihat Mengubah project yang dikueri. 

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

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.

Kueri dan cakupan metrik

Data yang dapat Anda kueri ditentukan oleh cakupan metrik konstruksi Cloud Monitoring, terlepas dari metode yang Anda gunakan untuk membuat kueri data. Misalnya, jika Anda menggunakan Grafana untuk membuat kueri data Managed Service for Prometheus, setiap cakupan metrik harus dikonfigurasi sebagai sumber data terpisah.

Cakupan metrik Monitoring adalah konstruksi hanya baca yang memungkinkan Anda membuat kueri data metrik yang termasuk dalam beberapa project Google Cloud. Setiap cakupan metrik dihosting oleh project Google Cloud khusus yang disebut project pencakupan.

Secara default, project adalah project pencakupan untuk cakupan metriknya sendiri, dan cakupan metrik berisi metrik dan konfigurasi untuk project tersebut. Project pencakupan dapat memiliki lebih dari satu project yang dipantau dalam cakupan metriknya, dan metrik serta konfigurasi dari semua project yang dipantau dalam cakupan metrik terlihat oleh project pencakupan. Project yang dipantau juga dapat termasuk dalam lebih dari satu cakupan metrik.

Saat Anda membuat kueri metrik dalam project pencakupan, dan jika project pencakupan tersebut menghosting cakupan metrik multi-project, Anda dapat mengambil data dari beberapa project. Jika cakupan metrik berisi semua project Anda, kueri dan aturan Anda akan dievaluasi secara global.

Untuk informasi selengkapnya tentang pencakupan project dan cakupan metrik, lihat Cakupan metrik. Untuk informasi tentang cara mengonfigurasi cakupan metrik multi-project, baca Melihat metrik untuk beberapa project.

Data Google Cloud Managed Service for Prometheus di Cloud Monitoring

Cara paling sederhana untuk memverifikasi bahwa data Prometheus Anda diekspor adalah dengan menggunakan halaman Cloud Monitoring Metrics Explorer di Konsol Google Cloud, yang mendukung PromQL. Untuk mengetahui petunjuknya, baca Membuat kueri menggunakan PromQL di Cloud Monitoring.

Anda juga dapat mengimpor dasbor Grafana ke Cloud Monitoring. Hal ini memungkinkan Anda untuk tetap menggunakan dasbor Grafana yang dibuat komunitas atau pribadi tanpa harus mengonfigurasi atau men-deploy instance Grafana.

Grafana

Google Cloud Managed Service for Prometheus menggunakan sumber data Prometheus bawaan untuk Grafana, yang berarti Anda dapat terus menggunakan dasbor Grafana buatan komunitas atau pribadi tanpa perubahan apa pun.

Kerahkan Grafana

Jika belum memiliki deployment Grafana yang berjalan di cluster, Anda dapat membuat deployment uji efemeral untuk bereksperimen.

Untuk membuat deployment Grafana efemeral, terapkan manifes grafana.yaml Managed Service for Prometheus ke cluster Anda, lalu teruskan layanan grafana ke komputer lokal Anda. Contoh berikut meneruskan layanan ke port 3000.

  1. Terapkan manifes grafana.yaml:

    kubectl -n NAMESPACE_NAME apply -f  https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/6ebc1afa8e609febe8d687bb7fa6bd2375e46db1/examples/grafana.yaml

  2. Teruskan port layanan grafana ke komputer lokal Anda. Contoh berikut meneruskan layanan ke port 3000:

    kubectl -n NAMESPACE_NAME port-forward svc/grafana 3000

    Perintah ini tidak ditampilkan, dan saat dijalankan, perintah ini melaporkan akses ke URL.

    Anda dapat mengakses Grafana di browser pada URL http://localhost:3000 dengan nama pengguna:sandi admin:admin.

Kemudian, tambahkan sumber data Prometheus baru ke Grafana dengan melakukan hal berikut:

  1. Buka deployment Grafana Anda, misalnya, dengan menjelajahi URL http://localhost:3000 untuk membuka halaman sambutan Grafana.

  2. Pilih Connections dari menu utama Grafana, lalu pilih Data Sources.

    Menambahkan sumber data di Grafana.

  3. Pilih Add data source, lalu pilih Prometheus sebagai database deret waktu.

    Menambahkan sumber data Prometheus.

  4. Beri nama sumber data, tetapkan kolom URL ke http://localhost:9090, lalu pilih Save & Test. Anda dapat mengabaikan error apa pun yang menyatakan bahwa sumber data tidak dikonfigurasi dengan benar.

  5. Salin URL layanan lokal untuk deployment Anda, yang akan terlihat seperti berikut:

    http://grafana.NAMESPACE_NAME.svc:3000

Mengonfigurasi dan mengautentikasi sumber data Grafana

Semua API Google Cloud memerlukan autentikasi menggunakan OAuth2. Namun, Grafana tidak mendukung autentikasi OAuth2 untuk sumber data Prometheus. Untuk menggunakan Grafana dengan Google Cloud Managed Service for Prometheus, gunakan sinkronisasi sumber data untuk membuat kredensial OAuth2 dan menyinkronkannya ke Grafana melalui API sumber data Grafana.

Anda harus menggunakan penyinkron sumber data untuk mengonfigurasi dan mengizinkan Grafana mengkueri data secara global. Jika Anda tidak mengikuti langkah-langkah ini, Grafana hanya akan mengeksekusi kueri terhadap data di server Prometheus lokal.

Penyinkron sumber data adalah alat antarmuka command line yang menggunakan Kubernetes CronJob untuk menyinkronkan nilai konfigurasi dari jarak jauh ke sumber data Grafana Prometheus tertentu. Langkah ini memastikan bahwa sumber data Grafana Anda telah mengonfigurasi hal berikut dengan benar:

  • Autentikasi, dilakukan dengan memuat ulang token akses OAuth2 secara berkala
  • Cloud Monitoring API ditetapkan sebagai URL server Prometheus
  • Metode HTTP ditetapkan ke GET
  • Jenis dan versi Prometheus ditetapkan ke minimal 2.40.x
  • Nilai waktu tunggu HTTP dan Kueri ditetapkan ke 2 menit

Penyinkron sumber data menggunakan akun layanan lokal cluster Anda untuk membuat token akses Google Cloud API secara berkala dengan izin IAM yang diperlukan untuk mengkueri data Cloud Monitoring. Karena token akses Google Cloud API memiliki masa aktif satu jam, sinkronisasi sumber data berjalan setiap 30 menit untuk memastikan Anda memiliki koneksi terautentikasi tanpa gangguan antara Grafana dan Cloud Monitoring API.

Untuk men-deploy dan menjalankan sinkronisasi sumber data, lakukan hal berikut:

  1. Pilih project, cluster, dan namespace untuk men-deploy sinkronisasi sumber data. Sebaiknya deploy sinkronisasi sumber data di cluster yang termasuk dalam project cakupan metrik multi-project. Penyinkron sumber data menggunakan project Google Cloud yang dikonfigurasi sebagai project pencakupan.

    Selanjutnya, pastikan Anda mengonfigurasi dan mengizinkan penyinkron sumber data dengan benar:

    Kemudian, tentukan apakah Anda perlu memberi otorisasi lebih lanjut ke sinkronisasi sumber data untuk kueri multi-project:

  2. Cari tahu URL instance Grafana Anda, misalnya https://yourcompanyname.grafana.net untuk deployment Grafana Cloud, atau http://grafana.NAMESPACE_NAME.svc:3000 untuk instance lokal yang dikonfigurasi menggunakan YAML deployment pengujian.

    Jika Anda men-deploy Grafana secara lokal dan cluster dikonfigurasi untuk mengamankan semua traffic dalam cluster menggunakan TLS, Anda harus menggunakan https:// di URL dan melakukan autentikasi menggunakan salah satu opsi autentikasi TLS yang didukung.

  3. Pilih sumber data Grafana Prometheus yang ingin Anda gunakan untuk Managed Service for Prometheus, yang dapat berupa sumber data baru atau yang sudah ada sebelumnya, lalu cari dan tuliskan UID sumber data. UID sumber data dapat ditemukan di bagian terakhir URL saat menjelajahi atau mengonfigurasi sumber data, misalnya https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.

  4. Siapkan akun layanan Grafana, beri peran "Admin", dan buat token akun layanan. Pastikan masa berlaku token ditetapkan ke "Tidak Ada Masa Berlaku".

  5. Siapkan variabel lingkungan berikut menggunakan hasil dari langkah sebelumnya:

    # These values are required.
PROJECT_ID=SCOPING_PROJECT_ID
GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL
DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID
GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN

  6. Jalankan perintah berikut untuk membuat CronJob yang memperbarui sumber data saat inisialisasi, lalu setiap 30 menit. Jika Anda menggunakan Workload Identity, nilai NAMESPACE_NAME harus berupa namespace yang sama dengan yang sebelumnya Anda ikat ke akun layanan.

    curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml \
| sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' \
| kubectl -n NAMESPACE_NAME apply -f -

  7. Buka sumber data Grafana yang baru dikonfigurasi dan pastikan nilai URL server Prometheus dimulai dengan https://monitoring.googleapis.com. Anda mungkin perlu memuat ulang halaman. Setelah diverifikasi, lanjutkan ke bagian bawah halaman dan pilih Save & test. Anda harus memilih tombol ini minimal sekali untuk memastikan pelengkapan otomatis label di Grafana berfungsi.

Menjalankan kueri menggunakan Grafana

Anda sekarang dapat membuat dasbor Grafana dan menjalankan kueri menggunakan sumber data yang dikonfigurasi. Screenshot berikut menunjukkan diagram Grafana yang menampilkan metrik up:

Diagram Grafana untuk metrik naik Google Cloud Managed Service for Prometheus.

Untuk mengetahui informasi tentang cara membuat kueri metrik sistem Google Cloud menggunakan PromQL, lihat metrik PromQL untuk Cloud Monitoring.

Menjalankan sinkronisasi sumber data di luar GKE

Anda dapat melewati bagian ini jika menjalankan sinkronisasi sumber data di cluster Google Kubernetes Engine. Jika Anda mengalami masalah autentikasi di GKE, lihat Memverifikasi kredensial akun layanan.

Saat berjalan di GKE, sinkronisasi sumber data akan otomatis mengambil kredensial dari lingkungan berdasarkan akun layanan node atau penyiapan Workload Identity. Dalam cluster Kubernetes non-GKE, kredensial harus diberikan secara eksplisit ke sinkronisasi sumber data menggunakan 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 telah Anda buat di petunjuk Workload Identity.

  3. 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.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

  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.iam.gserviceaccount.com

  5. Tetapkan jalur file kunci menggunakan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

Mengizinkan penyinkron sumber data untuk mendapatkan pemantauan multi-project

Google Cloud Managed Service for Prometheus mendukung pemantauan multi-project menggunakan cakupan metrik. Jika project lokal adalah project pencakupan Anda, dan Anda telah mengikuti petunjuk untuk memverifikasi atau mengonfigurasi akun layanan untuk project lokal, pembuatan kueri multi-project seharusnya dapat dilakukan tanpa konfigurasi lebih lanjut.

Jika project lokal bukan project pencakupan, Anda harus mengizinkan akun layanan komputasi default project lokal atau akun layanan Workload Identity agar memiliki akses monitoring.viewer ke project pencakupan. Kemudian, teruskan ID project pencakupan sebagai nilai variabel lingkungan PROJECT_ID.

Jika menggunakan akun layanan default Compute Engine, Anda dapat melakukan salah satu hal berikut:

Untuk memberi akun layanan izin yang diperlukan untuk mengakses project Google Cloud lain, lakukan hal berikut:

  1. Beri akun layanan izin untuk membaca dari project target yang ingin Anda kueri:

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

  2. Saat mengonfigurasi penyinkron sumber data, teruskan ID project pencakupan sebagai nilai variabel lingkungan PROJECT_ID.

Memeriksa CronJob

Untuk memeriksa CronJob dan memastikan semua variabel sudah ditetapkan dengan benar, jalankan perintah berikut:

kubectl describe cronjob datasource-syncer

Untuk melihat log Tugas yang awalnya mengonfigurasi Grafana, jalankan perintah berikut segera setelah menerapkan file datasource-syncer.yaml:

kubectl logs job.batch/datasource-syncer-init

Pembongkaran

Untuk menonaktifkan Cronjob sinkronisasi sumber data, jalankan perintah berikut:

kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/main/cmd/datasource-syncer/datasource-syncer.yaml

Menonaktifkan sinkronisasi sumber data akan menghentikan update Grafana tertaut dengan kredensial autentikasi baru, dan akibatnya kueri Layanan Terkelola untuk Prometheus tidak akan berfungsi lagi.

Kompatibilitas API

Endpoint Prometheus HTTP API berikut didukung oleh Google Cloud Managed Service for Prometheus dengan URL yang diawali dengan https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus/api/v1/.

Untuk dokumentasi selengkapnya, lihat dokumentasi referensi Cloud Monitoring API.

Untuk mengetahui informasi tentang kompatibilitas PromQL, lihat Dukungan PromQL.

  • Endpoint berikut didukung sepenuhnya:

    • /api/v1/query
    • /api/v1/query_range
    • /api/v1/metadata
    • /api/v1/labels
    • /api/v1/query_exemplars

  • Endpoint /api/v1/label/<label_name>/values hanya berfungsi jika label __name__ diberikan dengan menggunakannya sebagai nilai <label_name> atau dengan mencocokkan secara persis dengannya menggunakan pemilih seri. Misalnya, panggilan berikut didukung sepenuhnya:

    • /api/v1/label/__name__/values
    • /api/v1/label/__name__/values?match[]={__name__=~".*metricname.*"}
    • /api/v1/label/labelname/values?match[]={__name__="metricname"}

    Batasan ini menyebabkan kueri variabel label_values($label) di Grafana gagal. Sebagai gantinya, Anda dapat menggunakan label_values($metric, $label). Jenis kueri ini direkomendasikan karena menghindari pengambilan nilai untuk label pada metrik yang tidak relevan dengan dasbor tertentu.

  • Endpoint /api/v1/series didukung untuk permintaan GET, tetapi tidak untuk permintaan POST. Saat Anda menggunakan sinkronisasi sumber data atau proxy frontend, batasan ini akan dikelola untuk Anda. Anda juga dapat mengonfigurasi sumber data Prometheus di Grafana untuk mengeluarkan permintaan GET saja.

Langkah selanjutnya