Memberikan anotasi notifikasi dengan dokumentasi yang ditentukan pengguna

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}

Catatan: Konsol Google Cloud tidak mendukung konfigurasi objek Links untuk kebijakan pemberitahuan.

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 objek Link 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, 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, 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, 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 dimulai 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}} akan muncul sebagai ${metric.label.VALUE}, dalam 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.label.metadata_system_VALUE	Mereferensikan label sistem metadata PromQL, dengan VALUE adalah nama label tertentu, seperti region atau version. Contoh penggunaan: ${metric.label.metadata_system_version}.
metric.label.metadata_user_VALUE	Mereferensikan label pengguna metadata PromQL, dengan VALUE adalah nama label tertentu, seperti region atau name. Contoh penggunaan: ${metric.label.metadata_user_name}.
metric_or_resource.labels	Variabel ini merender semua nilai label metrik dan 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}} akan muncul sebagai ${metric_or_resource.labels} dalam 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 yang valid 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} dalam 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 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,3 Untuk menemukan label yang terkait dengan jenis resource yang dimonitor, lihat Daftar resource.

¹ Misalnya, ${resource.label.zone} diganti dengan nilai label zone. Nilai variabel ini tunduk pada 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 sebagai gantinya.

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.

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.

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 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 seri, label apa pun yang tidak digunakan dalam pengelompokan akan dihapus dan sebagai hasilnya, label tersebut akan dirender sebagai null 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:

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

Catatan: Variabel tidak di-resolve, tetapi muncul sebagai string seperti ${varname}, dalam konteks lain, dalam notifikasi yang dikirim menggunakan saluran notifikasi lainnya.

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: