Halaman ini menjelaskan cara mengonfigurasi dokumentasi kebijakan pemberitahuan agar notifikasi memberikan referensi dan informasi tambahan kepada responden insiden untuk penyelesaian insiden.
Struktur dokumentasi
Dokumentasi kebijakan pemberitahuan terdiri dari subjek, konten, dan link. Anda dapat mengonfigurasi dokumentasi di konsol Google Cloud, Cloud Monitoring API, dan Google Cloud CLI.
Subjek
Subjek dokumentasi Anda akan muncul di subjek pemberitahuan untuk insiden yang terkait dengan kebijakan pemberitahuan Anda. Penerima notifikasi dapat mengelola dan mengurutkan notifikasi mereka berdasarkan subjek.
Baris subjek dibatasi hingga 255 karakter. Jika Anda tidak menentukan subjek dalam dokumentasi, Cloud Monitoring akan menentukan baris subjek. Baris subjek mendukung teks biasa dan variabel.
Cloud Monitoring API
Konfigurasikan baris subjek notifikasi menggunakan kolom subject
dari kebijakan pemberitahuan documentation
.
Konsol Google Cloud
Konfigurasikan baris subjek notifikasi menggunakan kolom Notification subject line di bagian Notifications and name pada halaman Create alerting policy.
Konten
Konten dokumentasi Anda akan muncul dalam jenis notifikasi berikut:
- Email, di bagian header Dokumentasi Kebijakan
- PagerDuty
- Pub/Sub
- Slack
- Webhook
Sebaiknya konfigurasikan konten Anda agar responden insiden dapat melihat langkah-langkah perbaikan dan informasi insiden dalam notifikasi yang terkait dengan kebijakan pemberitahuan Anda. Misalnya, Anda dapat mengonfigurasi dokumentasi untuk menyertakan ringkasan insiden dan informasi tentang resource yang relevan.
Konten dokumentasi mendukung hal berikut:
- Teks biasa
- Variabel
- Kontrol khusus channel
Markdown di saluran notifikasi non-Slack
Cloud Monitoring API
Konfigurasikan konten dokumentasi menggunakan kolom content
kebijakan pemberitahuan documentation
.
Konsol Google Cloud
Konfigurasikan konten dokumentasi menggunakan kolom Dokumentasi di bagian Notifikasi dan nama di halaman Buat kebijakan pemberitahuan.
Link
Anda dapat menambahkan link ke dokumentasi sehingga responden insiden dapat mengakses resource seperti playbook, repositori, dan dasbor Google Cloud dari notifikasi.
Cloud Monitoring API
Link dokumentasi yang dikonfigurasi di Cloud Monitoring API muncul dalam jenis notifikasi berikut:
- Email, di bagian header Link Cepat
- PagerDuty
- Pub/Sub
- Webhook
Untuk mengonfigurasi link, tambahkan Link
ke
documentation
kebijakan pemberitahuan Anda.
Setiap link direpresentasikan oleh display_name
dan url
. Anda dapat memiliki maksimal
tiga link dalam dokumentasi.
Konfigurasi berikut menggunakan links
dengan satu URL
untuk membuat link ke playbook insiden. URL menyertakan variabel sehingga penerima notifikasi dapat mengakses playbook yang benar berdasarkan resource yang dipantau tempat insiden terjadi:
"links" [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
}
]
Konsol Google Cloud
Link dokumentasi yang dikonfigurasi di konsol Google Cloud akan muncul bersama konten dokumentasi lainnya dalam jenis notifikasi berikut:
- Email, di bagian header Dokumentasi Kebijakan
- PagerDuty
- Pub/Sub
- Slack
- Webhook
Anda dapat menambahkan link ke konten dokumentasi dengan menyertakannya di kolom Dokumentasi kebijakan pemberitahuan. Misalnya, dokumentasi berikut mencantumkan URL untuk playbook pelanggan:
### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}
Markdown dalam konten dokumentasi
Anda dapat menggunakan Markdown untuk memformat konten dokumentasi. Konten dokumentasi mendukung subset pemberian tag Markdown berikut:
- Header, yang ditunjukkan dengan karakter hash awal.
- Daftar acak, yang ditunjukkan dengan karakter plus, minus, atau tanda bintang awal.
- Daftar yang diurutkan, ditunjukkan dengan angka awal yang diikuti dengan titik.
- Teks miring, yang ditunjukkan dengan garis bawah atau tanda bintang tunggal di sekitar frasa.
- Teks tebal, yang ditunjukkan dengan garis bawah ganda atau tanda bintang di sekitar frasa.
- Link, yang ditunjukkan oleh sintaksis
[link text](url)
. Namun, sebaiknya gunakan objekLink
untuk mengonfigurasi link untuk konten Anda.
Untuk mengetahui informasi selengkapnya tentang pemberian tag ini, lihat referensi Markdown, misalnya, panduan Markdown.
Variabel dalam dokumentasi
Untuk menyesuaikan teks dalam dokumentasi, Anda dapat menggunakan variabel
dalam bentuk ${varname}
. Saat dokumentasi dikirim dengan
notifikasi, string ${varname}
akan diganti dengan nilai yang diambil dari
resource Google Cloud yang sesuai, seperti yang dijelaskan dalam tabel berikut.
Variabel | Nilai |
---|---|
condition.name |
Nama resource REST kondisi, sepertiprojects/foo/alertPolicies/1234/conditions/5678 . |
condition.display_name |
Nama tampilan kondisi, seperti
CPU usage increasing rapidly . |
log.extracted_label.KEY |
Nilai label KEY , yang diekstrak
dari entri log. Khusus untuk kebijakan pemberitahuan berbasis log; untuk informasi
selengkapnya,
lihat
Membuat kebijakan pemberitahuan berbasis log menggunakan Monitoring API. |
metadata.system_label.KEY |
Nilai label metadata resource yang disediakan sistem KEY .1 |
metadata.user_label.KEY |
Nilai label metadata resource yang ditentukan pengguna KEY .1,3 |
metric.type |
Jenis metrik, seperticompute.googleapis.com/instance/cpu/utilization . |
metric.display_name |
Nama tampilan untuk jenis metrik, seperti
CPU utilization . |
metric.label.KEY |
Nilai label metrik Jika nilai variabel Saat Anda memigrasikan aturan pemberitahuan Prometheus, template kolom pemberitahuan Prometheus Anda juga dapat menggunakan |
metric.label.metadata_system_VALUE |
Mereferensikan label sistem metadata PromQL,
dengan VALUE adalah nama label tertentu, seperti
Contoh penggunaan:
|
metric.label.metadata_user_VALUE |
Mereferensikan label pengguna metadata PromQL,
dengan VALUE adalah nama label tertentu, seperti
Contoh penggunaan: |
metric_or_resource.labels |
Variabel ini merender semua nilai label metrik dan resource sebagai daftar pasangan Saat Anda memigrasikan aturan pemberitahuan Prometheus, template kolom pemberitahuan Prometheus |
metric_or_resource.label.KEY |
Saat Anda memigrasikan aturan pemberitahuan Prometheus, template kolom pemberitahuan Prometheus |
policy.name |
Nama resource REST kebijakan, seperti
projects/foo/alertPolicies/1234 . |
policy.display_name |
Nama tampilan kebijakan, seperti
High CPU rate of change . |
policy.user_label.KEY |
Nilai label pengguna KEY .1
Kunci harus diawali dengan huruf kecil. Kunci dan nilai hanya boleh berisi huruf kecil, angka, garis bawah, dan tanda hubung. |
project |
ID project cakupan cakupan metrik, seperti
a-gcp-project . |
resource.type |
Jenis resource yang dimonitor, seperti gce_instance . |
resource.project |
Project ID resource yang dipantau dari kebijakan pemberitahuan. |
resource.label.KEY |
Nilai label resource
KEY .1,2,3Untuk menemukan label yang terkait dengan jenis resource yang dimonitor, lihat Daftar resource. |
1 Misalnya, ${resource.label.zone}
diganti dengan
nilai label zone
. Nilai variabel ini tunduk pada
pengelompokan; lihat nilai null
untuk mengetahui informasi selengkapnya.
2 Untuk mengambil nilai label project_id
pada
resource yang dimonitor dalam kebijakan pemberitahuan, gunakan ${resource.project}
.
3 Anda tidak dapat mengakses label metadata resource yang ditentukan pengguna dengan
menggunakan resource.label.KEY.
. Sebagai gantinya, gunakan metadata.user_label.KEY
.
Catatan penggunaan
- Hanya variabel dalam tabel yang didukung. Anda tidak dapat menggabungkannya menjadi
ekspresi yang lebih kompleks, seperti
${varname1 + varname2}
. - Untuk menyertakan string literal
${
dalam dokumentasi, escape simbol$
dengan simbol$
kedua, dan$${
akan dirender sebagai${
dalam dokumentasi Anda. - Variabel ini diganti dengan nilainya hanya dalam notifikasi yang dikirim melalui saluran notifikasi. Di konsol Google Cloud, saat dokumentasi ditampilkan, Anda akan melihat variabel, bukan nilai. Contoh di konsol mencakup deskripsi insiden dan pratinjau dokumentasi saat membuat kebijakan pemberitahuan.
- Pastikan setelan agregasi kondisi tidak menghapus label. Jika label dihapus, nilai label dalam
notifikasi adalah
null
. Untuk informasi selengkapnya, lihat Variabel untuk label metrik bernilai null.
null
nilai
Nilai untuk variabel metric.*
, resource.*
, dan metadata.*
diperoleh dari deret waktu. Nilainya dapat berupa null
jika tidak ada nilai
yang ditampilkan dari kueri deret waktu.
Variabel
resource.label.KEY
danmetric.label.KEY
dapat memiliki nilainull
jika kebijakan pemberitahuan Anda menggunakan agregasi lintas-deret (pengurangan), misalnya, menghitung SUM di setiap deret waktu yang cocok dengan filter. Saat menggunakan agregasi lintas seri, label apa pun yang tidak digunakan dalam pengelompokan akan dihapus dan sebagai hasilnya, label tersebut akan dirender sebagainull
saat variabel diganti dengan nilainya. Semua label akan dipertahankan jika tidak ada agregasi lintas seri. Untuk informasi selengkapnya, lihat Variabel untuk label metrik bernilai null.Nilai untuk variabel
metadata.*
hanya tersedia jika label secara eksplisit disertakan dalam filter atau pengelompokan kondisi untuk agregasi lintas seri. Artinya, Anda harus merujuk ke label metadata dalam filter atau pengelompokan agar memiliki nilai untuk template.
Resolusi variabel
Variabel dalam template dokumentasi hanya di-resolve dalam notifikasi yang dikirim menggunakan saluran notifikasi berikut:
- Google Chat
- Slack
- Pub/Sub, skema JSON versi 1.2
- Webhook, skema JSON versi 1.2
- PagerDuty, skema JSON versi 1.2
Kontrol channel
Teks di kolom dokumentasi juga dapat menyertakan karakter khusus yang digunakan oleh saluran notifikasi itu sendiri untuk mengontrol pemformatan dan notifikasi.
Misalnya, Slack menggunakan @
untuk sebutan. Anda dapat menggunakan @
untuk menautkan
notifikasi ke ID pengguna tertentu. Sebutan tidak boleh menyertakan nama.
Misalnya, Anda menyertakan string seperti ini di kolom dokumentasi:
<@backendoncall> Incident created based on policy ${policy.display_name}
Saat kolom dokumentasi diterima oleh saluran Slack yang relevan sebagai bagian
dari notifikasi, string sebelumnya akan menyebabkan Slack mengirim
pesan tambahan ke ID pengguna
backendoncall
. Pesan yang dikirim oleh Slack kepada pengguna
dapat berisi informasi yang relevan dari notifikasi; misalnya,
"Insiden dibuat berdasarkan kebijakan Rasio perubahan CPU Tinggi".
Opsi tambahan ini khusus untuk saluran; untuk mengetahui informasi selengkapnya tentang opsi yang mungkin tersedia, lihat dokumentasi yang disediakan oleh vendor saluran.
Contoh
Contoh berikut menunjukkan dokumentasi template versi Konsol Google Cloud dan Cloud Monitoring API untuk kebijakan pemberitahuan penggunaan CPU. Contoh ini menggunakan email untuk jenis saluran notifikasi. Template dokumentasi mencakup beberapa variabel untuk meringkas insiden dan mereferensikan kebijakan pemberitahuan dan resource REST kondisi.
Cloud Monitoring API
"documentation": {
"content": "### CPU utilization exceeded\n\n### Summary\n\nThe ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds.\n\n#### Additional resource information\n\nCondition resource name: ${condition.name} \nAlerting policy resource name: ${policy.name}",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded",
"links": [
{
"displayName": "Playbook",
"url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
},
{
"displayName": "Repository with debug scripts",
"url": "https://altostrat.com"
},
{
"displayName": "Google Cloud dashboard",
"url": "https://example.com"
}
]
}
Gambar berikut menunjukkan tampilan template ini dalam notifikasi email:
Konsol Google Cloud
### CPU utilization exceeded #### Summary The ${metric.display_name} of the ${resource.type} ${resource.label.instance_id} in the project ${resource.project} has exceeded 5% for over 60 seconds. #### Additional resource information Condition resource name: ${condition.name} Alerting policy resource name: ${policy.name} #### Troubleshooting and Debug References Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type} Repository with debug scripts: https://altostrat.com ${resource.type} dashboard: https://example.com
Gambar berikut menunjukkan tampilan template ini dalam notifikasi email: