Membuat kebijakan pemberitahuan berbasis PromQL (API)

Halaman ini menjelaskan cara membuat kebijakan pemberitahuan berbasis PromQL menggunakan Cloud Monitoring API. Anda dapat menggunakan kueri PromQL dalam kebijakan pemberitahuan untuk membuat kondisi kompleks dengan fitur seperti rasio, batas dinamis, dan evaluasi metrik.

Untuk mengetahui informasi umum, lihat Ringkasan pemberitahuan berbasis PromQL.

Jika Anda bekerja di lingkungan Prometheus di luar Cloud Monitoring dan memiliki aturan pemberitahuan Prometheus, Anda dapat menggunakan Google Cloud CLI untuk memigrasikannya ke kebijakan pemberitahuan berbasis PromQL di Monitoring. Untuk mengetahui informasi selengkapnya, lihat Memigrasikan aturan pemberitahuan dan penerima dari Prometheus.

Membuat kebijakan pemberitahuan dengan kueri PromQL

Anda menggunakan metode alertPolicies.create untuk membuat kebijakan pemberitahuan secara terprogram.

Satu-satunya perbedaan antara pembuatan kebijakan pemberitahuan berbasis PromQL dan kebijakan pemberitahuan lainnya adalah jenis Condition Anda harus berupa PrometheusQueryLanguageCondition. Jenis kondisi ini memungkinkan kebijakan pemberitahuan ditentukan dengan PromQL.

Berikut ini menunjukkan kueri PromQL untuk kondisi kebijakan pemberitahuan yang menggunakan metrik dari eksportir kube-state untuk menemukan jumlah waktu saat penampung telah dimulai ulang dalam 30 menit terakhir:

rate(kube_pod_container_status_restarts[30m]) * 1800 > 1

Membuat kebijakan pemberitahuan

Untuk membuat kebijakan pemberitahuan berbasis PromQL, gunakan AlertPolicy jenis kondisi PrometheusQueryLanguageCondition. PrometheusQueryLanguageCondition memiliki struktur berikut:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "alertRule": string
}

Catatan: Kebijakan pemberitahuan yang menggunakan PromQL hanya boleh memiliki satu kondisi. Kebijakan dengan beberapa kondisi tidak didukung jika suatu kondisi menggunakan PromQL. Namun, Anda dapat mereferensikan beberapa metrik dalam satu kondisi PromQL dan mengevaluasinya bersama-sama dengan menggunakan operator +.

Kolom PrometheusQueryLanguageCondition memiliki definisi berikut:

• query: Ekspresi PromQL yang akan dievaluasi. Setara dengan kolom expr dari aturan pemberitahuan Prometheus standar.
• duration: Menentukan durasi waktu selama setiap evaluasi kueri harus menghasilkan nilai true sebelum kondisi kebijakan pemberitahuan terpenuhi. Nilai harus berupa jumlah menit, yang dinyatakan dalam detik; misalnya, 600s untuk durasi 10 menit. Untuk mengetahui informasi selengkapnya, lihat Perilaku kebijakan pemberitahuan berbasis metrik.

• evaluationInterval: Interval waktu, dalam detik, antara evaluasi PromQL kueri. Nilai default-nya adalah 30 detik. Jika PrometheusQueryLanguageCondition dibuat dengan memigrasikan aturan pemberitahuan Prometheus, nilai ini berasal dari grup aturan Prometheus yang berisi aturan pemberitahuan Prometheus.

  Catatan: Insiden yang dibuat oleh kebijakan pemberitahuan berbasis PromQL tidak mengikuti durasi penutupan otomatis kebijakan pemberitahuan. Sebaliknya, insiden akan otomatis ditutup saat mencapai waktu yang ditetapkan setelah terakhir kali kondisi terpenuhi. Waktu ini adalah yang lebih besar dari 270 detik dan dua kali interval evaluasi kondisi.

• labels: Cara opsional untuk menambahkan atau menimpa label dalam hasil ekspresi PromQL.

• ruleGroup: Jika kebijakan pemberitahuan dimigrasikan dari file konfigurasi Prometheus, kolom ini akan berisi nilai kolom name dari grup aturan dalam file konfigurasi Prometheus. Kolom ini tidak diperlukan saat Anda membuat kebijakan pemberitahuan PromQL di Cloud Monitoring API.

• alertRule: Jika kebijakan pemberitahuan dimigrasikan dari file konfigurasi Prometheus, kolom ini berisi nilai kolom alert dari aturan pemberitahuan dalam file konfigurasi Prometheus. Kolom ini tidak diperlukan saat Anda membuat kebijakan pemberitahuan PromQL di Cloud Monitoring API.

Misalnya, kondisi berikut menggunakan kueri PromQL untuk menemukan jumlah waktu saat penampung telah dimulai ulang dalam 30 menit terakhir:

"conditionPrometheusQueryLanguage": {
  "query": "rate(kube_pod_container_status_restarts[30m]) * 1800 > 1",
  "duration": "600s",
  evaluationInterval: "60s",
  "alertRule": "ContainerRestartCount",
  "labels": {
    "action_required":"true",
    "severity":"critical/warning/info"}
}

Gunakan struktur ini sebagai nilai kolom conditionPrometheusQueryLanguage dalam kondisi, yang selanjutnya disematkan dalam struktur kebijakan pemberitahuan. Untuk mengetahui informasi selengkapnya tentang struktur ini, lihat AlertPolicy.

Berikut adalah kebijakan lengkap dengan kondisi PrometheusQueryLanguageCondition dalam JSON:

Catatan: Kolom documentation dalam contoh berikut menggunakan variabel dokumen.

{
  "displayName": "Container Restarts",
  "documentation": {
    "content": "Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes.",
    "mimeType": "text/markdown",
    "subject": "Container ${resource.label.container_name} in Pod ${resource.label.namespace_name}/${resource.label.pod_name} has restarted more than once during the last 30 minutes."
  },
  "userLabels": {},
  "conditions": [
    {
      "displayName": "Container has restarted",
      "conditionPrometheusQueryLanguage": {
        "query": "rate(kubernetes_io:container_restart_count[30m]) * 1800",
        "duration": "600s",
        evaluationInterval: "60s",
        "alertRule": "ContainerRestart",
        "labels": {
          "action_required":"true",
          "severity":"critical/warning/info"}
      }
    }
  ],
  "combiner": "OR",
  "enabled": true
}

Membuat kebijakan pemberitahuan

Untuk membuat kebijakan pemberitahuan, masukkan JSON kebijakan pemberitahuan ke dalam file bernama POLICY_NAME.json, lalu jalankan perintah berikut:

curl -d @POLICY_NAME.json -H "Authorization: Bearer $TOKEN"
-H 'Content-Type: application/json'
-X POST https://monitoring.googleapis.com/v3/projects/${PROJECT}/alertPolicies

Untuk mengetahui informasi selengkapnya tentang Monitoring API untuk kebijakan pemberitahuan, lihat Mengelola kebijakan pemberitahuan dengan API.

Untuk mengetahui informasi selengkapnya tentang penggunaan curl, lihat Memanggil curl.

Menonaktifkan pemeriksaan keberadaan metrik

Saat Anda membuat kebijakan pemberitahuan berbasis PromQL, Google Cloud menjalankan validasi untuk memastikan bahwa metrik yang dirujuk dalam kondisi sudah ada di Monitoring. Namun, Anda dapat mengganti validasi ini jika perlu membuat kebijakan pemberitahuan sebelum metrik ada. Misalnya, Anda mungkin ingin melakukannya saat menggunakan otomatisasi untuk membuat project baru yang dilengkapi dengan serangkaian kebijakan pemberitahuan standar yang telah ditentukan sebelumnya. Jika Anda tidak menonaktifkan validasi, pembuatan kebijakan pemberitahuan akan gagal hingga metrik pokok dibuat.

Untuk menonaktifkan pemeriksaan keberadaan metrik, tambahkan kolom "disableMetricValidation": true ke PrometheusQueryLanguageCondition Anda:

{
  "query": string,
  "duration": string,
  "evaluationInterval": string,
  "labels": {string: string},
  "ruleGroup": string,
  "disableMetricValidation": true,
  "alertRule": string
}

Jika kondisi kebijakan pemberitahuan merujuk ke metrik yang tidak ada, maka kondisi tersebut tetap berjalan sesuai dengan interval evaluasinya. Namun, hasil kueri selalu kosong. Setelah metrik pokok ada, kueri akan menampilkan data.

Catatan: Pengguna yang dapat melihat kebijakan pemberitahuan dapat melihat nama metrik yang tidak ada dalam kondisi kebijakan pemberitahuan.

Menggunakan Terraform

Untuk mengetahui petunjuk tentang cara mengonfigurasi kebijakan pemberitahuan berbasis PromQL menggunakan Terraform, lihat bagian condition_prometheus_query_language di google_monitoring_alert_policy Terraform Registry.

Untuk informasi umum tentang penggunaan Google Cloud dengan Terraform, lihat Terraform dengan Google Cloud.

Memanggil curl

Setiap pemanggilan curl mencakup serangkaian argumen, diikuti dengan URL resource API. Argumen umum mencakup ID project Google Cloud dan token autentikasi. Nilai ini diwakili di sini oleh variabel lingkungan PROJECT_ID dan TOKEN.

Anda mungkin juga harus menentukan argumen lain, misalnya, untuk menentukan jenis permintaan HTTP (misalnya, -X DELETE). Permintaan default adalah GET, jadi contoh tidak menentukannya.

Setiap pemanggilan curl memiliki struktur umum berikut:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Untuk menggunakan curl, Anda harus menentukan project ID dan token akses. Untuk mengurangi pengetikan dan error, Anda dapat memasukkan nilai ini ke dalam variabel lingkungan atau meneruskannya ke curl dengan cara tersebut.

Untuk menetapkan variabel ini, lakukan hal berikut:

1. Buat variabel lingkungan untuk menyimpan ID project pencakupan cakupan metrik Anda. Langkah-langkah ini memanggil variabel PROJECT_ID:

   PROJECT_ID=a-sample-project
   

2. Lakukan autentikasi ke Google Cloud CLI:

   gcloud auth login
   

3. Opsional. Agar tidak perlu menentukan project ID dengan setiap perintah gcloud, tetapkan project ID Anda sebagai default menggunakan gcloud CLI:

   gcloud config set project ${PROJECT_ID}
   

4. Buat token otorisasi dan ambil di variabel lingkungan. Langkah-langkah ini memanggil variabel TOKEN:

   TOKEN=`gcloud auth print-access-token`
   

   Anda harus memperbarui token akses secara berkala. Jika perintah yang berfungsi tiba-tiba melaporkan bahwa Anda tidak diautentikasi, terbitkan kembali perintah ini.

5. Untuk memverifikasi bahwa Anda mendapatkan token akses, tampilkan variabel TOKEN:

   echo ${TOKEN}
   ya29.GluiBj8o....