Setelah mengumpulkan metrik dari
workload yang di-deploy di lingkungan air-gapped Google Distributed Cloud (GDC), Anda dapat mulai
menganalisisnya. Untuk menganalisis metrik, Anda dapat memvisualisasikan dan memfilternya di dasbor Grafana yang informatif atau mengaksesnya langsung dari Cortex menggunakan alat curl untuk pembuatan skrip dan otomatisasi yang fleksibel.
Halaman ini memberikan petunjuk mendetail tentang cara membuat kueri dan memvisualisasikan metrik menggunakan antarmuka pengguna Grafana dan alat curl untuk endpoint Cortex guna mendapatkan insight tentang performa workload Anda.
Anda dapat mengakses metrik dengan salah satu dari dua metode berikut:
- Dasbor Grafana: Jelajahi tren dan identifikasi anomali dengan visualisasi intuitif dari metrik utama seperti pemakaian CPU, penggunaan penyimpanan, dan aktivitas jaringan. Grafana menyediakan antarmuka yang mudah digunakan untuk memfilter dan menganalisis data beban kerja Anda di dasbor.
- Endpoint Cortex: Untuk kasus penggunaan yang lebih canggih, kueri instance Cortex project Anda secara langsung menggunakan alat
curldi command line. Cortex menyimpan metrik Prometheus project Anda dan menyediakan endpoint HTTP untuk akses terprogram. Akses ini memungkinkan Anda mengekspor data, mengotomatiskan tugas, dan membuat integrasi kustom.
Sebelum memulai
Untuk mendapatkan izin yang diperlukan guna membuat kueri dan memvisualisasikan metrik di dasbor Grafana, minta Admin IAM Organisasi atau Admin IAM Project untuk memberi Anda salah satu peran Grafana Viewer Organisasi atau Grafana Viewer Project yang telah ditentukan sebelumnya. Bergantung pada tingkat akses dan izin yang Anda butuhkan, Anda dapat memperoleh peran Grafana di organisasi atau project.
Atau, untuk mendapatkan izin yang diperlukan untuk membuat kueri metrik dari endpoint Cortex, minta Admin IAM Project Anda untuk memberi Anda peran Project Cortex Prometheus Viewer di namespace project Anda.
Tabel berikut merangkum persyaratan Role untuk PA persona.
| Persona | Objek | Cluster | Peran | Namespace | Grup/Pengguna | Konfigurasi |
|---|---|---|---|---|---|---|
| PA | grafana | admin org | project-grafana-viewer |
platform-obs | Grup | 1 |
| PA | cortex | admin org | project-cortex-prometheus-viewer |
platform-obs | Grup | 2 |
| PA | grafana | admin org | project-grafana-viewer |
platform-obs | Pengguna | 3 |
| PA | cortex | admin org | project-cortex-prometheus-viewer |
platform-obs | Pengguna | 4 |
Ganti variabel berikut dengan tepat:
| Variabel | Deskripsi |
|---|---|
KUBECONFIG |
Anda akan memerlukan kubeconfig untuk cluster tertentu yang berisi NAMESPACE tempat RoleBinding ini akan diterapkan. |
RULE_NAME |
Nama unik untuk resource RoleBinding ini dalam namespace. Contoh, io-root-cortex-prometheus-viewer. |
NAMESPACE |
Namespace Kubernetes tempat RoleBinding ini akan dibuat dan diterapkan. Cari kolom Namespace di tabel sebelumnya. |
EMAIL_ADDRESS |
ID untuk pengguna yang diberi peran. Biasanya berupa alamat email. Misalnya, infrastructure-operator@example.com. |
ROLE |
Nama Role yang berisi izin yang ingin Anda berikan kepada pengguna. Cari peran yang tersedia di tabel sebelumnya |
GROUP_NAME |
Nama Role yang berisi izin yang ingin Anda berikan kepada pengguna. Contoh, io-group. |
ZONE |
Nama Zona |
Config 1
Konfigurasi ini ditujukan untuk persona PA, yang menargetkan objek grafana di cluster org-admin.
Hal ini memberikan peran project-grafana-viewer dalam namespace platform-obs kepada Group.
Perintah Kubectl
Berikut adalah format perintah umum:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-grafana-viewerContoh:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --group=my-team --namespace=platform-obsJalur file IAC
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>File YAML
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: Group name: GROUP_NAME apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-grafana-viewer apiGroup: rbac.authorization.k8s.io
Config 2
Konfigurasi ini ditujukan untuk persona PA, yang menargetkan objek cortex di cluster org-admin.
Hal ini memberikan peran project-cortex-prometheus-viewer dalam namespace platform-obs kepada Group.
Perintah Kubectl
Berikut adalah format perintah umum:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --group=`GROUP_NAME` --role=project-cortex-prometheus-viewerContoh:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --group=my-team --namespace=platform-obsJalur file IAC
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`GROUP_NAME`/<YAML_FILE>File YAML
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: Group name: GROUP_NAME apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-cortex-prometheus-viewer apiGroup: rbac.authorization.k8s.io
Config 3
Konfigurasi ini ditujukan untuk persona PA, yang menargetkan objek grafana di cluster org-admin.
Hal ini memberikan peran project-grafana-viewer dalam namespace platform-obs kepada User.
Perintah Kubectl
Berikut adalah format perintah umum:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-grafana-viewerContoh:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-grafana-viewers-binding --role=project-grafana-viewer --user=my-email@example.com --namespace=platform-obsJalur file IAC
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>File YAML
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: User name: EMAIL_ADDRESS apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-grafana-viewer apiGroup: rbac.authorization.k8s.io
Config 4
Konfigurasi ini ditujukan untuk persona PA, yang menargetkan objek cortex di cluster org-admin.
Hal ini memberikan peran project-cortex-prometheus-viewer dalam namespace platform-obs kepada User.
Perintah Kubectl
Berikut adalah format perintah umum:
kubectl --kubeconfig `KUBECONFIG` create rolebinding `RULE_NAME` -n platform-obs --user=`EMAIL_ADDRESS` --role=project-cortex-prometheus-viewerContoh:
kubectl --kubeconfig <path-to-kubeconfig> create rolebinding project-cortex-prometheus-viewer-binding --role=project-cortex-prometheus-viewer --user=my-email@example.com --namespace=platform-obsJalur file IAC
/infrastructure/zonal/zones/`ZONE`/org-admin/rolebindings/`EMAIL_ADDRESS`/<YAML_FILE>File YAML
apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: RULE_NAME namespace: platform-obs subjects: - kind: User name: EMAIL_ADDRESS apiGroup: rbac.authorization.k8s.io roleRef: kind: Role name: project-cortex-prometheus-viewer apiGroup: rbac.authorization.k8s.io
Untuk mengetahui informasi selengkapnya tentang peran ini, lihat Siapkan izin IAM.
Mendapatkan dan memfilter metrik
Pilih salah satu metode berikut untuk membuat kueri, memvisualisasikan tren, dan memfilter metrik dari workload project Anda:
Dasbor Grafana
Bagian ini menjelaskan cara mengakses metrik menggunakan dasbor Grafana.
Mengidentifikasi endpoint Grafana Anda
URL berikut adalah endpoint instance Grafana project Anda:
https://GDC_URL/PROJECT_NAMESPACE/grafana
Ganti kode berikut:
GDC_URL: URL organisasi Anda di GDC.PROJECT_NAMESPACE: namespace project Anda.Misalnya, endpoint Grafana untuk project
platform-obsdi organisasiorg-1adalahhttps://org-1/platform-obs/grafana.
Melihat metrik di antarmuka pengguna Grafana
Mengambil metrik di antarmuka pengguna Grafana:
- Di konsol GDC, pilih project Anda.
- Di menu navigasi, pilih Operations > Monitoring.
Klik Lihat semua di Grafana.
Halaman baru akan membuka endpoint Grafana Anda dan menampilkan antarmuka pengguna.
Di antarmuka pengguna, klik jelajahi Jelajahi dari menu navigasi untuk membuka halaman Jelajahi.
Dari menu di panel Jelajahi, pilih sumber data untuk mengambil metrik, sesuai dengan jenis semesta Anda:
Semesta zona tunggal: Pilih prometheus untuk menampilkan metrik dari zona tunggal semesta Anda.
Universe multi-zona: Grafana dapat terhubung ke zona yang berbeda dan menampilkan data lintas zona. Pilih Metrik ZONE_NAME untuk menampilkan metrik dari zona mana pun di semesta Anda, terlepas dari zona tempat Anda login.
Selain itu, untuk memiliki visualisasi data lintas zona dalam satu dasbor dan menambahkan beberapa zona ke kueri, pilih Campuran sebagai sumber data.
Masukkan kueri untuk menelusuri metrik menggunakan ekspresi PromQL (Prometheus Query Language). Anda dapat melakukan langkah ini dengan salah satu cara berikut:
- Pilih metrik dan label untuk kueri Anda dari menu Metrik dan Filter label. Klik tambahkan Tambahkan untuk menambahkan lebih banyak label ke kueri Anda. Kemudian, klik Run query.
- Masukkan kueri Anda langsung di kolom teks Metrik, lalu tekan Shift+Enter untuk menjalankan kueri.
Halaman ini menampilkan metrik yang cocok dengan kueri Anda.

Gambar 1. Opsi menu untuk membuat kueri metrik dari antarmuka pengguna Grafana.
Pada gambar 1, opsi prometheus menampilkan antarmuka yang memungkinkan Anda membuat kueri dari Grafana untuk mengambil metrik.
Untuk contoh nilai label yang dapat Anda gunakan untuk membuat kueri metrik, lihat Contoh kueri dan label.
Endpoint Cortex
Bagian ini menjelaskan cara mengakses metrik menggunakan Cortex.
Mengidentifikasi endpoint Cortex Anda
URL berikut adalah endpoint instance Cortex project Anda:
https://GDC_URL/PROJECT_NAMESPACE/cortex/prometheus/
Ganti kode berikut:
GDC_URL: URL organisasi Anda di GDC.PROJECT_NAMESPACE: namespace project Anda.Misalnya, endpoint Cortex untuk project
platform-obsdi organisasiorg-1adalahhttps://org-1/platform-obs/cortex/prometheus/.
Mengautentikasi permintaan curl
- Download dan instal gdcloud CLI.
Setel properti gdcloud
core/organization_console_url:gdcloud config set core/organization_console_url https://GDC_URLLogin dengan penyedia identitas yang dikonfigurasi:
gdcloud auth loginGunakan nama pengguna dan sandi Anda untuk mengautentikasi dan login.
Jika login berhasil, Anda dapat menggunakan header otorisasi dalam permintaan curl melalui perintah
gdcloud auth print-identity-token. Untuk mengetahui informasi selengkapnya, lihat gdcloud auth.
Memanggil endpoint Cortex
Selesaikan langkah-langkah berikut untuk menjangkau endpoint Cortex menggunakan alat curl:
- Autentikasi permintaan
curl. Gunakan
curluntuk memanggil endpoint Cortex dan memperluas URL menggunakan Format HTTP API Kueri untuk mengkueri metrik.Berikut adalah contoh permintaan
curl:curl https://GDC_URL/PROJECT_NAME/cortex/prometheus/api/v1/query?query=my_metric{cluster="my-cluster"}&time=2015-07-01T20:10:51.781Z \ -H "Authorization: Bearer $(gdcloud auth print-identity-token \ --audiences=https://GDC_URL)"Anda akan mendapatkan output berikut setelah menjalankan perintah. Respons API dalam format JSON.
Contoh kueri dan label
Anda dapat membuat kueri metrik menggunakan nama metrik dan pasangan nilai kunci untuk label. A Kueri PromQL memiliki sintaksis berikut:
metric_name{label_one="value", label_two="value"}
Label memungkinkan Anda membedakan karakteristik metrik. Dengan cara ini, pembuat penampung membuat beban kerja mereka menghasilkan metrik dan menambahkan tag untuk memfilter metrik tersebut.
Misalnya, Anda dapat memiliki metrik api_http_requests_total untuk menghitung jumlah permintaan HTTP yang diterima. Kemudian, Anda dapat menambahkan label request_method pada
metrik ini, yang menggunakan nilai POST, GET, atau PUT. Oleh karena itu, Anda membuat tiga aliran metrik untuk setiap jenis permintaan yang mungkin Anda terima. Dalam
kasus ini, untuk menemukan jumlah permintaan HTTP GET, Anda menjalankan kueri berikut:
api_http_requests_total{request_method="GET"}
Lihat Penamaan Metrik dan Label untuk mengetahui informasi selengkapnya tentang metrik dan label.
Berikut adalah beberapa label default yang ditambahkan oleh resource kustom MonitoringTarget. Anda dapat menggunakan label default ini untuk membuat kueri metrik:
_gdch_service: nama pendek layanan.cluster: nama cluster.container_name: nama container dalam pod.namespace_name: namespace project Anda.pod_name: awalan nama pod.
Tabel berikut menjelaskan label yang ditambahkan Prometheus secara otomatis:
| Label metrik | Deskripsi |
|---|---|
job |
Nama internal tugas pengambilan yang digunakan untuk mengumpulkan metrik. Tugas
yang dibuat oleh resource kustom MonitoringTarget memiliki nama
dengan pola berikut:obs-system/OBS_SHADOW_PROJECT_NAME/MONITORINGTARGET_NAME.MONITORINGTARGET_NAMESPACE/I/JI dan J adalah angka unik yang ditentukan secara internal
untuk menghindari konflik nama. |
instance |
$IP:$PORT layanan yang dibatalkan. Jika resource
workload memiliki beberapa replika, gunakan kolom ini untuk membedakannya. |
Contoh kode berikut menunjukkan penggunaan pasangan nilai kunci untuk label guna membuat kueri metrik yang berbeda:
Melihat semua aliran metrik operasi yang diproses di project Anda:
processed_ops_totalMelihat operasi yang diproses dan dikumpulkan di cluster Kubernetes:
processed_ops_total{cluster="CLUSTER_NAME"}Melihat penggunaan CPU yang dikumpulkan di cluster Kubernetes:
cpu_usage{cluster="CLUSTER_NAME"}
Gunakan alat pelabelan ulang metrik untuk menambahkan label yang awalnya tidak diekspos oleh container yang di-scrap dan mengganti nama metrik yang dihasilkan. Anda harus mengonfigurasi
resource kustom MonitoringTarget untuk menambahkan label pada metrik yang dikumpulkannya.
Tentukan label tersebut di kolom metricsRelabelings pada resource kustom.
Untuk mengetahui informasi selengkapnya, lihat
Metrik label.
Membuat kueri HTTP API
Ringkasan format
Respons API diformat secara konsisten dalam JSON. Permintaan yang berhasil akan selalu menerima kode status 2xx.
Untuk permintaan yang tidak valid, handler API akan menampilkan objek error JSON beserta salah satu kode status HTTP berikut:
- 400 Bad Request: Jika parameter penting tidak ada atau diberikan secara salah.
- 503 Layanan Tidak Tersedia: Jika kueri melampaui batas waktunya atau dibatalkan.
Data yang berhasil dikumpulkan akan disertakan dalam kolom "data" respons.
Format envelope respons JSON adalah sebagai berikut:
{
"status": "success" | "error",
"data": <data>,
// Only set if status is "error". The data field may still hold
// additional data.
"errorType": "<string>",
"error": "<string>",
// Only set if there were warnings while executing the request.
// There will still be data in the data field.
"warnings": ["<string>"],
// Only set if there were info-level annotations while executing the request.
"infos": ["<string>"]
}
Kueri instan
Endpoint berikut mengevaluasi kueri instan pada satu titik waktu:
GET /api/v1/query
POST /api/v1/query
Parameter kueri URL berikut tersedia untuk kueri ekspresi Prometheus:
query=<string>: String kueri ekspresi Prometheus.time=<rfc3339 | unix_timestamp>: Stempel waktu evaluasi opsional, yang ditentukan sebagai string RFC 3339 atau stempel waktu Unix. Jika tidak ada, waktu server saat ini akan digunakan.timeout=<duration>: Waktu tunggu evaluasi opsional. Nilai default-nya adalah dan dibatasi oleh nilai tanda query.timeout.limit=<number>: Jumlah maksimum deret opsional yang akan ditampilkan. Fungsi ini memangkas deret untuk matriks dan vektor, tetapi tidak memengaruhi skalar atau string. Nilai 0 akan menonaktifkan batas ini.lookback_delta=<number>: Parameter opsional untuk mengganti periode lihat kembali khusus untuk kueri ini.
Waktu server saat ini digunakan jika parameter waktu tidak ada.
Untuk kueri yang lebih besar yang mungkin melebihi batas karakter URL, Anda dapat mengirimkan parameter ini menggunakan metode POST. Pastikan isi permintaan dienkode ke URL dan header Content-Type ditetapkan ke application/x-www-form-urlencoded.
Bagian data hasil kueri memiliki format berikut:
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
<value> mengacu pada data hasil kueri, yang memiliki berbagai format bergantung pada resultType.
Contoh berikut mengevaluasi ekspresi up pada waktu 2015-07-01T20:10:51.781Z:
curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
"status" : "success",
"data" : {
"resultType" : "vector",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"value": [ 1435781451.781, "1" ]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9100"
},
"value" : [ 1435781451.781, "0" ]
}
]
}
}
Kueri rentang
Endpoint berikut mengevaluasi kueri ekspresi selama rentang waktu:
GET /api/v1/query_range
POST /api/v1/query_range
Parameter kueri URL berikut tersedia untuk kueri ekspresi Prometheus:
query=<string>: String kueri ekspresi Prometheus.start=<rfc3339 | unix_timestamp>: Stempel waktu awal, inklusif.end=<rfc3339 | unix_timestamp>: Stempel waktu akhir, inklusif.step=<duration | float>: Lebar langkah penyelesaian kueri dalam format durasi atau jumlah detik mengambang.timeout=<duration>: Waktu tunggu evaluasi opsional. Nilai default-nya adalah dan dibatasi oleh nilai tanda query.timeout.limit=<number>: Jumlah maksimum deret opsional yang akan ditampilkan. Fungsi ini memangkas deret untuk matriks dan vektor, tetapi tidak memengaruhi skalar atau string. Nilai 0 akan menonaktifkan batas ini.lookback_delta=<number>: Parameter opsional untuk mengganti periode lihat kembali khusus untuk kueri ini.
Untuk kueri yang lebih besar yang mungkin melebihi batas karakter URL, Anda dapat mengirimkan parameter ini menggunakan metode POST. Pastikan isi permintaan dienkode ke URL dan header Content-Type ditetapkan ke application/x-www-form-urlencoded.
Bagian data hasil kueri memiliki format berikut:
{
"resultType": "matrix",
"result": <value>
}
Contoh berikut mengevaluasi ekspresi up selama rentang 30 detik dengan resolusi kueri 15 detik.
curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
"status" : "success",
"data" : {
"resultType" : "matrix",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"values" : [
[ 1435781430.781, "1" ],
[ 1435781445.781, "1" ],
[ 1435781460.781, "1" ]
]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
"values" : [
[ 1435781430.781, "0" ],
[ 1435781445.781, "0" ],
[ 1435781460.781, "1" ]
]
}
]
}
}
Penamaan Metrik dan Label
Panduan Penamaan Metrik
Saat menentukan nama metrik, pertimbangkan prinsip-prinsip berikut:
Nama metrik HARUS menyertakan awalan aplikasi satu kata, yang terkadang disebut sebagai "namespace" oleh library klien. Awalan ini mengidentifikasi domain yang memiliki metrik. Untuk metrik khusus aplikasi, nama aplikasi biasanya digunakan sebagai awalan.
Contoh:
- prometheus_notifications_total (khusus untuk server Prometheus)
- process_cpu_seconds_total (diekspor oleh banyak library klien)
- http_request_duration_seconds (untuk semua permintaan HTTP)
Nama metrik HARUS mewakili satu unit (misalnya, hindari mencampur detik dengan milidetik, atau detik dengan byte).
Nama metrik HARUS menggunakan satuan dasar (misalnya, detik, byte, meter), bukan satuan turunan (misalnya, milidetik, megabyte, kilometer).
Nama metrik HARUS menyertakan akhiran unit jamak. Untuk penghitungan yang terakumulasi, akhiran "total" harus digunakan selain akhiran unit jika berlaku.
Contoh:
- http_request_duration_seconds
- node_memory_usage_bytes
- http_requests_total (untuk jumlah yang terakumulasi tanpa unit)
- process_cpu_seconds_total (untuk jumlah yang terakumulasi dengan satuan)
- foobar_build_info (untuk metrik semu yang memberikan metadata tentang biner yang sedang berjalan)
Nama metrik DAPAT mengurutkan komponennya untuk memfasilitasi pengelompokan yang mudah saat diurutkan secara leksikografis, asalkan semua aturan lainnya diikuti. Metrik terkait sering kali memiliki komponen nama umum yang ditempatkan di awal untuk memastikan metrik tersebut diurutkan bersama.
Contoh:
- prometheus_tsdb_head_truncations_closed_total
- prometheus_tsdb_head_truncations_established_total
- prometheus_tsdb_head_truncations_failed_total
- prometheus_tsdb_head_truncations_total
Nama metrik HARUS secara konsisten merepresentasikan "hal yang diukur" yang sama secara logis di semua dimensi label.
Contoh:
- durasi permintaan
- byte transfer data
- penggunaan resource instan sebagai persentase
Pedoman Penamaan Label
Saat mengukur sesuatu, gunakan label untuk membedakan karakteristiknya. Contoh:
- Untuk total permintaan HTTP API (
api_http_requests_total), bedakan menurut jenis operasi, misalnyacreate,update,delete(jenis permintaan:operation="create|update|delete"). - Untuk durasi permintaan API dalam detik (
api_request_duration_seconds), bedakan menurut tahap permintaan, misalnyaextract,transform,load(tahap permintaan:stage="extract|transform|load").
Hindari menyertakan nama label dalam nama metrik itu sendiri, karena hal ini menciptakan redundansi dan dapat menyebabkan kebingungan jika label tersebut digabungkan nanti.