Memberikan anotasi pemberitahuan menggunakan dokumentasi yang ditentukan pengguna

Halaman ini menjelaskan cara mengonfigurasi dokumentasi kebijakan pemberitahuan untuk menyesuaikan isi dan baris subjek notifikasi Anda. Kolom dokumentasi mendukung teks biasa, Markdown, variabel, dan kontrol khusus saluran.

Menambahkan informasi ke notifikasi

Anda dapat memberikan langkah-langkah perbaikan dan informasi tentang insiden dalam notifikasi kepada responden pemberitahuan, dengan menentukan konten tersebut saat Anda membuat kebijakan pemberitahuan. Misalnya, Anda dapat mengonfigurasi kebijakan pemberitahuan untuk menyertakan link ke playbook internal di setiap notifikasi.

Untuk contoh implementasi, lihat bagian Contoh di halaman ini.

Mengonfigurasi baris subjek notifikasi

Anda dapat mengelola dan mengurutkan notifikasi dengan menentukan baris subjek notifikasi tersebut. Baris subjek dibatasi hingga 255 karakter. Jika Anda tidak menetapkan subjek dalam dokumentasi, Cloud Monitoring akan menentukan baris subjek.

Anda dapat mengonfigurasi baris subjek saat menggunakan Cloud Monitoring API, Google Cloud CLI, atau Konsol Google Cloud.

Untuk contoh implementasi, lihat bagian Contoh di halaman ini.

Menggunakan Markdown

Bidang dokumentasi mendukung subset pemberian tag Markdown berikut:

• Header, ditunjukkan dengan karakter hash awal.
• Daftar yang tidak diurutkan, ditunjukkan dengan karakter plus, minus, atau tanda bintang awal.
• Daftar yang diurutkan, ditunjukkan dengan angka awal yang diikuti dengan titik.
• Teks miring, ditunjukkan dengan garis bawah tunggal atau tanda bintang di sekitar frasa.
• Teks tebal, ditunjukkan dengan garis bawah ganda atau tanda bintang di sekitar frasa.
• Link, ditunjukkan oleh sintaksis [link text](url).

Untuk informasi selengkapnya tentang pemberian tag ini, lihat referensi Markdown, misalnya, Panduan markup.

Menggunakan variabel

Untuk menyesuaikan teks dalam dokumentasi, Anda dapat menggunakan variabel berformat ${varname}. Saat dokumentasi dikirim dengan notifikasi, string ${varname} akan diganti dengan nilai yang diambil dari resource Google Cloud terkait, seperti yang dijelaskan dalam tabel berikut.

Variabel	Nilai
condition.name	Nama resource REST kondisi, seperti projects/foo/alertPolicies/1234/conditions/5678.
condition.display_name	Nama tampilan kondisi, seperti CPU usage increasing rapidly.
log.extracted_label.KEY	Nilai label KEY, diekstrak dari entri log. Khusus untuk pemberitahuan berbasis log; untuk mengetahui informasi selengkapnya, lihat Membuat 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, seperti compute.googleapis.com/instance/cpu/utilization.
metric.display_name	Nama tampilan untuk jenis metrik, seperti CPU utilization.
metric.label.KEY	Nilai label metrik KEY.^1 Untuk menemukan label yang terkait dengan jenis metrik, lihat Daftar metrik. Jika nilai variabel ${metric.label.KEY} tidak diawali dengan angka, huruf, garis miring (/), atau tanda sama dengan (=), Monitoring akan menghapus label dari notifikasi. Saat Anda memigrasikan aturan pemberitahuan Prometheus, template kolom pemberitahuan Prometheus {{$value}} dan {{humanize $value}} muncul sebagai ${metric.label.VALUE}, di konfigurasi dokumentasi kebijakan pemberitahuan. Dalam hal ini, VALUE menyimpan nilai kueri PromQL. Anda juga dapat menggunakan ${metric.label.VALUE} saat membuat kueri PromQL di Google Cloud.
metric_or_resource.labels	Variabel ini merender semua nilai metrik dan label resource sebagai daftar pasangan key-value yang diurutkan. Jika label metrik dan label resource memiliki nama yang sama, hanya label metrik yang akan dirender. Saat Anda memigrasikan aturan pemberitahuan Prometheus, template kolom pemberitahuan Prometheus {{$labels}} dan {{humanize $labels}} muncul sebagai ${metric_or_resource.labels} di konfigurasi dokumentasi kebijakan pemberitahuan.
metric_or_resource.label.KEY	Jika KEY adalah label yang valid, variabel ini akan dirender dalam notifikasi sebagai nilai ${metric.label.KEY}. Jika KEY adalah resource yang valid, variabel ini akan dirender dalam notifikasi sebagai nilai ${resource.label.KEY}. Jika KEY bukan label atau resource yang valid, variabel ini akan dirender dalam notifikasi sebagai string kosong. Saat Anda memigrasikan aturan pemberitahuan Prometheus, template kolom pemberitahuan Prometheus {{$labels.KEY}} dan {{humanize $labels.KEY}} akan muncul sebagai ${metric_or_resource.labels.KEY} di konfigurasi dokumentasi kebijakan pemberitahuan.
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 pencakupan dari cakupan metrik, seperti a-gcp-project.
resource.type	Jenis resource yang dimonitor, seperti gce_instance.
resource.project	Project ID dari resource yang dipantau dari kebijakan pemberitahuan.
resource.label.KEY	Nilai label resource KEY.^1,2,3 Untuk menemukan label yang terkait dengan jenis resource yang dipantau, lihat Daftar resource.

¹ Misalnya, ${resource.label.zone} diganti dengan nilai label zone. Nilai variabel ini dapat mengalami pengelompokan; lihat nilai null untuk mengetahui informasi selengkapnya.
² Untuk mengambil nilai label project_id pada resource yang dimonitor dalam kebijakan pemberitahuan, gunakan ${resource.project}.
³ Anda tidak dapat mengakses label metadata resource yang ditentukan pengguna dengan menggunakan resource.label.KEY.. 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 Anda, konversikan simbol $ dengan simbol $ kedua, dan $${ render 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 nilainya. Contoh di konsol mencakup deskripsi insiden dan pratinjau dokumentasi saat membuat kebijakan pemberitahuan.
• Pastikan setelan agregasi kondisi tidak menghilangkan label. Jika label dihapus, nilai label dalam notifikasi adalah null. Untuk informasi selengkapnya, lihat Variabel untuk label metrik adalah null.

Catatan: Label yang Anda tambahkan ke metrik berbasis log tidak dapat digunakan dalam ekspresi template. Namun, Anda dapat menampilkan label ini dalam legenda diagram dan memfilter deret waktu menurut nilai label.

Contoh

Contoh berikut menunjukkan versi dokumentasi template Konsol Google Cloud dan Cloud Monitoring API untuk kebijakan pemberitahuan penggunaan CPU, dan dokumentasi yang dirender yang muncul dalam isi notifikasi. Contoh ini menggunakan email untuk jenis saluran notifikasi. Template dokumentasi menyertakan beberapa variabel untuk meringkas insiden serta untuk mereferensikan kebijakan pemberitahuan dan resource REST kondisi.

Konsol Google Cloud

Catatan: Baris subjek notifikasi dikonfigurasi di bagian Notifikasi dan nama di halaman Buat kebijakan pemberitahuan.

## CPU utilization exceeded

### Summary

The ${metric.display_name} of the ${resource.type}
${resource.label.instance_id} in the project ${resource.project} has
exceeded 90% for over 15 minutes.

### Additional resource information

Condition resource name: ${condition.name}
Alerting policy resource name: ${policy.name}

### Troubleshooting and Debug References

Repository with debug scripts: example.com
Internal troubleshooting guide: example.com
${resource.type} dashboard: example.com

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 90% for over 15 minutes.\n\n### Additional resource information\n\nCondition resource name: ${condition.name}  \nAlerting policy resource name: ${policy.name}  \n\n### Troubleshooting and Debug References\n    \nRepository with debug scripts: example.com  \nInternal troubleshooting guide: example.com  \n${resource.type} dashboard: example.com",
"mimeType": "text/markdown",
"subject": "Alert: ${metric.display_name} exceeded"
}

Catatan: Teks subject muncul di baris subjek notifikasi.

Format dalam notifikasi

null nilai

Nilai untuk variabel metric.*, resource.*, dan metadata.* berasal dari deret waktu. Nilainya dapat berupa null jika tidak ada nilai yang ditampilkan dari kueri deret waktu.

• Variabel resource.label.KEY dan metric.label.KEY dapat memiliki nilai null jika kebijakan pemberitahuan Anda menggunakan agregasi lintas deret (pengurangan), misalnya, menghitung SUM di setiap deret waktu yang cocok dengan filter. Saat menggunakan agregasi lintas deret, label apa pun yang tidak digunakan dalam pengelompokan akan dihapus, sehingga dirender sebagai null saat variabel diganti dengan nilainya. Semua label dipertahankan jika tidak ada agregasi lintas seri. Untuk informasi selengkapnya, lihat Variabel untuk label metrik adalah 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 diselesaikan dalam notifikasi yang dikirim menggunakan saluran notifikasi berikut:

• Email
• Slack
• Pub/Sub, skema JSON versi 1.2
• Webhook, skema JSON versi 1.2
• PagerDuty, skema JSON versi 1.2

Variabel tidak di-resolve, tetapi muncul sebagai string seperti ${varname}, dalam konteks lain, termasuk yang berikut:

• Di halaman Detail insiden di konsol Google Cloud.
• Dalam notifikasi yang dikirimkan dengan menggunakan saluran notifikasi lain.

Menggunakan kontrol channel

Teks dalam 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. Misalkan Anda menyertakan string seperti ini dalam 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 menyebabkan Slack mengirim pesan tambahan ke ID pengguna backendoncall. Pesan yang dikirim oleh Slack kepada pengguna dapat berisi informasi yang relevan dari notifikasi tersebut; misalnya, "Insiden dibuat berdasarkan kebijakan tingkat perubahan CPU tinggi".

Opsi tambahan ini khusus untuk saluran tersebut. Untuk mengetahui informasi lebih lanjut tentang apa saja yang mungkin tersedia, lihat dokumentasi yang disediakan oleh vendor saluran.