Memberikan anotasi notifikasi dengan dokumentasi yang ditentukan pengguna

Kebijakan pemberitahuan memungkinkan Anda menambahkan dokumentasi kustom yang disertakan Cloud Monitoring dalam notifikasi. Dokumentasi yang ditentukan pengguna ini dapat mencakup informasi dan link pemecahan masalah, serta dapat membantu responder menyelesaikan pemberitahuan. Anda dapat memformat dokumentasi ini dengan Markdown dan menambahkan variabel; Monitoring mengganti variabel dengan detail tentang kebijakan pemberitahuan dan data yang dipantau saat mengirim notifikasi.

Struktur dokumentasi

Dokumentasi kebijakan pemberitahuan terdiri dari subjek, konten, dan link. Anda dapat mengonfigurasi dokumentasi di Google Cloud konsol, Cloud Monitoring API, dan Google Cloud CLI.

Subjek

Subjek dokumentasi Anda muncul di subjek notifikasi untuk pemberitahuan yang terkait dengan kebijakan pemberitahuan Anda. Penerima notifikasi dapat mengelola dan mengurutkan notifikasi menurut 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.

Konten

Konten dokumentasi Anda muncul dalam jenis notifikasi berikut:

• Email, di bagian Policy Documentation
• PagerDuty
• Pub/Sub
• Slack
• Webhook

Sebaiknya konfigurasi konten Anda agar responder pemberitahuan dapat melihat langkah-langkah perbaikan dan informasi pemberitahuan dalam notifikasi yang terkait dengan kebijakan pemberitahuan Anda. Misalnya, Anda dapat mengonfigurasi dokumentasi untuk menyertakan ringkasan pemberitahuan dan informasi tentang resource yang relevan.

Konten dokumentasi mendukung hal berikut:

• Teks biasa
• Variabel
• Kontrol khusus channel

• Markdown

Link

Anda dapat menambahkan link ke dokumentasi sehingga responder pemberitahuan dapat mengakses resource seperti playbook, repositori, dan Google Cloud dasbor dari notifikasi.

Cloud Monitoring API memungkinkan Anda menentukan objek yang berisi link paling relevan untuk responder. Meskipun Google Cloud konsol tidak memiliki kolom khusus untuk link, Anda dapat menambahkan bagian untuk link di isi dokumentasi.

"links" [
  {
    "displayName": "Playbook",
    "url": "https://myownpersonaldomain.com/playbook?name=${resource.type}"
  }
]

### 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 tagging Markdown berikut:

• Header, ditunjukkan oleh karakter hash awal.
• Daftar yang tidak diurutkan, ditunjukkan oleh karakter plus, minus, atau bintang awal.
• Daftar berurutan, ditunjukkan oleh angka awal yang diikuti dengan titik.
• Teks miring, ditunjukkan oleh garis bawah atau bintang tunggal di sekitar frasa.
• Teks tebal, ditunjukkan oleh garis bawah atau bintang ganda di sekitar frasa.
• Link, ditunjukkan oleh sintaksis [link text](url). Untuk menambahkan link ke notifikasi, sebaiknya gunakan Cloud Monitoring API dan konfigurasi objek Link.

Untuk mengetahui informasi selengkapnya tentang tagging ini, lihat referensi Markdown apa pun, 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} diganti dengan nilai yang diambil dari resource Google Cloud yang sesuai, seperti yang dijelaskan dalam tabel berikut.

¹ Misalnya, ${resource.label.zone} diganti dengan nilai label zone. Nilai variabel ini tunduk pada pengelompokan; lihat null nilai 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 menggunakan resource.label.KEY. Gunakan metadata.user_label.KEY sebagai gantinya.

Catatan penggunaan

• Hanya variabel dalam tabel yang didukung. Anda tidak dapat menggabungkannya ke dalam ekspresi yang lebih kompleks, seperti ${varname1 + varname2}.
• Untuk menyertakan string literal ${ dalam dokumentasi, gunakan karakter escape $ simbol dengan simbol $ kedua, dan $${ akan dirender sebagai ${ dalam dokumentasi Anda.
• Kebijakan pemberitahuan selalu menampilkan string variabel seperti ${varname}.
• Untuk beberapa saluran notifikasi, Cloud Monitoring mengganti string variabel seperti ${varname} dengan nilai yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Resolusi variabel.
• Saat Google Cloud konsol menampilkan tampilan detail pemberitahuan, konsol biasanya mengganti string variabel seperti ${varname} dengan nilai yang sesuai.
• Pastikan setelan agregasi kondisi tidak menghapus label. Jika label dihapus, nilai label dalam notifikasi adalah null. Untuk mengetahui informasi selengkapnya, lihat Variabel untuk label metrik adalah null.

Nilai null

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 null nilai jika kebijakan pemberitahuan Anda menggunakan agregasi lintas deret waktu (pengurangan), misalnya, menghitung SUM di setiap deret waktu yang cocok dengan filter. Saat menggunakan agregasi lintas deret waktu, label apa pun yang tidak digunakan dalam pengelompokan akan dihilangkan dan akibatnya akan dirender sebagai null saat variabel diganti dengan nilainya. Semua label dipertahankan jika tidak ada agregasi lintas deret waktu. Untuk mengetahui informasi selengkapnya, lihat Variabel untuk label metrik adalah null.

• Nilai untuk variabel metadata.* hanya tersedia jika label disertakan secara eksplisit dalam filter atau pengelompokan kondisi untuk agregasi lintas deret waktu. Artinya, Anda harus merujuk ke label metadata dalam filter atau pengelompokan agar memiliki nilai untuk template.

Resolusi variabel

Variabel dalam template dokumentasi diselesaikan dalam konteks berikut:

• Notifikasi yang dikirim menggunakan saluran notifikasi berikut:
  • Email
  • Google Chat
  • Slack
  • Pub/Sub, skema JSON versi 1.2
  • Webhook, skema JSON versi 1.2
  • PagerDuty, skema JSON versi 1.2
• Tampilan detail pemberitahuan konsol Google Cloud .

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 penyebutan. Anda dapat menggunakan @ untuk menautkan notifikasi ke ID pengguna tertentu. Penyebutan tidak dapat menyertakan nama. Misalkan Anda menyertakan string seperti ini di kolom dokumentasi:

<@backendoncall> Alert 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, "Pemberitahuan dibuat berdasarkan kebijakan High CPU rate of change".

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 Google Cloud versi konsol dan Cloud Monitoring API dari dokumentasi template untuk kebijakan pemberitahuan penggunaan CPU. Contoh ini menggunakan email untuk jenis saluran notifikasi. Template dokumentasi menyertakan beberapa variabel untuk meringkas pemberitahuan dan mereferensikan resource REST kebijakan pemberitahuan dan kondisi.

  "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"
      }
    ]
  }

### 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