Kebijakan pemberitahuan direpresentasikan dalam Cloud Monitoring API melalui objek AlertPolicy
, yang menjelaskan serangkaian kondisi yang menunjukkan status berpotensi tidak responsif di sistem Anda.
Dokumen ini menjelaskan hal berikut:
- Cara Monitoring API menampilkan kebijakan pemberitahuan.
- Jenis kondisi yang disediakan Monitoring API untuk kebijakan pemberitahuan.
- Cara membuat kebijakan pemberitahuan menggunakan Google Cloud CLI atau library klien.
Struktur kebijakan pemberitahuan
Struktur AlertPolicy
menentukan komponen kebijakan pemberitahuan. Saat membuat kebijakan, Anda menentukan nilai untuk kolom AlertPolicy
berikut:
displayName
: Label deskriptif untuk kebijakan.documentation
: Informasi apa pun yang diberikan untuk membantu responden. Kolom ini bersifat opsional. Objekdocumentation
mencakup hal berikut:content
: Teks yang ditentukan pengguna, yang muncul di isi notifikasi.subject
: Baris subjek notifikasi. Baris subjek dibatasi hingga 255 karakter.
userLabels
: Label buatan pengguna yang dilampirkan pada kebijakan. Untuk mengetahui informasi tentang penggunaan label dengan pemberitahuan, lihat Menganotasi pemberitahuan dengan label.conditions[]
: Array strukturCondition
.combiner
: Operator logika yang menentukan cara menangani beberapa kondisi.notificationChannels[]
: array nama resource, yang masing-masing mengidentifikasiNotificationChannel
.alertStrategy
: Menentukan seberapa cepat Monitoring menutup insiden saat data berhenti tiba. Objek ini juga menentukan apakah notifikasi berulang diaktifkan untuk pemberitahuan berbasis metrik, dan interval antar-notifikasi tersebut. Untuk informasi selengkapnya, lihat Mengirim notifikasi berulang.
Anda juga dapat menentukan kolom severity
saat menggunakan Cloud Monitoring API dan Konsol Google Cloud. Kolom ini memungkinkan Anda menentukan tingkat keparahan insiden. Jika Anda tidak menetapkan tingkat keparahan, Cloud Monitoring akan menetapkan tingkat keparahan kebijakan pemberitahuan ke No Severity
.
Ada kolom lain yang dapat Anda gunakan, bergantung pada kondisi yang Anda buat.
Jika kebijakan pemberitahuan berisi satu kondisi, notifikasi akan dikirim saat kondisi tersebut terpenuhi. Untuk informasi tentang notifikasi saat kebijakan pemberitahuan mengandung beberapa ketentuan, lihat Kebijakan dengan beberapa kondisi dan Jumlah notifikasi per kebijakan.
Saat Anda membuat atau mengubah kebijakan pemberitahuan, Monitoring juga akan menetapkan kolom lainnya, termasuk kolom name
. Nilai kolom name
adalah nama resource untuk kebijakan pemberitahuan, yang mengidentifikasi
kebijakan. Nama resource memiliki bentuk berikut:
projects/PROJECT_ID/alertPolicies/POLICY_ID
Jenis kondisi pada API
Cloud Monitoring API mendukung berbagai jenis kondisi dalam struktur Condition
. Ada beberapa jenis kondisi untuk kebijakan pemberitahuan berbasis metrik, dan satu kondisi untuk kebijakan pemberitahuan berbasis log. Bagian berikut menjelaskan jenis kondisi yang tersedia.
Ketentuan untuk kebijakan pemberitahuan berbasis metrik
Untuk membuat kebijakan pemberitahuan yang memantau data metrik, termasuk metrik berbasis log, Anda dapat menggunakan jenis kondisi berikut:
Kondisi metrik berbasis filter
Kondisi MetricAbsence
dan MetricThreshold
menggunakan filter Monitoring untuk memilih data deret waktu yang akan dipantau. Kolom lain dalam struktur kondisi menentukan cara memfilter,
mengelompokkan, dan menggabungkan data. Untuk informasi selengkapnya tentang konsep ini, lihat
Pemfilteran dan agregasi: memanipulasi deret waktu.
Jika menggunakan jenis kondisi MetricAbsence
, Anda dapat membuat kondisi
yang akan terpenuhi hanya jika semua deret waktu tidak ada. Kondisi ini menggunakan parameter aggregations
untuk menggabungkan beberapa deret waktu menjadi satu deret waktu. Untuk informasi selengkapnya, lihat
referensi MetricAbsence
dalam dokumentasi API.
Kebijakan pemberitahuan tidak ada metrik mengharuskan beberapa data telah ditulis sebelumnya; untuk informasi selengkapnya, lihat Membuat kebijakan pemberitahuan tidak ada metrik.
Jika Anda ingin mendapatkan notifikasi berdasarkan nilai yang diperkirakan, konfigurasikan kebijakan pemberitahuan untuk menggunakan jenis kondisi MetricThreshold
dan menetapkan kolom forecastOptions
. Jika
kolom ini tidak ditetapkan, data yang diukur akan dibandingkan dengan nilai minimum.
Namun, jika kolom ini ditetapkan, data yang diprediksi akan dibandingkan dengan nilai minimum. Untuk mengetahui informasi selengkapnya, lihat artikel Membuat kebijakan pemberitahuan nilai metrik yang diperkirakan.
Kondisi metrik berbasis MQL
Kondisi MonitoringQueryLanguageCondition
menggunakan Bahasa Kueri Monitoring (MQL) untuk memilih dan memanipulasi data deret waktu yang akan dipantau. Anda dapat membuat kebijakan pemberitahuan yang membandingkan nilai dengan nilai minimum atau menguji tidak adanya nilai dengan jenis kondisi ini.
Jika Anda menggunakan kondisi MonitoringQueryLanguageCondition
, kondisi tersebut harus menjadi satu-satunya kondisi dalam kebijakan pemberitahuan Anda. Untuk mengetahui informasi selengkapnya, lihat Kebijakan pemberitahuan dengan MQL.
Kondisi metrik berbasis PromQL
Kondisi PrometheusQueryLanguageCondition
menggunakan kueri Prometheus Query Language (PromQL) untuk memilih dan memanipulasi data deret waktu yang akan dipantau. Anda dapat membuat kueri sederhana atau kompleks dan menggunakan struktur kueri seperti nilai minimum dinamis, rasio, perbandingan metrik, dan lainnya.
Jika Anda menggunakan kondisi PrometheusQueryLanguageCondition
, kondisi tersebut harus menjadi satu-satunya kondisi dalam kebijakan pemberitahuan Anda. Untuk mengetahui informasi selengkapnya, baca Kebijakan pemberitahuan dengan PromQL.
Ketentuan untuk pemberitahuan rasio
Anda dapat membuat kebijakan pemberitahuan batas metrik untuk memantau rasio dua metrik. Anda dapat membuat kebijakan ini menggunakan jenis kondisi MetricThreshold
atau MonitoringQueryLanguageCondition
.
Anda juga dapat menggunakan MQL secara langsung di Konsol Google Cloud. Anda tidak dapat membuat
atau mengelola kondisi berbasis rasio menggunakan antarmuka grafis untuk membuat
kondisi nilai minimum.
Sebaiknya gunakan MQL untuk membuat kebijakan pemberitahuan berbasis rasio.
MQL memungkinkan Anda mem-build kueri yang lebih andal dan fleksibel daripada yang dapat Anda buat menggunakan jenis kondisi MetricTheshold
dan filter Pemantauan.
Misalnya, dengan kondisi MonitoringQueryLanguageCondition
, Anda dapat menghitung rasio metrik pengukur terhadap metrik delta. Misalnya, lihat contoh kebijakan pemberitahuan MQL.
Jika Anda menggunakan kondisi MetricThreshold
, pembilang dan penyebut rasio harus memiliki MetricKind
yang sama.
Untuk daftar metrik dan propertinya, lihat Daftar metrik.
Secara umum, cara terbaik adalah menghitung rasio berdasarkan deret waktu yang dikumpulkan untuk satu jenis metrik, dengan menggunakan nilai label. Rasio yang dihitung dengan dua jenis metrik yang berbeda dapat mengalami anomali karena periode pengambilan sampel dan periode penyelarasan yang berbeda.
Misalnya, Anda memiliki dua jenis metrik yang berbeda, jumlah total RPC dan jumlah error RPC, dan Anda ingin menghitung rasio RPC jumlah error dibandingkan total RPC. RPC yang gagal dihitung dalam deret waktu dari kedua jenis metrik. Oleh karena itu, ada kemungkinan bahwa, saat Anda menyelaraskan deret waktu, RPC yang gagal tidak akan muncul dalam interval perataan yang sama untuk kedua deret waktu. Perbedaan ini dapat terjadi karena beberapa alasan, termasuk:
- Karena ada dua deret waktu berbeda yang merekam peristiwa yang sama, ada dua nilai penghitung dasar yang mengimplementasikan pengumpulan data tersebut, dan keduanya tidak diperbarui secara atomik.
- Frekuensi sampling mungkin berbeda. Jika deret waktu diselaraskan dengan periode yang sama, jumlah untuk satu peristiwa dapat muncul dalam interval perataan yang berdekatan dalam deret waktu untuk metrik yang berbeda.
Perbedaan jumlah nilai dalam interval perataan yang sesuai dapat
menyebabkan nilai rasio error/total
yang tidak masuk akal seperti 1/0 atau 2/1.
Rasio angka yang lebih besar cenderung tidak menghasilkan nilai yang tidak masuk akal. Anda dapat memperoleh jumlah yang lebih besar melalui agregasi, baik dengan menggunakan periode perataan yang lebih panjang dari periode pengambilan sampel, atau dengan mengelompokkan data untuk label tertentu. Teknik ini meminimalkan efek perbedaan kecil pada jumlah titik pada interval tertentu. Artinya, selisih dua titik akan lebih signifikan jika jumlah titik yang diharapkan dalam sebuah interval adalah 3 daripada saat angka yang diharapkan adalah 300.
Jika menggunakan jenis metrik bawaan, Anda mungkin tidak punya pilihan selain menghitung rasio di seluruh jenis metrik untuk mendapatkan nilai yang dibutuhkan.
Jika Anda mendesain metrik kustom yang mungkin menghitung hal yang sama—seperti RPC yang menampilkan status error—dalam dua metrik berbeda, pertimbangkan satu metrik, yang menyertakan setiap jumlah hanya sekali. Misalnya, anggap Anda menghitung RPC dan ingin melacak rasio RPC yang gagal terhadap semua RPC. Untuk mengatasi masalah ini, buat satu jenis metrik untuk menghitung RPC, dan gunakan label untuk mencatat status pemanggilan, termasuk status "OK". Kemudian, setiap nilai status, error atau "OK", dicatat dengan memperbarui satu penghitung untuk kasus tersebut.
Kondisi untuk kebijakan pemberitahuan berbasis log
Untuk membuat kebijakan pemberitahuan berbasis log, yang memberi tahu Anda saat pesan yang cocok dengan filter muncul di entri log, gunakan jenis kondisi LogMatch
. Jika Anda menggunakan kondisi LogMatch
, kondisi tersebut harus menjadi satu-satunya kondisi dalam kebijakan pemberitahuan Anda.
Jangan mencoba menggunakan jenis kondisi LogMatch
bersama-sama dengan metrik berbasis log. Kebijakan pemberitahuan yang memantau metrik berbasis log adalah kebijakan berbasis metrik. Untuk mengetahui informasi selengkapnya tentang cara memilih antara kebijakan pemberitahuan yang memantau metrik berbasis log atau entri log, lihat Memantau log.
Kebijakan pemberitahuan yang digunakan dalam contoh di dokumen Kelola kebijakan pemberitahuan dengan API adalah kebijakan pemberitahuan berbasis metrik, meskipun prinsipnya sama untuk kebijakan pemberitahuan berbasis log. Untuk mengetahui informasi khusus tentang kebijakan pemberitahuan berbasis log, lihat Membuat pemberitahuan berbasis log menggunakan Monitoring API dalam dokumentasi Cloud Logging.
Sebelum memulai
Sebelum menulis kode terhadap API, Anda harus:
- Pahami konsep dan terminologi umum yang digunakan terkait kebijakan pemberitahuan. Baca Ringkasan pemberitahuan untuk mengetahui informasi selengkapnya.
- Pastikan Cloud Monitoring API diaktifkan untuk digunakan. Baca bagian Mengaktifkan API untuk mengetahui informasi selengkapnya.
- Jika Anda berencana menggunakan library klien, maka instal library untuk bahasa yang ingin Anda gunakan; lihat Library Klien untuk mengetahui detailnya. Saat ini, dukungan API untuk pemberitahuan hanya tersedia untuk C#, Go, Java, Node.js, dan Python.
Jika Anda berencana menggunakan Google Cloud CLI, instal saja. Namun, jika Anda menggunakan Cloud Shell, berarti Google Cloud CLI sudah terinstal.
Contoh penggunaan antarmuka
gcloud
juga disediakan di sini. Perhatikan bahwa semua contohgcloud
mengasumsikan bahwa project saat ini telah ditetapkan sebagai target (gcloud config set project [PROJECT_ID]
), sehingga pemanggilan menghilangkan flag--project
eksplisit. ID project saat ini dalam contoh adalaha-gcp-project
.
-
Untuk mendapatkan izin yang diperlukan untuk membuat dan mengubah kebijakan pemberitahuan menggunakan Cloud Monitoring API, minta administrator untuk memberi Anda peran IAM Monitoring AlertPolicy Editor (
roles/monitoring.alertPolicyEditor
) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
Guna mengetahui informasi mendetail tentang peran IAM untuk Monitoring, lihat Mengontrol akses dengan Identity and Access Management.
Rancang aplikasi Anda ke panggilan Cloud Monitoring API thread tunggal yang mengubah status kebijakan pemberitahuan di project Google Cloud. Misalnya, panggilan API thread tunggal yang membuat, memperbarui, atau menghapus kebijakan pemberitahuan.
Membuat kebijakan pemberitahuan
Untuk membuat kebijakan pemberitahuan dalam sebuah project, gunakan metode alertPolicies.create
. Untuk mengetahui informasi tentang cara memanggil
metode ini, parameternya, dan data respons, lihat halaman referensi
alertPolicies.create
.
Anda dapat membuat kebijakan dari file JSON atau YAML.
Google Cloud CLI menerima file ini sebagai argumen, dan Anda dapat membaca file JSON secara terprogram, mengonversinya menjadi objek AlertPolicy
, serta membuat kebijakan dari file tersebut menggunakan metode alertPolicies.create
. Jika Anda memiliki file konfigurasi JSON atau YAML Prometheus dengan aturan pemberitahuan, gcloud CLI dapat memigrasikannya ke kebijakan pemberitahuan Cloud Monitoring dengan kondisi PromQL. Untuk mengetahui informasi selengkapnya, lihat Memigrasikan aturan dan penerima pemberitahuan dari Prometheus.
Setiap kebijakan pemberitahuan termasuk dalam project pencakupan cakupan metrik. Setiap project dapat berisi hingga 500 kebijakan.
Untuk panggilan API, Anda harus memberikan "project ID"; gunakan ID project pencakupan dalam cakupan metrik sebagai nilai. Dalam contoh ini, ID project pencakupan cakupan metrik adalah a-gcp-project
.
Contoh berikut menggambarkan pembuatan kebijakan pemberitahuan, tetapi tidak menjelaskan cara membuat file JSON atau YAML yang mendeskripsikan kebijakan pemberitahuan. Sebagai gantinya, contoh ini mengasumsikan bahwa file berformat JSON sudah ada dan menggambarkan cara melakukan panggilan API. Untuk contoh file JSON, lihat Kebijakan contoh. Untuk informasi umum tentang pemantauan rasio metrik, lihat Rasio metrik.
gcloud
Untuk membuat kebijakan pemberitahuan di project, gunakan perintah gcloud alpha monitoring
policies create
. Contoh berikut akan membuat kebijakan pemberitahuan di a-gcp-project
dari file rising-cpu-usage.json
:
gcloud alpha monitoring policies create --policy-from-file="rising-cpu-usage.json"
Jika berhasil, perintah ini akan menampilkan nama kebijakan yang baru, misalnya:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
File rising-cpu-usage.json
berisi JSON untuk kebijakan dengan
nama tampilan “Kecepatan perubahan CPU yang tinggi”. Untuk mengetahui detail tentang kebijakan ini, lihat
kebijakan Tarif perubahan.
Lihat referensi
gcloud alpha monitoring policies create
untuk mengetahui informasi selengkapnya.
C#
Untuk mengautentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Go
Untuk mengautentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Untuk mengautentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Untuk mengautentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
PHP
Untuk mengautentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Python
Untuk mengautentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Objek AlertPolicy
yang dibuat akan memiliki kolom tambahan.
Kebijakan itu sendiri akan memiliki kolom
name
, creationRecord
, dan mutationRecord
. Selain itu, setiap kondisi dalam kebijakan juga diberi name
.
Kolom ini tidak dapat diubah secara eksternal, sehingga Anda tidak perlu menetapkannya
saat membuat kebijakan. Contoh JSON yang digunakan untuk membuat kebijakan tidak menyertakannya, tetapi jika kebijakan yang dibuat dari data tersebut diambil setelah dibuat, kolom akan tetap ada.