PromQL untuk Cloud Monitoring

Dokumen ini menjelaskan penggunaan Prometheus Query Language (PromQL) di Cloud Monitoring. PromQL menyediakan alternatif untuk antarmuka berbasis menu Metrics Explorer dalam membuat diagram dan dasbor.

Anda dapat menggunakan PromQL untuk membuat kueri dan memetakan data Cloud Monitoring dari sumber berikut:

Anda juga dapat menggunakan alat seperti Grafana untuk memetakan data metrik yang dimasukkan ke dalam Cloud Monitoring. Metrik yang tersedia mencakup metrik dari Managed Service for Prometheus dan metrik Cloud Monitoring yang didokumentasikan dalam daftar metrik. Untuk mengetahui informasi tentang cara menyiapkan Grafana dan alat lain berdasarkan Prometheus API, lihat dokumentasi Managed Service for Prometheus tentang Grafana.

Anda juga dapat mengimpor dasbor Grafana ke Cloud Monitoring.

Membuat kueri metrik Cloud Monitoring menggunakan PromQL

Metrik Cloud Monitoring dapat dikueri menggunakan spesifikasi UTF-8 untuk PromQL. Nama metrik UTF-8 harus diapit tanda kutip dan dipindahkan ke dalam tanda kurung kurawal. Nama label juga harus diapit tanda petik jika berisi karakter yang tidak kompatibel dengan versi lama. Untuk metrik Cloud Monitoring kubernetes.io/container/cpu/limit_utilization, kueri berikut setara:

  • {"kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}
  • {__name__="kubernetes.io/container/cpu/limit_utilization", pod_name="foo"}.
  • {"__name__"="kubernetes.io/container/cpu/limit_utilization", "pod_name"="foo"}.

Metrik bernilai distribusi Cloud Monitoring dapat dikueri seperti histogram Prometheus, dengan akhiran _count, _sum, atau _bucket ditambahkan ke nama metrik.

Anda dapat menggunakan label metadata di PromQL seperti label lainnya, tetapi seperti nama metrik, label metadata juga harus dibuat agar kompatibel dengan PromQL. Sintaksis untuk merujuk ke label sistem metadata version adalah metadata_system_version, dan sintaksis untuk label pengguna metadata version adalah metadata_user_version. Kueri PromQL yang disusun dengan baik menggunakan label metadata mungkin terlihat seperti berikut:

  • {"compute.googleapis.com/instance/cpu/utilization", monitored_resource="gce_instance",metadata_user_env="prod"}
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_system_region)
  • sum("compute.googleapis.com/instance/cpu/utilization") by (metadata_user_env)
  • {"compute.googleapis.com/instance/uptime_total", "metadata_user_i-love.special/chars"="yes"}
  • sum("compute.googleapis.com/instance/uptime_total") by ("metadata_user_i-love.special/chars")

Jika kunci label metadata Anda berisi karakter khusus selain karakter _, Anda harus menyertakan kunci label dalam tanda petik ganda (") sesuai dengan spesifikasi UTF-8 PromQL. Anda tetap harus menambahkan awalan pada label metadata dengan string metadata_user_.

Diagram dan dasbor yang dibuat sebelum kueri kompatibilitas UTF-8 Cloud Monitoring menggunakan metrik dengan mengonversi namanya menjadi yang setara dan kompatibel dengan PromQL lama. Untuk mengetahui informasi selengkapnya tentang aturan konversi PromQL lama, lihat Memetakan metrik Cloud Monitoring ke PromQL lama.

Mengakses PromQL di Cloud Monitoring

Anda dapat menggunakan PromQL dari tab Code di halaman berikut di konsol Google Cloud :

  • Metrics Explorer
  • Tambahkan Diagram saat membuat dasbor kustom

Untuk informasi tentang cara mengakses dan menggunakan editor, lihat Menggunakan editor PromQL.

Aturan dan pemberitahuan PromQL

Anda dapat menggunakan PromQL untuk membuat kebijakan pemberitahuan untuk metrik apa pun di Cloud Monitoring. Untuk mengetahui informasi selengkapnya, lihat Kebijakan pemberitahuan berbasis PromQL.

Anda juga dapat menggunakan PromQL untuk membuat aturan perekaman dan pemberitahuan pada metrik apa pun di Cloud Monitoring dengan menggunakan pemberitahuan dalam cluster gaya Prometheus di Cloud Monitoring. Untuk mengetahui informasi selengkapnya, lihat Pemberitahuan dan evaluasi aturan terkelola atau Pemberitahuan dan evaluasi aturan yang di-deploy sendiri.

Mempelajari PromQL

Untuk mempelajari dasar-dasar penggunaan PromQL, sebaiknya lihat dokumentasi open source. Referensi berikut dapat membantu Anda memulai:

Menentukan jenis resource yang dimonitor

Jika metrik Cloud Monitoring hanya dikaitkan dengan satu jenis resource yang dipantau Cloud Monitoring, kueri PromQL akan berfungsi tanpa perlu menentukan jenis resource secara manual. Namun, beberapa metrik dalam Cloud Monitoring, termasuk beberapa metrik sistem dan banyak metrik yang dihasilkan oleh metrik berbasis log, dipetakan ke lebih dari satu jenis resource. Jika Anda menggunakan salah satu metrik ini, terutama metrik berbasis log, Anda harus menentukan jenis resource secara eksplisit.

Anda dapat melihat jenis resource yang dipantau yang dipetakan ke metrik dengan melakukan salah satu tindakan berikut:

  • Untuk metrik yang dikurasi Google, Anda dapat melihat daftar metrik yang tersedia, termasuk metrikGoogle Cloud dan metrik Kubernetes. Setiap entri dalam dokumentasi mencantumkan jenis resource yang dimonitor terkait di kolom pertama setiap entri di bawah jenis. Jika tidak ada jenis resource yang dimonitor yang tercantum, metrik dapat dikaitkan dengan jenis apa pun.

  • Di Metrics Explorer, Anda dapat melakukan hal berikut:

    1. Masukkan nama metrik Anda di kolom Pilih metrik, lalu pilih metrik dengan menjelajahi menu. Menu resource mencantumkan jenis resource yang valid untuk metrik tersebut, misalnya, "Instance VM".

    2. Di toolbar panel pembuat kueri, pilih tombol yang namanya adalah < > PromQL.

      Kueri PromQL yang ditampilkan menunjukkan jenis resource sebagai nilai kolom monitored_resource. Khususnya, metode ini berguna untuk metrik yang dapat dikaitkan dengan banyak jenis resource yang dipantau, misalnya metrik berbasis log, metrik kustom, atau metrik yang ditentukan pengguna.

Jika metrik dikaitkan dengan lebih dari satu jenis resource, Anda harus menentukan jenis resource dalam kueri PromQL. Ada label khusus, monitored_resource, yang dapat Anda gunakan untuk memilih jenis resource.

Jenis resource yang dipantau sebagian besar berupa string pendek, seperti gce_instance, tetapi terkadang muncul sebagai URI lengkap, seperti monitoring.googleapis.com/MetricIngestionAttribution. Kueri PromQL yang disusun dengan benar mungkin terlihat seperti berikut:

  • logging_googleapis_com:byte_count{monitored_resource="k8s_container"}
  • custom_googleapis_com:opencensus_opencensus_io_http_server_request_count_by_method{monitored_resource="global"}
  • loadbalancing_googleapis_com:l3_external_egress_bytes_count{monitored_resource="loadbalancing.googleapis.com/ExternalNetworkLoadBalancerRule"}

Nilai "" untuk label monitored_resource bersifat khusus dan merujuk ke jenis resource prometheus_target default yang digunakan untuk metrik Cloud Monitoring.

Jika Anda tidak menggunakan label monitored_resource saat diperlukan, Anda akan menerima error berikut:

metric is configured to be used with more than one monitored resource type; series selector must specify a label matcher on monitored resource name

Menyelesaikan konflik label

Di Cloud Monitoring, label dapat termasuk dalam metrik atau resource. Jika label metrik memiliki nama kunci yang sama dengan label resource, Anda dapat merujuk ke label metrik secara khusus dengan menambahkan awalan metric_ ke nama kunci label dalam kueri Anda.

Misalnya, anggaplah Anda memiliki label resource dan label metrik yang keduanya bernama pod_name dalam metrik example.googleapis.com/user/widget_count.

  • Untuk memfilter nilai label resource, gunakan
    example_googleapis_com:user_widget_count{pod_name="RESOURCE_LABEL_VALUE"}

  • Untuk memfilter nilai label metrik, gunakan
    example_googleapis_com:user_widget_count{metric_pod_name="METRIC_LABEL_VALUE"}

Memetakan nama metrik Cloud Monitoring ke PromQL lama

Nama metrik Cloud Monitoring mencakup dua komponen, yaitu domain (seperti compute.googleapis.com/) dan jalur (seperti instance/disk/max_read_ops_count). Karena PromQL lama hanya mendukung karakter khusus : dan _, Anda harus menerapkan aturan berikut agar nama metrik Monitoring kompatibel dengan PromQL lama:

  • Ganti / pertama dengan :.
  • Ganti semua karakter khusus lainnya (termasuk . dan karakter / lainnya) dengan _.

Tabel berikut mencantumkan beberapa nama metrik dan PromQL lama yang setara:

Nama metrik Cloud Monitoring Nama metrik PromQL lama
kubernetes.io/container/cpu/limit_cores kubernetes_io:container_cpu_limit_cores
compute.googleapis.com/instance/cpu/utilization compute_googleapis_com:instance_cpu_utilization
logging.googleapis.com/log_entry_count logging_googleapis_com:log_entry_count
custom.googleapis.com/opencensus/opencensus.io/
http/server/request_count_by_method		 custom_googleapis_com:opencensus_opencensus_io_
http_server_request_count_by_method
agent.googleapis.com/disk/io_time agent_googleapis_com:disk_io_time

Metrik bernilai distribusi Cloud Monitoring dapat dikueri seperti histogram Prometheus, dengan akhiran _count, _sum, atau _bucket ditambahkan ke nama metrik:

Nama metrik Cloud Monitoring Nama metrik PromQL lama
networking.googleapis.com/vm_flow/rtt networking_googleapis_com:vm_flow_rtt_sum
networking_googleapis_com:vm_flow_rtt_count
networking_googleapis_com:vm_flow_rtt_bucket

Kompatibilitas PromQL

PromQL untuk Cloud Monitoring mungkin berfungsi sedikit berbeda dengan PromQL upstream.

Kueri PromQL di Cloud Monitoring dievaluasi sebagian di backend Monarch menggunakan bahasa kueri internal, dan ada beberapa perbedaan yang diketahui dalam hasil kueri. Selain perbedaan yang tercantum di bagian ini, PromQL di Cloud Monitoring setara dengan PromQL yang tersedia di Prometheus versi 2.44.

Fungsi PromQL yang ditambahkan setelah Prometheus versi 2.44 mungkin tidak didukung.

Dukungan UTF-8

PromQL untuk Cloud Monitoring mendukung kueri UTF-8.

Jika nama metrik Prometheus Anda hanya terdiri dari karakter alfanumerik ditambah karakter _ atau :, dan jika kunci label Anda hanya terdiri dari karakter alfanumerik ditambah karakter _, Anda dapat membuat kueri menggunakan sintaksis PromQL tradisional. Misalnya, kueri yang valid mungkin terlihat seperti job:my_metric:sum{label_key="label_value"}.

Namun, jika nama metrik Prometheus Anda menggunakan karakter khusus kecuali karakter _ atau :, atau jika kunci label Anda menggunakan karakter khusus kecuali karakter _, maka Anda harus membuat kueri sesuai dengan spesifikasi UTF-8 untuk PromQL.

Nama metrik UTF-8 harus diapit tanda petik dan dipindahkan ke dalam tanda kurung. Nama label juga harus diapit tanda petik jika berisi karakter yang tidak kompatibel dengan versi lama. Contoh kueri valid berikut semuanya setara:

  • {"my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {__name__="my.domain.com/metric/name_bucket", "label.key"="label.value"}
  • {"__name__"="my.domain.com/metric/name_bucket", "label.key"="label.value"}

Mencocokkan nama metrik

Hanya pencocokan persis pada nama metrik yang didukung. Anda harus menyertakan kecocokan persis pada nama metrik dalam kueri Anda.

Sebaiknya gunakan solusi berikut untuk skenario umum yang menggunakan pencocokan ekspresi reguler pada label __name__:

  • Konfigurasi adaptor Prometheus sering menggunakan operator =~ untuk mencocokkan beberapa nama metrik. Untuk memperbaiki penggunaan ini, perluas konfigurasi untuk menggunakan kebijakan terpisah untuk setiap metrik dan beri nama setiap metrik secara eksplisit. Hal ini juga mencegah Anda melakukan penskalaan otomatis secara tidak sengaja pada metrik yang tidak terduga.
  • Ekspresi reguler sering digunakan untuk membuat grafik beberapa metrik non-dimensi pada diagram yang sama. Misalnya, jika Anda memiliki metrik seperti cpu_servicename_usage, Anda dapat menggunakan karakter pengganti untuk membuat grafik semua layanan Anda secara bersamaan. Menggunakan metrik non-dimensi seperti ini adalah praktik yang sangat buruk di Cloud Monitoring, dan praktik ini menyebabkan performa kueri yang sangat buruk. Untuk memperbaiki penggunaan ini, pindahkan semua dimensi ke dalam label metrik, bukan menyematkan dimensi dalam nama metrik.
  • Kueri untuk beberapa metrik sering digunakan untuk melihat metrik yang tersedia untuk dikueri. Sebaiknya gunakan panggilan /labels/__name__/values untuk menemukan metrik. Anda juga dapat menemukan metrik menggunakan UI Cloud Monitoring.
  • Mencocokkan beberapa metrik berguna untuk melihat berapa banyak sampel yang di-scraping, diserap, dan ditagih berdasarkan per metrik. Cloud Monitoring memberikan informasi ini kepada Anda di halaman Pengelolaan Metrik. Anda juga dapat mengakses informasi ini sebagai data metrik menggunakan metrik Sampel yang Di-Ingest atau metrik Sampel yang Ditulis oleh ID Atribusi.

Tidak berlaku

Keterlambatan tidak didukung di backend Monarch.

Penghitungan irate

Jika periode lihat balik untuk fungsi irate kurang dari ukuran langkah, kami akan memperbesar periode menjadi ukuran langkah. Monarch memerlukan perubahan ini untuk memastikan bahwa tidak ada data input yang sepenuhnya diabaikan dalam output. Perbedaan ini juga berlaku untuk penghitungan rate.

Penghitungan rate dan increase

Jika periode lihat balik untuk fungsi rate kurang dari ukuran langkah, kami akan memperbesar periode menjadi ukuran langkah. Monarch memerlukan perubahan ini untuk memastikan bahwa tidak ada data input yang diabaikan sepenuhnya dalam output. Perbedaan ini juga berlaku untuk penghitungan irate.

Ada perbedaan dalam penghitungan interpolasi dan ekstrapolasi. Monarch menggunakan algoritma interpolasi yang berbeda dengan Prometheus, dan perbedaan ini dapat menyebabkan hasil yang sedikit berbeda. Misalnya, sampel penghitung Monarch disimpan dengan rentang waktu, bukan stempel waktu tunggal yang digunakan Prometheus. Oleh karena itu, contoh penghitung di Monarch dapat disertakan dalam penghitungan rasio meskipun stempel waktu Prometheus akan mengecualikannya. Hal ini umumnya menghasilkan hasil tarif yang lebih akurat, terutama saat membuat kueri di awal atau akhir deret waktu pokok.

Penghitungan histogram_quantile

Penghitungan histogram_quantile PromQL pada histogram tanpa sampel menghasilkan nilai NaN. Penghitungan bahasa kueri internal tidak menghasilkan nilai; titik pada stempel waktu akan dihilangkan.

Perbedaan perhitungan tarif juga dapat memengaruhi input ke kueri histogram_quantile.

Fungsi khusus jenis pada metrik dengan jenis yang berbeda

Meskipun Prometheus upstream diketik secara lemah, Monarch diketik secara kuat. Artinya, menjalankan fungsi khusus untuk satu jenis pada metrik dengan jenis yang berbeda (misalnya, menjalankan rate() pada metrik GAUGE atau histogram_quantile() pada metrik COUNTER atau metrik tanpa jenis) tidak berfungsi di Cloud Monitoring, meskipun fungsi ini berfungsi di Prometheus upstream.