Bagikan melalui

Menggunakan Azure Application Insights di penyusun API Data

Azure Application Insights adalah layanan Pemantauan Performa Aplikasi (APM) yang secara otomatis menangkap permintaan, jejak, pengecualian, dan metrik performa. Mengintegrasikannya dengan Penyusun API Data (DAB) membantu Anda memantau perilaku runtime, mendiagnosis masalah, dan mengoptimalkan performa dalam produksi.

Diagram memperlihatkan alur telemetri Application Insights.

Peringatan

Integrasi Application Insights dengan DAB mungkin memiliki batasan saat dihosting di aplikasi web Azure App Service karena instrumentasi ganda. Application Insights berfungsi paling baik dengan DAB saat Anda menghost sendiri dalam kontainer, Azure Container Apps, atau Azure Kubernetes Service (AKS). Jika Anda harus menggunakan App Service, uji secara menyeluruh atau pertimbangkan pendekatan pemantauan alternatif.

Prasyarat

  • File konfigurasi DAB yang ada.
  • Sumber daya Azure Application Insights.
  • String koneksi untuk Application Insights.
  • CLI pembangun API Data. Menginstal CLI

Dapatkan string koneksi

Sebelum mengonfigurasi DAB, dapatkan string koneksi Application Insights dari Azure.

portal Azure

  1. Buka sumber daya Application Insights di portal Azure.
  2. Buka Gambaran Umum atau Properti.
  3. Salin String Koneksi (bukan Kunci Instrumentasi).

Azure CLI (antarmuka baris perintah Azure)

az monitor app-insights component show \
  --app my-app-insights \
  --resource-group my-rg \
  --query connectionString -o tsv

Format string untuk koneksi

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/;LiveEndpoint=https://<region>.livediagnostics.monitor.azure.com/

Nota

Gunakan string koneksi lengkap (bukan hanya kunci instrumentasi) untuk titik akhir khusus wilayah dan performa yang lebih baik.

Konfigurasikan Wawasan Aplikasi

application-insights Tambahkan bagian di bawah runtime.telemetry dalam file konfigurasi Anda.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

Konfigurasi ini menggunakan variabel lingkungan untuk string koneksi. Tentukan dalam .env file:

app-insights-connection-string="InstrumentationKey=...;IngestionEndpoint=...;LiveEndpoint=..."

Peringatan

Jangan pernah menerapkan string koneksi ke kontrol sumber. Selalu gunakan variabel lingkungan atau Azure Key Vault.

Command-line

Mengonfigurasi Application Insights melalui dab add-telemetry.

Option Deskripsi
--app-insights-enabled Mengaktifkan atau menonaktifkan Application Insights (true atau false).
--app-insights-conn-string String koneksi untuk Application Insights.

Mengaktifkan Application Insights

dab add-telemetry \
  --app-insights-enabled true \
  --app-insights-conn-string "@env('app-insights-connection-string')"

Menonaktifkan Application Insights

dab add-telemetry \
  --app-insights-enabled false

Nota

Pengaturan Application Insights menggunakan dab add-telemetry, bukan dab configure.

Jalankan DAB

Mulai DAB dengan file konfigurasi Anda:

dab start

Periksa log startup untuk konfirmasi:

Application Insights telemetry is enabled with connection string from config.

Cara kerjanya

Saat Application Insights diaktifkan, DAB:

  1. Mendaftarkan Application Insights SDK menggunakan AddApplicationInsightsTelemetry().
  2. Mendaftarkan penginisialisasi telemetri kustom untuk memperkaya semua telemetri dengan properti khusus DAB.
  3. Mengonfigurasi TelemetryClient dengan string koneksi yang berasal dari konfigurasi.
  4. Terintegrasi dengan pengelogan ASP.NET Core untuk mengambil log konsol sebagai jejak.

Aliran Data

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
ApplicationInsightsLoggerProvider
    ↓
AppInsightsTelemetryInitializer (adds custom properties)
    ↓
TelemetryClient
    ↓
Application Insights (Azure)

Apa yang akan ditangkap

Jenis telemetri Sumber Examples
Permintaan ASP.NET Core middleware Permintaan REST/GraphQL, waktu respons, kode status
Tanda-tanda ILogger panggilan di DAB Log pengaktifan, log eksekusi kueri, peringatan
Pengecualian Pengecualian yang Tidak Tertangani Kesalahan runtime, kesalahan konfigurasi, kesalahan database
Dependensi Panggilan Database Kueri SQL, operasi Azure Cosmos DB, durasi
Penghitung kinerja Runtime Penggunaan CPU, konsumsi memori, tingkat permintaan

Pengayaan telemetri

DAB secara otomatis memperkaya semua telemetri Application Insights dengan properti kustom:

Harta benda Deskripsi Contoh nilai
ProductName Pengidentifikasi agen pengguna DAB dab-1.2.3
UserAgent String agen pengguna DAB penuh data-api-builder/1.2.3
Cloud.RoleName Nama peran cloud DAB DataApiBuilder
Component.Version Versi DAB 1.2.3
Session.Id Pengidentifikasi sesi unik guid

Properti ini membantu memfilter dan menghubungkan telemetri khusus DAB di Application Insights.

Kueri Telemetri di Azure

Jejak (log)

traces
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, message, severityLevel

Pemetaan LogLevel:

LogLevel Tingkat Keparahan Nilai
Jejak / Pemecahan Masalah Verbositas 0
Informasi Informasi 1
Peringatan Peringatan 2
Kesalahan Kesalahan 3
Penting Penting 4

Permintaan

requests
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, name, duration, resultCode, success

Cuplikan layar hasil kueri untuk permintaan aplikasi pembuat API Data di Application Insights.

Pengecualian

exceptions
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, type, outerMessage, details

Cuplikan layar hasil kueri untuk pengecualian penyusun API Data di Application Insights.

Filter menurut versi DAB

traces
| where customDimensions["Component.Version"] == "1.2.3"
| project timestamp, message, severityLevel

Menemukan kueri GraphQL yang lambat

requests
| where name contains "/graphql"
| where duration > 1000
| project timestamp, name, duration, resultCode
| order by duration desc

Tingkat keberhasilan permintaan

requests
| where customDimensions["ProductName"] startswith "dab-"
| summarize 
    Total = count(),
    Success = countif(success == true),
    Failed = countif(success == false)
| extend SuccessRate = (Success * 100.0) / Total

Operasi database paling lambat teratas

dependencies
| where type == "SQL" or type == "Azure Cosmos DB"
| top 10 by duration desc
| project timestamp, name, duration, target, data

Metrik Langsung

Metrik Langsung menyediakan pemantauan waktu nyata dengan <latensi 1 detik. Application Insights memungkinkannya secara otomatis saat dikonfigurasi.

Mengakses Metrik Langsung

  1. Buka sumber daya Application Insights Anda di portal Microsoft Azure.
  2. Navigasi ke Metrik Langsung di menu sebelah kiri.
  3. Mulai aplikasi DAB Anda.
  4. Dalam hitungan detik, data real-time muncul.

Cuplikan layar halaman metrik langsung untuk data penyusun API Data di Application Insights.

Apa yang Anda lihat

Ukuran Deskripsi
Permintaan Masuk Permintaan REST/GraphQL per detik
Permintaan Keluar Panggilan database per detik
Kesehatan Keseluruhan Tingkat keberhasilan, kegagalan per detik
Memori / CPU Pemakaian sumber daya
Tingkat Pengecualian Pengecualian per detik

Petunjuk / Saran

Gunakan Metrik Langsung selama pengembangan untuk melihat umpan balik langsung tentang permintaan API dan operasi database.

Pengambilan sampel dan retensi data

Pengambilan sampel adaptif

Application Insights SDK secara otomatis mengambil sampel telemetri ketika volume tinggi untuk mengurangi biaya dan tetap dalam batas tarif. Laju pengambilan sampel ditampilkan di UI Application Insights.

Perilaku default:

  • Lalu lintas rendah: Semua data telemetri dikirim (100%)
  • Lalu lintas tinggi: Pengambilan sampel secara otomatis mengurangi volume
  • Data representatif dikelola

Retensi data

Plan Retensi default Retensi maksimum
Tingkatan gratis 90 hari 90 hari
Pay-as-you-go 90 hari 730 hari (dua tahun)

Mengonfigurasi retensi: Penggunaan → Application Insights dan perkiraan biaya → Retensi Data.

Pertimbangan performa

Overhead telemetri

Application Insights menambahkan overhead minimal.

  • Memori: ~10-50 MB tergantung pada lalu lintas
  • CPU: <1% di bawah beban normal
  • Latensi: <1 ms per permintaan (asinkron)

Praktik terbaik

  • Gunakan variabel lingkungan untuk string koneksi.
  • Nonaktifkan dalam pengembangan lokal jika tidak diperlukan.
  • Pantau laju pengambilan sampel dalam produksi.
  • Atur retensi data yang sesuai untuk mengelola biaya.

Nonaktifkan dalam pengembangan

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": false
      }
    }
  }
}

Ekspor dan visualisasi

Telemetri diekspor melalui Application Insights SDK. SDK melakukan batch dan mengirim data secara berkala.

Nota

SDK mengontrol waktu ekspor. Perilaku bawaan mengirimkan telemetri secara berkelompok setiap beberapa detik.

Peringatan

Kontainer sementara yang mati dengan cepat dapat keluar sebelum ekspor selesai. Konfigurasikan jendela matikan yang anggun dan hindari penghentian agresif untuk memastikan flush telemetri yang tertunda.

String koneksi vs. kunci instrumentasi

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=https://eastus.in.applicationinsights.azure.com/"
}

Keuntungan:

  • Titik akhir khusus wilayah (latensi yang lebih rendah)
  • Mendukung sovereign cloud
  • Tahan Masa Depan (pendekatan yang direkomendasikan Microsoft)

Kunci instrumentasi lama

Meskipun masih didukung, Microsoft merekomendasikan string koneksi untuk implementasi baru.

{
  "connection-string": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}

Nota

Jika Anda hanya memberikan kunci instrumentasi, Application Insights menggunakan titik akhir penyerapan global, yang mungkin memiliki latensi yang lebih tinggi.

Troubleshooting

Kesalahan: "String koneksi Application Insights tidak boleh null atau kosong jika diaktifkan"

Penyebab: enabled diatur ke true tetapi connection-string hilang atau kosong.

Solusi: Berikan string koneksi yang valid saat mengaktifkan Application Insights, atau atur enabled ke false.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

DAB telah dimulai tetapi telemetri tidak muncul

Periksa log startup untuk pesan-pesan ini:

dab start --LogLevel Information

Pesan keberhasilan:

Application Insights telemetry is enabled with connection string from config.

Pesan peringatan:

Logs won't be sent to Application Insights because an Application Insights connection string is not available in the runtime config.

Application Insights are disabled.

Pesan kesalahan:

Telemetry client is not initialized.

Memverifikasi variabel lingkungan

echo $app-insights-connection-string

Uji dengan string koneksi langsung

Gunakan string koneksi langsung untuk sementara (bukan variabel lingkungan) untuk memverifikasi string valid:

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=..."
}

Jika pengujian ini berfungsi, masalahnya adalah dengan pemuatan variabel lingkungan.

Konten terkait

  • Last updated on