Cloud Monitoring API dan Google Cloud CLI memungkinkan Anda membuat kebijakan pemberitahuan dari file JSON atau YAML atau menggunakan library klien. Setiap objek AlertPolicy menentukan kondisi berbasis metrik atau berbasis log yang menunjukkan status yang berpotensi tidak responsif dalam sistem Anda, beserta saluran notifikasi dan strategi pemberitahuan.
Saat menggunakan Monitoring API, Anda harus melakukan autentikasi dengan kredensial pengguna akhir, bukan kunci API. Misalnya, Anda dapat memberikan token OAuth 2.0 untuk pengguna atau akun layanan. Untuk mengetahui informasi selengkapnya, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API dan Autentikasi untuk Google Cloud API dan layanan.
Fitur ini hanya didukung untuk project Google Cloud . Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
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: Sebaiknya gunakan kolom ini untuk memberikan informasi yang membantu responden pemberitahuan. Untuk mengetahui informasi selengkapnya, lihat Memberikan anotasi pada notifikasi dengan dokumentasi yang ditentukan pengguna.userLabels: Label apa pun yang ditentukan pengguna yang dilampirkan ke kebijakan. Kebijakan pemberitahuan, pemberitahuan, dan notifikasi menampilkan label ini. Untuk mengetahui informasi tentang cara menggunakan label dengan pemberitahuan, lihat Memberikan anotasi pemberitahuan menggunakan label.conditions[]: Array strukturCondition.combiner: Operator logis yang menentukan cara menangani beberapa kondisi.notificationChannels[]: array nama resource, yang masing-masing mengidentifikasiNotificationChannel.alertStrategy: Menentukan hal berikut:- Seberapa cepat Monitoring menutup pemberitahuan saat data berhenti masuk.
- Untuk kebijakan pemberitahuan berbasis metrik, apakah Monitoring mengirimkan notifikasi saat pemberitahuan ditutup.
- Untuk kebijakan pemberitahuan berbasis metrik, apakah notifikasi berulang diaktifkan, dan interval antara notifikasi tersebut. Untuk mengetahui informasi selengkapnya, lihat Mengonfigurasi notifikasi berulang untuk kebijakan pemberitahuan berbasis metrik.
Anda juga dapat menentukan kolom severity saat menggunakan Cloud Monitoring API dan konsol Google Cloud . Kolom ini memungkinkan Anda menentukan tingkat keparahan pemberitahuan. Jika Anda tidak menentukan tingkat keparahan, Cloud Monitoring akan menetapkan tingkat keparahan kebijakan pemberitahuan ke No Severity.
Ada kolom lain yang mungkin Anda gunakan, bergantung pada kondisi yang Anda buat.
Jika kebijakan pemberitahuan berisi satu kondisi, notifikasi akan dikirim saat kondisi tersebut terpenuhi. Untuk mengetahui informasi tentang notifikasi saat kebijakan pemberitahuan berisi beberapa kondisi, lihat Kebijakan dengan beberapa kondisi dan Kapan Monitoring mengirim notifikasi dan membuat pemberitahuan.
Saat Anda membuat atau mengubah kebijakan pemberitahuan, Monitoring juga menetapkan kolom lain, termasuk kolom name. Nilai kolom name
adalah nama resource untuk kebijakan pemberitahuan, yang mengidentifikasi
kebijakan tersebut. Nama resource memiliki format berikut:
projects/PROJECT_ID/alertPolicies/POLICY_ID
Dalam ekspresi sebelumnya:
- PROJECT_ID: ID project. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
- POLICY_ID: ID kebijakan pemberitahuan
Jenis kondisi di API
Cloud Monitoring API mendukung berbagai jenis kondisi dalam struktur Condition. Ada beberapa jenis kondisi untuk kebijakan pemberitahuan berbasis metrik, dan satu untuk kebijakan pemberitahuan berbasis log. Bagian berikut menjelaskan jenis kondisi yang tersedia.
Kondisi 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 mengetahui informasi selengkapnya tentang konsep ini, lihat Pemfilteran dan agregasi: memanipulasi deret waktu.
Jika menggunakan jenis kondisi MetricAbsence, Anda dapat membuat kondisi yang hanya terpenuhi jika semua deret waktu tidak ada. Kondisi ini menggunakan parameter aggregations untuk menggabungkan beberapa deret waktu menjadi satu deret waktu. Untuk mengetahui informasi selengkapnya, lihat
referensi MetricAbsence dalam dokumentasi API.
Kebijakan pemberitahuan tanpa metrik mengharuskan beberapa data telah ditulis sebelumnya; untuk mengetahui informasi selengkapnya, lihat Membuat kebijakan pemberitahuan tanpa metrik.
Jika Anda ingin mendapatkan notifikasi berdasarkan nilai perkiraan, konfigurasikan
kebijakan pemberitahuan Anda untuk menggunakan
jenis kondisi MetricThreshold dan untuk 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
Membuat kebijakan pemberitahuan nilai metrik yang diperkirakan.
Kondisi metrik berbasis PromQL
Kondisi PrometheusQueryLanguageCondition menggunakan kueri Prometheus Query Language (PromQL)
untuk memilih dan memanipulasi data deret waktu yang akan dipantau.
Kondisi Anda dapat menghitung rasio metrik,
mengevaluasi perbandingan metrik, dan lainnya.
Jika Anda menggunakan kondisi PrometheusQueryLanguageCondition, kondisi tersebut harus menjadi satu-satunya kondisi dalam kebijakan pemberitahuan Anda. Untuk mengetahui informasi selengkapnya, lihat
Kebijakan pemberitahuan dengan PromQL.
Kondisi untuk pemberitahuan tentang rasio
Anda dapat membuat kebijakan pemberitahuan nilai minimum metrik untuk memantau rasio dua metrik. Anda dapat membuat kebijakan ini menggunakan jenis kondisi MetricThreshold atau PrometheusQueryLanguageCondition.
Anda juga dapat menggunakan PromQL langsung di konsol Google Cloud . Anda tidak dapat membuat atau mengelola kondisi berbasis rasio menggunakan antarmuka grafis untuk membuat kondisi nilai minimum.
Sebaiknya gunakan PromQL untuk membuat kebijakan pemberitahuan berbasis rasio.
PromQL memungkinkan Anda membuat kueri yang lebih canggih dan fleksibel daripada yang dapat Anda buat menggunakan jenis kondisi MetricTheshold dan filter Monitoring.
Misalnya, dengan kondisi PrometheusQueryLanguageCondition, Anda dapat menghitung rasio metrik gauge terhadap metrik delta.
Jika Anda menggunakan kondisi MetricThreshold, pembilang dan penyebut
rasio harus memiliki MetricKind yang sama.
Untuk mengetahui daftar metrik dan propertinya, lihat Daftar metrik.
Secara umum, sebaiknya hitung rasio berdasarkan deret waktu yang dikumpulkan untuk satu jenis metrik, dengan menggunakan nilai label. Rasio yang dihitung berdasarkan 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, yaitu jumlah total RPC dan jumlah error RPC, dan Anda ingin menghitung rasio RPC jumlah error terhadap total RPC. RPC yang tidak berhasil dihitung dalam deret waktu kedua jenis metrik. Oleh karena itu, ada kemungkinan bahwa, saat Anda menyelaraskan deret waktu, RPC yang tidak berhasil tidak muncul dalam interval penyelarasan yang sama untuk kedua deret waktu. Perbedaan ini dapat terjadi karena beberapa alasan, termasuk:
- Karena ada dua deret waktu berbeda yang mencatat peristiwa yang sama, ada dua nilai penghitung pokok yang mengimplementasikan pengumpulan, dan nilai tersebut tidak diupdate secara atomik.
- Frekuensi sampling mungkin berbeda. Jika deret waktu diselaraskan ke periode yang sama, jumlah untuk satu peristiwa mungkin muncul dalam interval penyelarasan yang berdekatan dalam deret waktu untuk metrik yang berbeda.
Perbedaan jumlah nilai dalam interval penyelarasan 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 bisa mendapatkan angka yang lebih besar dengan agregasi, baik dengan menggunakan jendela penyelarasan yang lebih panjang daripada periode pengambilan sampel, atau dengan mengelompokkan data untuk label tertentu. Teknik ini meminimalkan efek perbedaan kecil dalam jumlah titik pada interval tertentu. Artinya, perbedaan dua poin lebih signifikan jika jumlah poin yang diharapkan dalam suatu interval adalah 3 daripada jika jumlah 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 diperlukan.
Jika Anda mendesain metrik kustom yang mungkin menghitung hal yang sama—seperti RPC yang menampilkan status error—dalam dua metrik yang berbeda, pertimbangkan untuk menggunakan satu metrik, yang menyertakan setiap hitungan hanya sekali. Misalnya, Anda menghitung RPC dan ingin melacak rasio RPC yang tidak berhasil 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 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 Anda.
Kebijakan pemberitahuan yang digunakan dalam contoh di dokumen Mengelola kebijakan pemberitahuan berdasarkan API adalah kebijakan pemberitahuan berbasis metrik, meskipun prinsipnya sama untuk kebijakan pemberitahuan berbasis log. Untuk informasi khusus tentang kebijakan pemberitahuan berbasis log, lihat Membuat kebijakan pemberitahuan berbasis log menggunakan Monitoring API dalam dokumentasi Cloud Logging.
Cara mengaitkan kebijakan pemberitahuan dengan aplikasi App Hub
Google Cloud membuat dasbor yang membantu Anda memantau aplikasi App Hub. Dasbor ini menampilkan informasi seperti data log dan metrik untuk aplikasi Anda, serta layanan dan workload yang merupakan bagian dari aplikasi. Kebijakan pemberitahuan dan pemberitahuannya juga ditampilkan di dasbor ini, jika kebijakan tersebut dikaitkan dengan layanan atau workload aplikasi. Untuk mengetahui informasi selengkapnya tentang Pemantauan Aplikasi, lihat Melihat telemetri aplikasi.
Untuk mengaitkan kebijakan pemberitahuan dengan aplikasi App Hub, lampirkan label dengan kunci berikut ke kebijakan Anda:
apphub_application_locationapphub_application_idapphub_service_idatauapphub_workload_id
userLabels dari representasi JSON dari
kebijakan pemberitahuan mungkin seperti berikut:
"userLabels": {
"apphub_service_id": "my-service-id",
"apphub_application_location": "my-app-location",
"apphub_application_id": "my-app"
},
Sebelum memulai
Sebelum menulis kode untuk API, Anda harus:
- Pahami konsep umum dan terminologi yang digunakan dengan kebijakan pemberitahuan; lihat Ringkasan pemberitahuan untuk mengetahui informasi selengkapnya.
- Pastikan Cloud Monitoring API diaktifkan untuk digunakan; lihat Mengaktifkan API untuk mengetahui informasi selengkapnya.
- Jika Anda berencana menggunakan library klien, instal library untuk bahasa yang ingin Anda gunakan; lihat Library Klien untuk mengetahui detailnya. Dukungan API untuk pemberitahuan hanya tersedia untuk C#, Go, Java, Node.js, dan Python.
Jika Anda berencana menggunakan Google Cloud CLI, instal Google Cloud CLI. Namun, jika Anda menggunakan Cloud Shell, Google Cloud CLI sudah diinstal.
Contoh penggunaan antarmuka
gcloudjuga disediakan di sini. Perhatikan bahwa semua contohgcloudmengasumsikan bahwa project saat ini telah ditetapkan sebagai target (gcloud config set project [PROJECT_ID]) sehingga pemanggilan menghilangkan flag--projecteksplisit. ID project saat ini dalam contoh adalaha-gcp-project. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
-
Untuk mendapatkan izin yang diperlukan guna 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 ke project, folder, dan organisasi.Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
Untuk mengetahui informasi mendetail tentang peran IAM untuk Monitoring, lihat Mengontrol akses dengan Identity and Access Management.
Desain aplikasi Anda untuk melakukan panggilan Cloud Monitoring API dengan single-thread yang mengubah status kebijakan pemberitahuan dalam projectGoogle Cloud . Misalnya, panggilan API thread tunggal yang membuat, memperbarui, atau menghapus kebijakan pemberitahuan.
Membuat kebijakan pemberitahuan
Untuk membuat kebijakan pemberitahuan dalam 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,
dan 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 pemberitahuan dan penerima dari Prometheus.
Setiap kebijakan pemberitahuan termasuk dalam project pencakupan dari cakupan metrik. Setiap project dapat berisi hingga 2.000 kebijakan.
Untuk panggilan API, Anda harus memberikan “project ID”; gunakan ID project pencakupan dari cakupan metrik sebagai nilainya. Dalam contoh ini, ID project pencakupan dari cakupan metrik adalah a-gcp-project.
Contoh berikut mengilustrasikan pembuatan kebijakan pemberitahuan, tetapi tidak menjelaskan cara membuat file JSON atau YAML yang menjelaskan kebijakan pemberitahuan. Sebagai gantinya, contoh mengasumsikan bahwa file berformat JSON ada dan contoh tersebut menggambarkan cara melakukan panggilan API. Untuk contoh file JSON, lihat Contoh kebijakan. Untuk mengetahui informasi umum tentang rasio pemantauan metrik, lihat Rasio metrik.
gcloud
Untuk membuat kebijakan pemberitahuan dalam project, gunakan perintah gcloud monitoring
policies create. Contoh berikut membuat kebijakan pemberitahuan di a-gcp-project dari file rising-cpu-usage.json:
gcloud monitoring policies create --policy-from-file="rising-cpu-usage.json"
Jika berhasil, perintah ini akan menampilkan nama kebijakan baru, misalnya:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
File rising-cpu-usage.json berisi JSON untuk kebijakan dengan nama tampilan “High CPU rate of change”. Untuk mengetahui detail tentang kebijakan ini, lihat Kebijakan tingkat perubahan.
Lihat referensi
gcloud monitoring policies create
untuk mengetahui informasi selengkapnya.
C#
Untuk melakukan autentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Go
Untuk melakukan autentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Untuk melakukan autentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Untuk melakukan autentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
PHP
Untuk melakukan autentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Python
Untuk melakukan autentikasi ke Monitoring, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat 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 tidak perlu ditetapkan saat membuat kebijakan. Tidak ada contoh JSON yang digunakan untuk membuat kebijakan yang menyertakannya, tetapi jika kebijakan yang dibuat darinya diambil setelah pembuatan, kolom tersebut akan ada.
Mengonfigurasi notifikasi berulang untuk kebijakan pemberitahuan berbasis metrik
Secara default, kebijakan pemberitahuan berbasis metrik mengirimkan satu notifikasi ke setiap saluran notifikasi saat pemberitahuan dibuka. Namun, Anda dapat mengubah perilaku default dan mengonfigurasi kebijakan pemberitahuan untuk mengirim ulang notifikasi ke semua atau beberapa saluran notifikasi untuk kebijakan pemberitahuan Anda. Notifikasi berulang ini dikirim untuk pemberitahuan dengan status Terbuka atau Diakui. Interval antara notifikasi ini harus minimal 30 menit dan tidak lebih dari 24 jam, yang dinyatakan dalam detik.
Untuk mengonfigurasi notifikasi berulang, tambahkan objek AlertStrategy yang berisi setidaknya satu objek NotificationChannelStrategy ke konfigurasi kebijakan pemberitahuan.
Objek NotificationChannelStrategy memiliki dua kolom:
renotifyInterval: Interval, dalam detik, antara notifikasi berulang.Jika Anda mengubah nilai kolom
renotifyIntervalsaat pemberitahuan untuk kebijakan pemberitahuan dibuka, hal berikut akan terjadi:- Kebijakan pemberitahuan akan mengirimkan notifikasi lain untuk pemberitahuan tersebut.
- Kebijakan pemberitahuan memulai ulang periode interval.
notificationChannelNames: Array nama resource saluran notifikasi, yang merupakan string dalam formatprojects/PROJECT_ID/notificationChannels/CHANNEL_ID, dengan CHANNEL_ID adalah nilai numerik. Untuk mengetahui informasi tentang cara mengambil ID channel, lihat Mencantumkan saluran notifikasi dalam project.
Misalnya, contoh JSON berikut menunjukkan strategi pemberitahuan yang dikonfigurasi untuk mengirim notifikasi berulang setiap 1.800 detik (30 menit) ke satu saluran notifikasi:
"alertStrategy": {
"notificationChannelStrategy": [
{
"notificationChannelNames": [
"projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
],
"renotifyInterval": "1800s"
}
]
}
Untuk menghentikan sementara notifikasi berulang, buat
penundaan. Untuk mencegah notifikasi berulang, edit kebijakan pemberitahuan menggunakan API dan hapus objek NotificationChannelStrategy.