Application Real-Time Monitoring Service:Integrasi peringatan kustom

Langkah 1: Buat integrasi kustom

1. Masuk ke ARMS console. Di panel navigasi sebelah kiri, pilih Alert Management > Integrations.

2. Pada tab Alert Integration, klik Custom Integration.
3. Di kotak dialog Create Custom Event Integration, masukkan nama integrasi, atur waktu pemulihan otomatis peringatan, tambahkan deskripsi jika diperlukan, lalu klik Save and Configure.
   Catatan

   Waktu pemulihan otomatis setelah timeout: Jika event peringatan tidak dipicu lagi dalam periode waktu yang ditentukan, event peringatan tersebut akan dihapus secara otomatis.

Langkah 2: Konfigurasikan titik akhir API

Kirim peringatan dari sumber pihak ketiga Anda ke manajemen peringatan ARMS menggunakan URL titik akhir API yang disediakan.

1. Pada halaman Edit Integration, di bagian API Configuration, salin URL titik akhir dan Kunci API.
2. Dari sumber peringatan pihak ketiga Anda, gunakan URL titik akhir untuk melaporkan konten peringatan.

   Contoh:

   curl -k -H "Content-Type: application/json" -d '{
     "trigger-type": "network",
     "trigger-location": "cn-hangzhou",
     "trigger-severity": "MAX",
     "trigger-policy": "package errors > 5%",
     "trigger-event": "inbound tcp package errors is 20%",
     "trigger-check": "tcp package error percentage",
     "trigger-value": "20",
     "trigger-time": "1629702922000",
     "metadata": [
       {
         "agent": "SERVER",
         "ip": "141.219.XX.XX",
         "fqdn": "websrv1.damenport.org",
         "microServiceId": "ms-login-2251",
         "accountId": "1504000433993",
         "service": "login-0"
       },
       {
         "agent": "CONTAINER",
         "ip": "172.1.XX.XX",
         "fqdn": "websrv2.damenport.org",
         "microServiceId": "ms-login-2252",
         "accountId": "129930302939",
         "service": "login-1"
       }
     ],
     "equipments": [
       {
         "equipmentId": "112"
       },
       {
         "equipmentId": "113"
       }
     ]
   }' "https://alerts.aliyuncs.com/api/v1/integrations/custom/ymQBN******"

   Pertama kali menjalankan perintah curl, respons error berikut ini diharapkan muncul:

   { "requestId":null,"traceId":"0bc3b4a********71e4aa7","code":601,"data":{},"success":false,"errorCode":"Invalid incident, labels.alertname is required","message":"Invalid incident, labels.alertname is required","httpStatusCode":601,"errorCodeParams":null,"dynamicMessage":null

   Setelah Anda menyelesaikan pemetaan di Langkah 3 dan menjalankan perintah tersebut kembali, data yang benar akan dikembalikan.

   Anda juga dapat melaporkan peringatan dengan mengirim data uji. Pertama kali melakukan ini, muncul pesan yang meminta Anda menyelesaikan pemetaan di Langkah 3.

   Di jendela pop-up Send Test Data, setelah Anda mengklik Send untuk pertama kalinya, halaman menampilkan pesan Upload successful, but no event was generated. Please configure event mapping rules based on the raw data! Ikuti petunjuk ini untuk menyelesaikan pemetaan di Langkah 3.

Langkah 3: Konfigurasikan pemetaan field peringatan

Di bagian Event Mapping, petakan field dari sumber peringatan pihak ketiga ke field event peringatan ARMS.

Bagian ini menggunakan contoh untuk mengilustrasikan prosesnya.

Skenario: Terjadi error paket TCP pada jaringan mesin.

Konten peringatan pihak ketiga:

{
  "trigger-type": "network",    // Jenis event: network.
  "trigger-location": "cn-hangzhou",    // Wilayah tempat event terjadi.
  "trigger-severity": "MAX",    // Tingkat keparahan event kustom, seperti MAX, MID, atau LOW.
  "trigger-policy": "package errors > 5%",     // Kebijakan pemicu.
  "trigger-event": "inbound tcp package errors is 20%",    // Konten event: Laju error paket TCP inbound untuk layanan adalah 20%.
  "trigger-check": "tcp package error percentage",    // Item pemeriksaan event: Persentase error paket TCP.
  "trigger-value": "20",    // Nilai sampel peringatan.
  "trigger-time": "1629702922000",    // Waktu mulai peringatan.
  "metadata": [
    {
      "agent": "SERVER",    // Jenis agen: server.
      "ip": "141.219.XX.XX",   // Alamat IP.
      "fqdn": "websrv1.damenport.org",    // Informasi nama domain layanan.
      "microServiceId": "ms-login-2251",    // ID microservice. Jika 'agent' bernilai 'CONTAINER', field ini dipetakan secara kondisional ke field 'service' ARMS.
      "accountId": "1504000433993",    // ID pengguna. Tidak termasuk dalam notifikasi peringatan.
      "service": "login-0" // ID layanan. Jika 'agent' bernilai 'SERVER', field ini dipetakan secara kondisional ke field 'service' ARMS.
    },
    {
      "agent": "CONTAINER",   // Jenis agen: container.
      "ip": "172.1.XX.XX",  // Alamat IP.
      "fqdn": "websrv2.damenport.org",    // Informasi nama domain layanan.
      "microServiceId": "ms-login-2252",   // ID microservice. Jika 'agent' bernilai 'CONTAINER', field ini dipetakan secara kondisional ke field 'service' ARMS.
      "accountId": "129930302939",  // ID pengguna. Tidak termasuk dalam notifikasi peringatan.
      "service": "login-1"    // ID layanan. Jika 'agent' bernilai 'SERVER', field ini dipetakan secara kondisional ke field 'service' ARMS.
    }
  ],
  "equipments": [  // Node array lainnya.
    {
      "equipmentId": "112"
    },
    {
      "equipmentId": "113"
    }
  ]
}

1. Di bagian Event Mapping, klik Send Test Data.

2. Di kotak dialog Send Test Data, masukkan konten peringatan dari sumber pihak ketiga Anda dalam format JSON, lalu klik Send.
   Catatan

   • Jika muncul pesan Uploaded. No events are generated. Configure mappings based on the original data., artinya field dari sumber peringatan belum dipetakan ke field event peringatan ARMS. Data yang dikirim ditampilkan di kotak sebelah kiri, sehingga Anda dapat memilih field sumber saat mengonfigurasi pemetaan.

   • Jika muncul pesan Uploaded., konten peringatan dilaporkan ke halaman Alert Event History. Untuk informasi selengkapnya, lihat View alert event history.

3. Di kotak dialog Send Test Data, klik Disable.

4. Di bagian kiri bagian Event Mapping, klik catatan data yang ingin Anda konfigurasikan pemetaannya untuk melihat detailnya.

5. Di panel kanan bagian Event Mapping, konfigurasikan pemetaan antara field sumber peringatan dan field peringatan ARMS.
   1. Opsi: Di bagian Select Root Node, tentukan apakah akan menggunakan pemrosesan batch.
      Jika data peringatan Anda berisi array, Anda dapat menentukannya sebagai root node untuk pemrosesan batch.

      Setelah memilih Use Batch Processing, pilih node array yang ingin diproses secara batch sebagai root node.

      Catatan Jika data peringatan berisi beberapa node array, manajemen peringatan ARMS hanya memungkinkan Anda memilih satu node array untuk pemrosesan batch.

      Misalnya, dalam contoh peringatan, node array metadata berisi dua field service. Jika Anda memilih metadata sebagai root node, kedua field service di bawah node ini dipetakan ke field peringatan ARMS yang sama.

      • Jika Anda memilih root node, Anda dapat memetakan nilai atribut $.metadata[*].service untuk semua elemen dalam array ke field ARMS service secara iteratif.
      • Jika Anda tidak memilih root node, Anda dapat memetakan nilai elemen tertentu, seperti $.metadata[0].service atau $.metadata[1].service, ke field ARMS service.

   2. Opsi:Pilih Configure Alert Recovery Events dan konfigurasikan kondisi field untuk menghapus peringatan.

      Setelah ARMS menerima event, sistem mencari peringatan yang berisi nilai field tertentu dan menghapus peringatan tersebut. Field yang Anda tentukan untuk menghapus peringatan harus setara dengan tingkat keparahan peringatan dalam event tersebut. Anda tidak dapat menggunakan field $.severity untuk menghapus peringatan. Misalnya, jika field yang Anda tentukan untuk menghapus peringatan adalah {$.eventType ="resolved"}, sistem secara otomatis menghapus semua peringatan yang memiliki nilai eventType sebesar resolved dalam integrasi tersebut.

   3. Di bagian Map Source Fields to Target Fields, petakan field sumber peringatan ke field peringatan ARMS.
      Klik ikon pemetaan untuk mengubah metode pemetaan field.

      • Direct: Field sumber peringatan yang ditentukan langsung dipetakan ke field peringatan ARMS yang sesuai.
      • Series: Menggabungkan beberapa field sumber menjadi satu, dipisahkan oleh pembatas, lalu memetakan hasilnya ke field peringatan ARMS. Hanya karakter khusus yang didukung sebagai pembatas.

        Misalnya, Anda dapat menggunakan garis bawah (_) untuk menggabungkan field $.trigger-type dan $.trigger-policy menjadi $.trigger-type_$.trigger-policy, lalu memetakan hasilnya ke field ARMS alertname.

      • Condition: Memetakan field sumber ke field ARMS tujuan hanya jika kondisi tertentu terpenuhi.

        Misalnya, untuk field agent dalam node array metadata, Anda dapat menetapkan kondisi berikut: Jika nilai agent adalah CONTAINER, petakan nilai atribut microServiceId ke field ARMS service (kondisi If). Jika nilai agent adalah SERVER, petakan nilai atribut service ke field ARMS service (kondisi Else If).

      • mapping table: Menyiapkan pemetaan antara tingkat keparahan peringatan dari sumber peringatan dan tingkat keparahan di ARMS. Tabel pemetaan hanya diperlukan untuk field severity.

      Tabel berikut menjelaskan field peringatan ARMS.

      Parameter	Deskripsi	Metode pemetaan contoh	Field sumber contoh
      alertname	Nama peringatan kustom.	Series	$.trigger-type, $.trigger-policy
      severity	Field untuk memetakan tingkat keparahan peringatan. Anda harus mengonfigurasi tabel pemetaan untuk field ini, dan metode pemetaan harus diatur ke Direct.	Metode: Direct (wajib) mapping table: MAX: P1 MID: P2 MIN: P3	$.trigger-severity
      message	Informasi detail tentang event peringatan, digunakan dalam notifikasi. Panjang maksimum: 15.000 karakter.	Direct	$.trigger-event
      value	Nilai sampel metrik.	Direct	$.trigger-value
      imageUrl	URL grafik garis metrik, digunakan untuk memetakan grafik metrik Grafana.	None	None
      check	Item pemeriksaan peringatan. Contoh: CPU, JVM, Application Crash, dan Deployment.	Direct	$.trigger-check
      source	Sumber event peringatan.	Direct	$.metadata[*].ip
      class	Jenis objek event peringatan, seperti host.	Direct	$.trigger-type
      service	Layanan sumber terkait bisnis, seperti logService.	Condition	Jika $.metadata[*].agent bernilai CONTAINER, petakan $.metadata[*].microServiceId ke field ARMS service. Jika $.metadata[*].agent bernilai SERVER, petakan $.metadata[*].service ke field ARMS service.
      startat	Timestamp mulai event.	Direct	$.trigger-time
      endat	Timestamp akhir event.	None	None
      generatorUrl	URL untuk detail event.	None	None

Langkah 4: Konfigurasikan deduplikasi event

Untuk mengurangi data berlebih, sistem menggunakan field tertentu sebagai dasar deduplikasi event. Manajemen peringatan ARMS memungkinkan Anda melihat pratinjau hasil pengelompokan deduplikasi untuk data event historis di bagian Event Mapping. Anda dapat menyesuaikan field deduplikasi sesuai kebutuhan.

1. Di bagian Event Deduplication, pilih field yang akan digunakan untuk deduplikasi.
   Saat beberapa event memiliki nilai yang sama untuk field yang dipilih, event tersebut digabung menjadi satu notifikasi peringatan.

   Misalnya, tetapkan field ARMS source dan check sebagai kunci deduplikasi. Dalam skenario contoh, field $.metadata[*].ip dari sumber peringatan pihak ketiga dipetakan ke field ARMS source, dan field $.trigger-check dipetakan ke field ARMS check. Akibatnya, event dengan alamat IP dan item pemeriksaan yang sama digabung menjadi satu event, sedangkan event dengan alamat IP atau item pemeriksaan berbeda tetap terpisah.

2. Klik Deduplication Test untuk melihat pratinjau kelompok peringatan setelah deduplikasi.
   Catatan Uji deduplikasi berlaku untuk 10 catatan data uji terakhir yang diunggah di panel kiri bagian Event Mapping.

   Di area Select fields for deduplication, pilih source dan check, lalu klik Deduplication Test. Hasil uji dikelompokkan berdasarkan field yang dipilih. Misalnya, event dibagi menjadi dua kelompok berdasarkan alamat IP sumber berbeda (141.219.xxx dan 172.1.xxx) dan item pemeriksaan yang sama (tcp package error percentage). Event peringatan dalam setiap kelompok memiliki nilai yang sama untuk field source dan check.
3. Setelah menyelesaikan konfigurasi, klik Save.

Hasil

Setelah konfigurasi selesai, halaman Integrations menampilkan integrasi kustom yang telah Anda buat.

Manage integrations

Di panel navigasi sebelah kiri, pilih Alert Management > Integrations. Pada tab Alert Integration, Anda dapat melakukan operasi berikut pada integrasi yang telah Anda buat:

• Lihat detail integrasi: Temukan integrasi lalu klik baris tersebut. Di halaman Integration Details, lihat detail integrasi.

• Perbarui kunci: Di kolom Actions untuk integrasi target, pilih More > Update Key. Di kotak dialog yang muncul, klik Confirm.
  Penting Setelah memperbarui kunci, Anda juga harus memperbarui URL titik akhir di sumber peringatan seperti yang dijelaskan di Langkah 2.

• Ubah integrasi: Temukan integrasi lalu klik Edit di kolom Actions. Di halaman Integration Details, ubah informasi integrasi lalu klik Save.

• Aktifkan atau nonaktifkan integrasi: Temukan integrasi lalu klik Disable atau Enable di kolom Actions.

• Hapus integrasi: Temukan integrasi lalu klik Delete di kolom Actions. Di pesan yang muncul, klik OK.

• Tambahkan alur pemrosesan event ke integrasi: Temukan integrasi lalu klik Add Event Processing Flow di kolom Actions. Untuk informasi selengkapnya, lihat Event processing flow.

• Buat kebijakan notifikasi: Temukan integrasi yang ingin Anda buat kebijakan notifikasinya, lalu klik More di kolom Actions. Di daftar yang muncul, klik Create Notification Policy. Untuk informasi selengkapnya, lihat Notification policies.