Bagikan melalui

Cara mengintegrasikan API Management Azure dengan Application Insights Azure

  • Artikel

BERLAKU UNTUK: Semua tingkatAN API Management

Anda dapat dengan mudah mengintegrasikan Azure Application Insights dengan Azure API Management. Azure Application Insights adalah layanan yang dapat diperluas untuk pengembang web yang membangun dan mengelola aplikasi di berbagai platform. Dalam panduan ini, Anda akan:

  • Telusuri integrasi Application Insights ke API Management.
  • Pelajari strategi untuk mengurangi dampak performa pada instans layanan API Management Anda.

Catatan

Di ruang kerja API Management, pemilik ruang kerja dapat mengintegrasikan Application Insights secara independen dan mengaktifkan pengelogan Application Insights untuk API ruang kerja. Panduan umum untuk mengintegrasikan ruang kerja dengan Application Insights mirip dengan panduan untuk instans API Management; namun, konfigurasi hanya dilingkupkan ke ruang kerja. Saat ini, Anda harus mengintegrasikan Application Insights di ruang kerja dengan mengonfigurasi string koneksi (disarankan) atau kunci instrumentasi.

Peringatan

Saat menggunakan gateway yang dihost sendiri, kami tidak menjamin semua telemetri akan didorong ke Azure Application Insights mengingatnya bergantung pada buffering dalam memori Application Insights.

Prasyarat

  • Anda memerlukan instans API Management Azure. Buat instans terlebih dahulu.

  • Untuk menggunakan Application Insights, buat instans layanan Application Insights. Untuk membuat instans menggunakan portal Microsoft Azure, lihat Sumber daya Application Insights berbasis ruang kerja.

    Catatan

    Sumber daya Application Insights dapat berada di langganan yang berbeda atau bahkan penyewa yang berbeda dengan sumber daya API Management.

  • Jika Anda berencana untuk mengonfigurasi kredensial identitas terkelola untuk digunakan dengan Application Insights, selesaikan langkah-langkah berikut:

    1. Aktifkan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna untuk API Management.

      • Jika Anda mengaktifkan identitas terkelola yang ditetapkan pengguna, catat ID Klien identitas.

    2. Tetapkan identitas peran Penerbit Metrik Pemantauan, yang terlingkup ke sumber daya Application Insights. Untuk menetapkan peran, gunakan portal Azure atau alat Azure lainnya.

Gambaran umum skenario

Berikut ini adalah langkah-langkah tingkat tinggi untuk skenario ini.

  1. Pertama, buat koneksi antara Application Insights dan API Management

    Anda dapat membuat koneksi antara Application Insights dan API Management Anda menggunakan portal Azure, REST API, atau alat Azure terkait. API Management mengonfigurasi sumber daya pencatat untuk koneksi.

    Penting

    Saat ini, di portal, API Management hanya mendukung koneksi ke Application Insights menggunakan kunci instrumentasi Application Insights. Untuk keamanan yang ditingkatkan, sebaiknya gunakan string koneksi Application Insights dengan identitas terkelola API Management. Untuk mengonfigurasi string koneksi dengan kredensial identitas terkelola, gunakan REST API atau alat terkait seperti yang ditunjukkan di bagian selanjutnya dari artikel ini. Pelajari selengkapnya tentang string koneksi Application Insights.

    Catatan

    Jika sumber daya Application Insights Anda berada di penyewa yang berbeda, maka Anda harus membuat pencatat menggunakan REST API atau alat terkait seperti yang ditunjukkan di bagian selanjutnya dari artikel ini.

  2. Kedua, aktifkan pengelogan Application Insights untuk API atau API Anda.

    Dalam artikel ini, Anda mengaktifkan pengelogan Application Insights untuk API Anda menggunakan portal Azure. API Management mengonfigurasi sumber daya diagnostik untuk API.

Membuat koneksi menggunakan portal Azure

Ikuti langkah-langkah ini untuk menggunakan portal Azure untuk membuat koneksi antara Application Insights dan API Management.

Catatan

Jika memungkinkan, Microsoft merekomendasikan penggunaan string koneksi dengan kredensial identitas terkelola untuk keamanan yang ditingkatkan. Untuk mengonfigurasi kredensial ini, gunakan REST API atau alat terkait seperti yang ditunjukkan di bagian selanjutnya dari artikel ini.

  1. Navigasikan ke instans layanan Azure API Management Anda di portal Azure.

  2. Pilih Application Insights dari menu di sebelah kiri.

  3. Pilih + Tambah.
    Cuplikan layar yang menunjukkan tempat untuk menambahkan koneksi baru

  4. Pilih instans Application Insights yang Anda buat sebelumnya dan berikan deskripsi singkat.

  5. Untuk mengaktifkan pemantauan ketersediaan instans API Management di Application Insights, pilih kotak centang Tambahkan pemantauan.

    • Pengaturan ini secara rutin memvalidasi apakah titik akhir gateway API Management merespons.
    • Hasil muncul di panel Ketersediaan instans Application Insights.

  6. Pilih Buat.

  7. Periksa apakah pencatat Application Insights baru sekarang muncul dalam daftar.

    Cuplikan layar yang menunjukkan tempat untuk melihat pencatat Application Insights yang baru dibuat.

Catatan

Di balik layar, entitas pencatat dibuat di instans API Management Anda, yang berisi kunci instrumentasi instans Application Insights.

Tip

Jika Anda perlu memperbarui kunci instrumentasi yang dikonfigurasi di pencatat Application Insights, pilih baris pencatat dalam daftar (bukan nama pencatat). Masukkan kunci instrumentasi, dan pilih Simpan.

Membuat koneksi menggunakan rest API, Bicep, atau templat ARM

Ikuti langkah-langkah ini untuk menggunakan templat REST API, Bicep, atau ARM untuk membuat pencatat Application Insights untuk instans API Management Anda. Anda dapat mengonfigurasi pencatat yang menggunakan string koneksi dengan kredensial identitas terkelola (disarankan), atau pencatat yang hanya menggunakan string koneksi.

Lihat prasyarat untuk menggunakan identitas terkelola API Management.

String koneksi Application Insights muncul di bagian Gambaran Umum sumber daya Application Insights Anda.

String koneksi dengan identitas terkelola yang ditetapkan sistem

Gunakan API Management Logger - Buat atau Perbarui REST API dengan isi permintaan berikut.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

String koneksi dengan identitas terkelola yang ditetapkan pengguna

Gunakan API Management Logger - Buat atau Perbarui REST API dengan isi permintaan berikut.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Pencatat hanya dengan kredensial string koneksi

String koneksi Application Insights muncul di bagian Gambaran Umum sumber daya Application Insights Anda.

Gunakan API Management Logger - Buat atau Perbarui REST API dengan isi permintaan berikut.

Jika Anda mengonfigurasi pencatat untuk ruang kerja, gunakan Pencatat Ruang Kerja - Buat atau Perbarui REST API.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

Aktifkan pencatatan Application Insights untuk API Anda

Gunakan langkah-langkah berikut untuk mengaktifkan pengelogan Application Insights untuk API. Anda juga dapat mengaktifkan pengelogan Application Insights untuk semua API.

  1. Navigasikan ke instans layanan Azure API Management Anda di portal Azure.

  2. Pilih API dari menu di sebelah kiri.

  3. Klik pada API Anda, dalam hal ini Demo Conference API. Jika dikonfigurasi, pilih versi.

    Tip

    Untuk mengaktifkan pengelogan untuk semua API, pilih Semua API.

  4. Buka tab Pengaturan dari bilah atas.

  5. Gulir ke bawah ke bagian Log Diagnostik.
    Pencatat App Insights

  6. Centang kotak Aktifkan.

  7. Pilih pencatat Anda yang terlampir di menu tarik-turun Tujuan.

  8. Masukkan 100 sebagai Pengambilan Sampel (%) dan pilih kotak centang Selalu catat kesalahan.

  9. Biarkan pengaturan lainnya apa adanya. Untuk detail tentang pengaturan, lihat Referensi pengaturan log diagnostik.

    Peringatan

    Mengesampingkan Jumlah byte payload default ke nilai log 0 dapat secara signifikan menurunkan performa API Anda.

  10. Pilih Simpan.

  11. Di belakang layar, entitas Diagnostik bernama applicationinsights dibuat pada tingkat API.

Catatan

Permintaan berhasil setelah API Management mengirimkan seluruh respons ke klien.

Pencatat untuk satu API atau semua API

Anda dapat menentukan pencatat pada tingkat yang berbeda:

  • Pencatat API tunggal
  • Pencatat untuk semua API

Menentukan keduanya:

  • Secara default, pencatat API tunggal (tingkat yang lebih terperinci) mengambil alih satu untuk semua API.
  • Jika pencatat yang dikonfigurasi di dua tingkat berbeda, dan Anda memerlukan kedua pencatat untuk menerima telemetri (multiplexing), silakan hubungi Dukungan Microsoft. Harap dicatat bahwa multiplexing tidak didukung jika Anda menggunakan pencatat yang sama (tujuan Application Insights) di tingkat "Semua API" dan tingkat API tunggal. Agar multipleks berfungsi dengan benar, Anda harus mengonfigurasi pencatat yang berbeda di "Semua API" dan tingkat API individual dan meminta bantuan dari dukungan Microsoft untuk mengaktifkan multipleks untuk layanan Anda.

Data apa yang ditambahkan ke Application Insights

Application Insights menerima:

Item telemetri Deskripsi
Permintaan Untuk setiap permintaan masuk:
  • permintaan frontend
  • permintaan frontend
Dependensi Untuk setiap permintaan yang diteruskan ke layanan backend:
  • permintaan backend
  • permintaan backend
Pengecualian Untuk setiap permintaan yang gagal:
  • Gagal karena koneksi klien tertutup
  • Memicu bagian on-error dari kebijakan API
  • Memiliki kode status HTTP respons yang cocok dengan 4xx atau 5xx
Bekas Jika Anda mengonfigurasi kebijakan jejak.
Pengaturan severity di kebijakan trace harus sama dengan atau lebih besar dari pengaturan verbosity di pengelogan Application Insights.

Catatan

Lihat batas Application Insights untuk informasi tentang ukuran maksimum dan jumlah metrik dan peristiwa per contoh Application Insights.

Mengeluarkan metrik kustom

Anda dapat memancarkan metrik kustom ke Application Insights dari instans API Management Anda. API Management memancarkan metrik kustom menggunakan kebijakan seperti emit-metric dan azure-openai-emit-token-metric. Bagian berikut menggunakan emit-metric kebijakan sebagai contoh.

Catatan

Metrik kustom adalah fitur pratinjau dari Azure Monitor dan tunduk pada batasan.

Untuk memancarkan metrik kustom, lakukan langkah-langkah konfigurasi berikut.

  1. Aktifkan Metrik kustom (Pratinjau) dengan dimensi kustom di instans Application Insights Anda.

    1. Navigasikan ke instans Application Insights Anda di portal.
    2. Di menu sebelah kiri, pilih Penggunaan dan perkiraan biaya.
    3. Pilih Metrik kustom (Pratinjau)>Dengan dimensi.
    4. Pilih OK.

  2. "metrics": true Tambahkan properti ke applicationInsights entitas diagnostik yang dikonfigurasi dalam API Management. Saat ini Anda harus menambahkan properti ini menggunakan API Management Diagnostic - Create atau Update REST API. Contohnya:

    PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights

{
    [...]
    {
    "properties": {
        "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}",
        "metrics": true
        [...]
    }
}

  3. Pastikan bahwa pencatat Application Insights dikonfigurasi pada cakupan yang ingin Anda keluarkan metrik kustom (baik semua API, atau satu API). Untuk informasi selengkapnya, lihat Mengaktifkan pengelogan Application Insights untuk API Anda, sebelumnya di artikel ini.

  4. Konfigurasikan emit-metric kebijakan pada cakupan tempat pengelogan Application Insights dikonfigurasi (baik semua API, atau satu API) dan diaktifkan untuk metrik kustom. Untuk detail kebijakan, lihat emit-metric referensi kebijakan.

Batas metrik kustom

Azure Monitor memberlakukan batas penggunaan untuk metrik kustom yang dapat memengaruhi kemampuan Anda untuk memancarkan metrik dari API Management. Misalnya, Azure Monitor saat ini menetapkan batas 10 kunci dimensi per metrik, dan batas 50.000 total rangkaian waktu aktif per wilayah dalam langganan (dalam periode 12 jam).

Batas ini memiliki implikasi berikut untuk mengonfigurasi metrik kustom dalam kebijakan API Management seperti emit-metric atau azure-openai-emit-token-metric:

  • Anda dapat mengonfigurasi maksimum 10 dimensi kustom per kebijakan.

  • Jumlah rangkaian waktu aktif yang dihasilkan oleh kebijakan dalam periode 12 jam adalah produk dari jumlah nilai unik dari setiap dimensi yang dikonfigurasi selama periode tersebut. Misalnya, jika tiga dimensi kustom dikonfigurasi dalam kebijakan, dan setiap dimensi memiliki 10 nilai yang mungkin dalam periode tersebut, kebijakan akan berkontribusi 1.000 (10 x 10 x 10) rangkaian waktu aktif.

  • Jika Anda mengonfigurasi kebijakan dalam beberapa instans API Management yang berada di wilayah yang sama dalam langganan, semua instans dapat berkontribusi pada batas rangkaian waktu aktif regional.

Pelajari selengkapnya tentang batasan dan pertimbangan desain untuk metrik kustom di Azure Monitor.

Implikasi kinerja dan pengambilan sampel log

Peringatan

Mencatat semua peristiwa bisa memiliki implikasi kinerja yang serius, bergantung pada tingkat permintaan yang masuk.

Berdasarkan tes muatan internal, mengaktifkan fitur pencatatan menyebabkan penurunan throughput 40% -50% ketika tingkat permintaan melebihi 1.000 permintaan per detik. Application Insights dirancang untuk menilai performa aplikasi menggunakan analisis statistik. Ini bukan:

  • Dimaksudkan untuk menjadi sistem audit.
  • Cocok untuk mencatat setiap permintaan individu untuk API volume tinggi.

Anda dapat memanipulasi jumlah permintaan yang dicatat dengan menyesuaikan pengaturan Pengambilan Sampel. Nilai 100 % berarti semua permintaan dicatat, sedangkan 0 % mencerminkan tidak ada pengelogan.

Pengambilan Sampel membantu mengurangi volume telemetri, secara efektif mencegah degradasi performa yang signifikan sambil tetap membawa manfaat pengelogan.

Untuk meningkatkan masalah performa, lewati:

  • Header permintaan dan respons.
  • Pengelogan isi.

Video

Pemecahan Masalah

Mengatasi masalah aliran data telemetri dari API Management ke Application Insights:

  • Selidiki apakah sumber daya Azure Monitor Private Link Scope (AMPLS) tertaut ada dalam VNet tempat sumber daya API Management terhubung. Sumber daya AMPLS memiliki cakupan global di seluruh langganan dan bertanggung jawab untuk mengelola kueri dan penyerapan data untuk semua sumber daya Azure Monitor. Ada kemungkinan bahwa AMPLS telah dikonfigurasi dengan mode akses Privat-Saja khusus untuk penyerapan data. Dalam kasus tersebut, sertakan sumber daya Application Insights dan sumber daya Analitik Log terkait di AMPLS. Setelah penambahan ini dibuat, data API Management akan berhasil diserap ke dalam sumber daya Application Insights, menyelesaikan masalah transmisi data telemetri.

Konten terkait