Memberikan anotasi notifikasi dengan dokumentasi yang ditentukan pengguna

Halaman ini menjelaskan cara mengonfigurasi dokumentasi kebijakan pemberitahuan sehingga notifikasi memberikan resource 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 Google Cloud konsol, Cloud Monitoring API, dan Google Cloud CLI.

Subjek

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

Konfigurasi baris subjek notifikasi menggunakan subject kolom dari documentation kebijakan pemberitahuan.

Google Cloud Konsol

Konfigurasi baris subjek notifikasi menggunakan kolom Notification subject line di bagian Notifications and name pada halaman Create alerting policy.

Konten

Konten dokumentasi Anda muncul dalam jenis notifikasi berikut:

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

Sebaiknya konfigurasi konten Anda sehingga responden insiden dapat melihat langkah-langkah remediasi 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:

Cloud Monitoring API

Konfigurasi konten dokumentasi menggunakan kolom content dari documentation kebijakan pemberitahuan.

Google Cloud Konsol

Konfigurasi konten dokumentasi menggunakan kolom Documentation di bagian Notifications and name pada halaman Create alerting policy.

Anda dapat menambahkan link ke dokumentasi sehingga responden insiden 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 responden. Meskipun konsol tidak memiliki kolom khusus untuk link, Anda dapat menambahkan bagian untuk link di isi dokumentasi. Google Cloud

Cloud Monitoring API

Anda dapat menambahkan link ke dokumentasi dengan menentukan satu atau beberapa Link objek di kolom links dari kebijakan pemberitahuan documentation. Setiap objek Link terdiri dari display_name dan url. Anda dapat memiliki hingga tiga link dalam dokumentasi.

Konfigurasi berikut menunjukkan kolom links dengan satu objek Link yang mewakili URL ke playbook insiden. URL menyertakan variabel sehingga penerima notifikasi dapat mengakses playbook yang benar berdasarkan resource yang dimonitor tempat insiden terjadi:

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

Link dokumentasi yang ditambahkan menggunakan kolom Link muncul dalam jenis notifikasi berikut:

  • Email, di bagian Quick Links
  • PagerDuty
  • Pub/Sub
  • Webhook

Google Cloud Konsol

Anda dapat menambahkan link ke konten dokumentasi dengan menyertakannya di kolom Documentation pada kebijakan pemberitahuan. Misalnya, dokumentasi berikut mencantumkan URL untuk playbook pelanggan:

### Troubleshooting and Debug References

Playbook: https://myownpersonaldomain.com/playbook?name=${resource.type}

Link dokumentasi yang ditambahkan menggunakan Google Cloud konsol muncul dengan konten dokumentasi lainnya dalam jenis notifikasi berikut:

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

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 tidak berurutan, ditunjukkan oleh karakter plus, minus, atau tanda bintang awal.
  • Daftar berurutan, ditunjukkan oleh angka awal yang diikuti dengan titik.
  • Teks miring, ditunjukkan oleh garis bawah atau tanda bintang tunggal di sekitar frasa.
  • Teks tebal, ditunjukkan oleh garis bawah atau tanda 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} akan diganti dengan nilai yang diambil dari resource yang sesuai Google Cloud , 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.

Untuk kebijakan pemberitahuan berbasis log yang Anda buat menggunakan Logs Explorer, nilai kolom ini adalah "Log match condition". Untuk menyesuaikan nilai kolom ini, gunakan Cloud Monitoring API.
log.extracted_label.KEY Nilai label KEY, yang diekstrak dari entri log. Hanya untuk kebijakan pemberitahuan berbasis log; untuk mengetahui 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 digit, 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, ${metric.label.value} menyimpan nilai pemicu aturan pemberitahuan Prometheus.

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 maupun 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 dimulai dengan huruf kecil. Kunci dan nilai hanya dapat berisi huruf kecil, digit, 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 dimonitor 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.

1 Misalnya, ${resource.label.zone} diganti dengan nilai label zone. Nilai variabel ini dapat dikelompokkan; lihat null nilai 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 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.
  • Variabel ini hanya diganti dengan nilainya dalam notifikasi yang dikirim melalui saluran notifikasi. Di Google Cloud konsol, 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 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 (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 dihilangkan dan akibatnya akan dirender sebagai null saat variabel diganti dengan nilainya. Semua label dipertahankan jika tidak ada agregasi lintas deret. 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. 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
  • 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 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> 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 High CPU rate of change".

Opsi tambahan ini khusus untuk channel; untuk mengetahui informasi selengkapnya tentang opsi yang mungkin tersedia, lihat dokumentasi yang disediakan oleh vendor channel.

Contoh

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

Contoh cara dokumentasi ditampilkan dalam notifikasi. Link ditampilkan di bagian &#39;Link Cepat&#39;.

Google Cloud Konsol 

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

Contoh cara dokumentasi ditampilkan dalam notifikasi. Link ditampilkan di bagian header &#39;Referensi Pemecahan Masalah dan Debug&#39;.